会话-Cookie
[TOC]
概述
客户端状态保持
HTTP 协议本身是无状态的(Stateless),即服务端默认将每一次 HTTP 请求视为完全独立的事务,无法在多次请求之间直接识别是否来自同一客户端。为了在多次请求间维持客户端的上下文身份或偏好配置,Web 体系引入了基于客户端存储的会话跟踪机制——Cookie。
Cookie 本质上是由服务端生成并下发给客户端浏览器的一小段文本数据(以 name=value 键值对为核心,附带生命周期、作用域及安全控制等元数据属性)。浏览器将其保存在本地内存或磁盘中,并在后续访问符合作用域条件的 URL 时,自动将这些键值对随请求一并回传给服务端,从而实现跨请求的状态识别。
| 维度 | 客户端 Cookie | 服务端 Session |
|---|---|---|
| 存储位置 | 客户端浏览器(内存或本地磁盘文件) | 服务端容器内存(或外部持久化存储) |
| 数据容量 | 单个 Cookie 通常不超过 4KB,单域名数量受限 | 容量取决于服务端内存控制,可存放复杂对象 |
| 带宽开销 | 每次匹配请求均在 HTTP 请求头中携带,占用网络带宽 | 仅通过请求头传递轻量级会话标识(如 JSESSIONID) |
| 安全性 | 明文暴露于客户端,存在被篡改或窃取的风险 | 数据留在服务端,客户端仅持有随机散列凭据 |
报头交互机制
在底层协议层面,Cookie 的下发与回传完全依赖 HTTP 响应报头 Set-Cookie 与 HTTP 请求报头 Cookie 的配对协作。

一次完整的客户端状态建立与识别包含以下四个阶段:
客户端发起首次请求:浏览器向服务端目标 Servlet 发起常规的
HTTP Request,此时本地尚未存储该站点的 Cookie,请求头中不包含Cookie字段。服务端下发状态指令:Servlet 在处理业务时构建 Cookie 数据,容器将其序列化为
Set-Cookie响应报头,随HTTP Response返回给客户端。浏览器本地存储并自动回传:浏览器解析响应中的
Set-Cookie报头,将键值对及附属属性保存至本地;当浏览器再次向该站点发起符合路径与域名规则的请求时,会自动构造Cookie请求报头将键值回传给服务端。服务端识别客户端状态:容器解析请求中的
Cookie报头,将其还原为可读的数据结构供 Servlet 消费,并据此生成对应的HTTP Response。sh# 1. 服务端响应报头:通知浏览器保存键值对 HTTP/1.1 200 OK Set-Cookie: theme=light # 2. 客户端后续请求报头:自动回传已保存的键值对 GET /index HTTP/1.1 Cookie: theme=light
Servlet 组件协作架构
为了屏蔽底层 HTTP 报头字符串的拼接与解析细节,Servlet 规范在 javax.servlet.http(Jakarta EE 9+ 为 jakarta.servlet.http)包中提供了面向对象的 Cookie 封装类,并通过 HttpServletRequest 与 HttpServletResponse 两个核心接口完成读写解耦。
从下述 UML 类图可以清晰地看出核心组件间的职责边界与关联关系:
数据载体(
Cookie):独立封装单个 Cookie 的键名(name)、键值(value)以及有效期、路径、域名等控制属性,实现了Cloneable与Serializable接口。下发通道(
HttpServletResponse):与Cookie建立关联,对外暴露void addCookie(Cookie)方法,负责将 Java 层的Cookie实例转换为响应流中的Set-Cookie报头。读取通道(
HttpServletRequest):与Cookie建立关联,对外暴露Cookie[] getCookies()方法,负责将请求流中的Cookie报头解析并组装为Cookie对象数组。业务调度(
HttpServlet):在service或doGet、doPost方法中同时持有HttpServletRequest与HttpServletResponse引用,完成业务层的状态读取与下发编排。

标准读写流程
Cookie
在 Servlet 中创建 Cookie 必须调用其双参构造器 new Cookie(String name, String value)。根据 RFC 6265 规范与 Servlet 容器校验规则:
键名不可变性:
Cookie类仅提供getName()而未提供setName()方法,键名一旦通过构造器指定即不可修改。键值可变性:创建实例后,可通过
setValue(String newValue)动态更新其内存值,并通过getValue()读取当前值。命名字符约束:
name与value默认仅支持 ASCII 可打印字符,且不能包含分号(;)、逗号(,)、等号(=)以及空格或制表符等分隔符,否则在实例化或写入响应时会抛出IllegalArgumentException。
addCookie
服务端向客户端写入 Cookie 时,需调用 HttpServletResponse 的 addCookie 方法。
多值追加机制:
addCookie可以被连续调用多次,每次调用都会在 HTTP 响应中独立追加一行Set-Cookie报头,互不覆盖。同名覆盖规则:若服务端下发了一个与浏览器本地已存在 Cookie 具有相同
name、相同path且相同domain的新 Cookie,浏览器会直接用新value覆盖本地原有的旧值。提交时机限制:由于 Cookie 存储在 HTTP 响应头中,
addCookie必须在响应体(Response Body)正式提交(Committed)并刷新至客户端之前调用;若响应流已关闭或缓冲区已刷出,后续调用将无法生效。java// 1. 实例化 Cookie 对象,指定键名与初始键值 Cookie themeCookie = new Cookie("theme", "dark"); // 2. 如需更新键值,可通过 setValue 覆盖原值 themeCookie.setValue("light"); // 3. 将 Cookie 写入响应报头 Set-Cookie 并下发客户端 response.addCookie(themeCookie);
getCookies
服务端读取客户端回传的 Cookie 时,需调用 HttpServletRequest 的 getCookies 方法。
批量返回数组:Servlet API 未提供按名称直接获取单个 Cookie 的方法,而是通过
getCookies()一次性返回请求头中携带的所有Cookie[]数组,需由开发者自行遍历并比对getName()。空指针防御:当客户端首次访问站点或本地没有任何匹配当前路径的 Cookie 时,请求头中不含
Cookie字段,此时request.getCookies()返回的是null而非长度为 0 的空数组。因此在遍历前必须进行非空判断,否则会直接触发NullPointerException。请求头信息损耗:浏览器回传的
Cookie请求头仅包含name=value键值对,不会回传maxAge、path、domain、httpOnly等属性;因此在服务端通过getCookies()获取的实例上调用getMaxAge()等方法只能得到默认值(如-1),无法反映浏览器的真实剩余有效期。java// 1. 从请求报头中提取客户端回传的全部 Cookie 数组 Cookie[] cookies = request.getCookies(); // 2. 必须先执行非空校验,避免无 Cookie 时触发空指针异常 if (cookies != null) { for (Cookie cookie : cookies) { // 3. 按键名匹配目标项并读取对应键值 if ("theme".equals(cookie.getName())) { String theme = cookie.getValue(); response.getWriter().write("Current theme: " + theme); break; } } }
URLEncoder
当需要在 Cookie 中存储中文字符串、空格或特殊符号(如 ;、,)时,由于底层 RFC 规范对报头字符集的严格限制,直接传入会引发容器报头序列化异常或乱码。标准做法是在写入前使用 java.net.URLEncoder 将字符串转换为百分号编码(Percent-Encoding),并在读取后使用 java.net.URLDecoder 按相同字符集还原。
// 1. 下发前对包含中文或特殊字符的值执行 UTF-8 URL 编码
String encodedCity = URLEncoder.encode("上海市", StandardCharsets.UTF_8);
Cookie cityCookie = new Cookie("city", encodedCity);
response.addCookie(cityCookie);
// 2. 读取时对获取到的编码字符串执行 UTF-8 URL 解码
String rawValue = cityCookie.getValue();
String decodedCity = URLDecoder.decode(rawValue, StandardCharsets.UTF_8);API: Cookie
构造方法
CookieCookie():(String name, String value),键值对构造。使用指定的不可变键名name与初始键值value构建一个Cookie实例,默认存活时间maxAge为-1(会话级内存存储),且未绑定特定域名或路径。
注意事项:
- 键名字符合规校验:
Cookie构造器在初始化时会通过内部CookieNamingValidator(基于 RFC 2109 / RFC 6265 Token 规范)严格校验name参数。name不能为空字符串或null,必须全部由 ASCII 字符组成,且严禁包含逗号(,)、分号(;)、空格、制表符等分隔符,也不能以$字符开头(如$Version),否则直接抛出IllegalArgumentException。- 保留字与中文限制:
name不能与Comment、Discard、Domain、Expires、Max-Age、Path、Secure、Version等标准协议属性名重名;若需在name或value中存放中文或空格,必须在传入构造器前使用URLEncoder.encode(str, StandardCharsets.UTF_8)进行百分号编码。
import javax.servlet.http.Cookie;
public class CookieConstructorExample {
public static void main(String[] args) {
// 1. 使用合法的 ASCII 键名与键值实例化 Cookie 对象
Cookie themeCookie = new Cookie("theme", "dark");
System.out.println("Cookie 实例化成功: " + themeCookie.getName() + "=" + themeCookie.getValue());
try {
// 2. 传入包含分号等 RFC 6265 禁用分隔符的键名将触发 IllegalArgumentException
Cookie invalidCookie = new Cookie("invalid;name", "value");
} catch (IllegalArgumentException e) {
System.out.println("非法键名拦截: " + e.getMessage());
}
}
}键值操作
StringgetName():(),键名读取。返回当前Cookie实例在构造时绑定的键名字符串;键名一旦创建即不可更改,类定义中未提供对应的setName()方法。StringgetValue():(),键值读取。返回当前Cookie实例绑定的键值字符串。voidsetValue():(String newValue),键值更新。在将Cookie写入响应流之前,动态赋予或覆盖当前实例的键值字符串。Objectclone():(),副本克隆。重写Object.clone()方法并将访问权限提升为public,创建并返回当前Cookie实例的浅拷贝副本(Servlet 6.0 中同时深拷贝内部的扩展属性映射表)。booleanequals():(Object obj),相等性判定。在 Servlet 6.0(Jakarta EE 10)中重写,当两个Cookie实例的name(区分大小写)、path(区分大小写)以及domain(不区分大小写)三元组完全相同时返回true。inthashCode():(),哈希码计算。在 Servlet 6.0(Jakarta EE 10)中重写,基于name、domain(转小写)与path三个核心唯一标识字段计算散列值。
注意事项:
- 二进制与特殊字符编码:
setValue(String)虽然在 Java 对象赋值阶段不会立即校验字符集,但在调用response.addCookie(cookie)触发容器Rfc6265CookieProcessor序列化报头时,若值中包含空格、双引号、分号或逗号,会抛出IllegalArgumentException。存放复杂结构建议先执行 Base64 或 URL 编码。- 版本相等性差异:在 Servlet 5.0 及更早期的
javax.servlet.http.Cookie中,Cookie未重写equals和hashCode,直接沿用Object的内存引用地址比对;升级至 Servlet 6.0(jakarta.servlet.http.Cookie)后才改为按(name, domain, path)三元组比对。
import javax.servlet.http.Cookie;
public class CookieKeyValueExample {
public static void main(String[] args) {
// 1. 创建 Cookie 并读取不可变键名与初始键值
Cookie original = new Cookie("lang", "zh-CN");
System.out.println("初始键值: " + original.getName() + "=" + original.getValue());
// 2. 动态更新当前 Cookie 实例的键值内容
original.setValue("en-US");
System.out.println("更新后键值: " + original.getValue());
// 3. 克隆独立副本并修改副本键值,验证原对象不受影响
Cookie copied = (Cookie) original.clone();
copied.setValue("ja-JP");
System.out.println("原对象值: " + original.getValue() + ", 副本对象值: " + copied.getValue());
}
}作用域配置
voidsetMaxAge():(int expiry),存活时长设置。以秒为单位设置Cookie在客户端的最大存活时间:正数表示持久化写入磁盘的秒数,负数表示仅驻留浏览器内存并在关闭浏览器时销毁,零(0)表示通知浏览器立即删除该同名同作用域条目。intgetMaxAge():(),存活时长读取。返回当前Cookie实例设置的最大存活秒数;若未设置或从客户端请求头反序列化而来,默认返回-1。voidsetDomain():(String domain),域名范围设置。指定客户端应向哪些域名回传该Cookie(对应Set-Cookie中的Domain属性),方法内部会自动通过Locale.ENGLISH将传入的域名转换为全小写形式。StringgetDomain():(),域名范围读取。返回当前实例配置的域名字符串;若未配置或由客户端请求头解析生成,返回null。voidsetPath():(String uri),路径前缀设置。指定客户端触发回传该Cookie的 URL 路径前缀(对应Set-Cookie中的Path属性),传入的路径必须以/开头。StringgetPath():(),路径前缀读取。返回当前实例绑定的路径前缀字符串;若未配置或由客户端请求头解析生成,返回null。
注意事项:
- 请求端元数据丢失:客户端发送的
Cookie请求报头仅携带name=value键值对,不包含Max-Age、Domain或Path属性。因此对request.getCookies()获取的实例调用getMaxAge()恒返回-1,调用getDomain()和getPath()恒返回null。- 删除操作作用域对齐:调用
setMaxAge(0)销毁客户端已有 Cookie 时,必须同步调用setPath(以及必要的setDomain)使其与原 Cookie 下发时的路径和域名完全一致,否则浏览器会将其视为不同作用域的新条目而无法清除原记录。
import javax.servlet.http.Cookie;
public class CookieScopeLifecycleExample {
public static void main(String[] args) {
// 1. 配置父级域名(内部自动转换为全小写形式)并校验读取结果
Cookie ssoCookie = new Cookie("ssoToken", "tk_9012");
ssoCookie.setDomain("EXAMPLE.COM");
System.out.println("绑定域名: " + ssoCookie.getDomain());
// 2. 配置应用级路径前缀并读取当前路径作用域
ssoCookie.setPath("/portal");
System.out.println("绑定路径: " + ssoCookie.getPath());
// 3. 设置持久化存活时长为 3600 秒(1 小时)并读取有效期
ssoCookie.setMaxAge(3600);
System.out.println("存活秒数: " + ssoCookie.getMaxAge());
}
}安全控制
voidsetHttpOnly():(boolean isHttpOnly),脚本隔离设置。自 Servlet 3.0 起引入,设置为true时在响应头中追加; HttpOnly标记,禁止客户端通过document.cookie等脚本 API 读取或篡改该Cookie,以缓解跨站脚本(XSS)窃取风险。booleanisHttpOnly():(),脚本隔离判定。判断当前Cookie实例是否开启了HttpOnly保护,默认返回false。voidsetSecure():(boolean flag),加密传输设置。设置为true时在响应头中追加; Secure标记,指示浏览器仅在使用 HTTPS 或 SSL/TLS 等安全加密通道发起请求时才回传该Cookie。booleangetSecure():(),加密传输判定。判断当前Cookie实例是否要求仅在安全加密通道下传输,默认返回false。
注意事项:
- 命名风格差异:由于历史版本演进原因,Servlet 1.0 定义的加密检查方法名为
getSecure(),而 Servlet 3.0 新增的脚本隔离检查方法名为isHttpOnly(),调用时需注意两者的前缀差异。- 回传布尔值重置:与作用域属性一致,客户端请求头不会回传
; Secure和; HttpOnly标记,因此从request.getCookies()获取的实例调用getSecure()和isHttpOnly()均固定返回false。
import javax.servlet.http.Cookie;
public class CookieSecurityExample {
public static void main(String[] args) {
// 1. 开启 HttpOnly 属性以阻断客户端脚本通过 document.cookie 读取
Cookie authCookie = new Cookie("SESSIONID", "9A8B7C6D");
authCookie.setHttpOnly(true);
System.out.println("是否开启 HttpOnly 隔离: " + authCookie.isHttpOnly());
// 2. 开启 Secure 属性以限制浏览器仅在 HTTPS 加密通道下传输
authCookie.setSecure(true);
System.out.println("是否强制 HTTPS 传输: " + authCookie.getSecure());
}
}扩展属性
voidsetAttribute():(String name, String value),通用属性设置。自 Servlet 6.0(Jakarta EE 10)起新增,用于向Cookie注入任意标准或扩展报头属性(如SameSite、Partitioned);当传入Max-Age、Domain、Path、Secure、HttpOnly等已知属性名(忽略大小写)时,内部会自动联动更新对应的强类型字段,传入value为null则移除该属性。StringgetAttribute():(String name),通用属性读取。自 Servlet 6.0 起新增,按属性名称(忽略大小写)获取绑定的属性值字符串;若属性不存在则返回null。Map<String, String>getAttributes():(),属性映射获取。自 Servlet 6.0 起新增,返回当前Cookie实例配置的所有属性(包括Domain、Max-Age、Path以及通过setAttribute添加的自定义属性)的不可变Map视图。voidsetComment():(String purpose),注释说明设置。设置描述该Cookie用途的注释文本(对应早期 RFC 2109 的Comment属性);因现行 RFC 6265 规范已移除Comment属性,该方法在 Servlet 6.0 中已被标记为@Deprecated(forRemoval = true),调用不产生任何效果。StringgetComment():(),注释说明读取。返回当前Cookie的注释文本或null;在 Servlet 6.0 中已标记为@Deprecated(forRemoval = true)并固定返回null。voidsetVersion():(int v),协议版本设置。设置遵循的 Cookie 协议版本号(0代表 Netscape 规范,1代表 RFC 2109 规范);因现代容器统一遵循 RFC 6265,该方法在 Servlet 6.0 中已标记为@Deprecated(forRemoval = true),调用不产生任何效果。intgetVersion():(),协议版本读取。返回当前Cookie的协议版本号;在 Servlet 6.0 中已标记为@Deprecated(forRemoval = true)并固定返回0。
注意事项:
- Servlet 6.0 底层存储重构:在 Jakarta Servlet 6.0 的
Cookie源码中,maxAge、domain、path、secure、httpOnly等傳統 setter/getter 已全部重构为委托给内部的Map<String, String> attributes(基于TreeMap(String.CASE_INSENSITIVE_ORDER))存取,从而实现了setMaxAge(3600)与getAttribute("Max-Age")的双向互通。- 无值标志属性约定:若需通过
setAttribute设置类似Partitioned这类在Set-Cookie报头中仅有属性名而无=value的标记属性,可将第二个参数传入空字符串""(即cookie.setAttribute("Partitioned", ""))。
import jakarta.servlet.http.Cookie;
import java.util.Map;
public class CookieAttributeExample {
public static void main(String[] args) {
// 1. 使用 Servlet 6.0 setAttribute 配置 SameSite 等扩展报头属性
Cookie cookie = new Cookie("csrfToken", "c_7712");
cookie.setAttribute("SameSite", "Strict");
cookie.setAttribute("Partitioned", "");
// 2. 按属性名忽略大小写读取单个扩展属性值
String sameSite = cookie.getAttribute("samesite");
System.out.println("SameSite 策略: " + sameSite);
// 3. 获取全部属性只读映射视图(包含标准属性与自定义扩展属性)
Map<String, String> attrs = cookie.getAttributes();
System.out.println("当前全部属性映射: " + attrs);
}
}MaxAge 生命周期
在 Servlet 规范中,客户端 Cookie 的存活时长并非永久有效,而是由 Cookie 类的 maxAge 属性(单位为秒)全权控制。容器在调用 HttpServletResponse.addCookie(Cookie) 生成响应报头时,会根据 maxAge 的正负与零值状态,决定浏览器将该 Cookie 存入运行内存、持久化至本地磁盘,或是立即从客户端存储中抹除。
状态流转模型
Cookie 从服务端创建、下发至客户端存储,再到最终失效销毁,遵循明确的状态流转边界。

如上图所示,当 Web Server 通过 Set-Cookie 报头将 Cookie 下发给 Client Browser 后,浏览器的存储引擎会根据报头中是否携带过期指令,将其分流至两条截然不同的生命周期轨道:
创建与下发态(Created & Issued):Servlet 调用
new Cookie(name, value)实例化对象,此时maxAge默认初始化为-1。开发者可在调用response.addCookie(cookie)之前通过setMaxAge(int expiry)显式修改其生命周期策略。客户端驻留态(Browser Stored):
- 会话级驻留(Session Cookie):当
maxAge为负数时,浏览器仅将 Cookie 保存在当前进程的运行内存中;只要浏览器未彻底关闭,每次符合作用域的后续请求都会携带该 Cookie。 - 持久化驻留(Persistent Cookie):当
maxAge为正数时,浏览器将 Cookie 序列化写入本地磁盘文件,并记录到期时间戳;即便关闭浏览器甚至重启操作系统,只要未到达失效时间,后续请求依然会自动回传。
- 会话级驻留(Session Cookie):当
销毁态(Expired & Removed):当会话级 Cookie 遭遇浏览器进程关闭、持久化 Cookie 的倒计时归零,或服务端显式下发
maxAge为0的同名同路径覆盖指令时,浏览器会立即将该条目从内存或磁盘中清除,后续请求不再携带。
maxAge 取值范围 | 生命周期分类 | 客户端存储介质 | Set-Cookie 报头体现 | 销毁触发条件 |
|---|---|---|---|---|
负数(小于 0,默认 -1) | 会话级 Cookie | 浏览器运行内存 | 不含 Max-Age 与 Expires 属性 | 整个浏览器进程关闭时自动销毁 |
| 正数(大于 0,单位:秒) | 持久化 Cookie | 客户端本地磁盘 | 包含 Max-Age=秒数(或 Expires) | 倒计时秒数耗尽后由浏览器自动清理 |
| 零值(等于 0) | 立即销毁指令 | 不存储(直接移除) | 包含 Max-Age=0(Expires 设为纪元初) | 浏览器接收到响应报头的瞬间立即移除 |
setMaxAge
Cookie 类通过 public void setMaxAge(int expiry) 方法配置 Cookie 的最大存活秒数。根据传入整型参数的正负与零值差异,容器与浏览器会执行三种不同的生命周期策略。
会话级内存存活
当 setMaxAge 传入负数(例如 -1),或者创建 Cookie 实例后完全不调用 setMaxAge 方法(源码中 private int maxAge = -1 为默认初始值)时,该 Cookie 被标记为会话级(Session Cookie)。
报头省略机制:Servlet 容器在序列化
maxAge小于 0 的 Cookie 时,不会在Set-Cookie响应头中输出Max-Age或Expires字段。内存级隔离:浏览器解析到不含过期属性的
Set-Cookie报头后,将其保存在进程内存中。需要注意,仅关闭单个标签页(Tab)不会触发销毁,必须彻底退出整个浏览器应用程序进程,内存中的会话级 Cookie 才会被回收(服务端HttpSession默认依赖的JSESSIONID即采用此模式)。java// 1. 创建会话级 Cookie(默认 maxAge 即为 -1) Cookie sessionCookie = new Cookie("tempToken", "a8f9d2"); // 2. 显式设置为负数,仅保存在浏览器运行内存中 sessionCookie.setMaxAge(-1); // 3. 写入响应头,生成不含过期属性的 Set-Cookie 报头 response.addCookie(sessionCookie);
持久化磁盘存活
当 setMaxAge 传入正整数(大于 0)时,参数值代表该 Cookie 从服务端生成响应时刻算起允许存活的秒数(注意单位是秒,而非毫秒)。
磁盘落盘机制:浏览器收到带有正数有效期的响应后,会将该 Cookie 写入操作系统本地磁盘的专用数据库(如 Chromium 内核的 SQLite
Cookies文件)。跨会话保留:在倒计时归零之前,无论用户关闭标签页、退出浏览器还是重启计算机,再次打开浏览器访问匹配站点时,浏览器都会从磁盘加载该 Cookie 并随请求头发送。
java// 1. 创建需要跨浏览器关闭保留的偏好 Cookie Cookie rememberCookie = new Cookie("rememberUser", "zhangsan"); // 2. 设置存活时间为 7 天(60 秒 * 60 分钟 * 24 小时 * 7 天 = 604800 秒) rememberCookie.setMaxAge(60 * 60 * 24 * 7); // 3. 下发响应,容器自动追加 Max-Age=604800 属性 response.addCookie(rememberCookie);
零值立即销毁
Servlet API 并未在 HttpServletResponse 中提供类似 removeCookie 或 deleteCookie 的专用删除方法。若服务端需要主动清除客户端已保存的某个 Cookie(例如用户点击“退出登录”时清理自动登录凭证),标准做法是下发一个 maxAge 等于 0 的同名 Cookie 进行覆盖淘汰。
三要素严格一致:浏览器通过
name + domain + path三个维度唯一标识一条 Cookie 记录。因此,用于删除的 Cookie 不仅键名(name)必须与原 Cookie 完全相同,其路径(path)和域名(domain)也必须与原 Cookie 下发时的配置严格吻合;若未显式对齐path,浏览器会将其视为另一个路径下的新 Cookie,导致原 Cookie 无法被删除。零值覆盖淘汰:当
setMaxAge(0)随响应下发后,浏览器匹配到本地同标识的条目,看到有效期为 0 秒,便会立即将其从内存或磁盘中物理移除。java// 1. 构造与待删除目标同名且值为空的 Cookie 实例 Cookie deleteCookie = new Cookie("rememberUser", ""); // 2. 必须保持与原 Cookie 完全一致的 path 作用域,否则浏览器视为不同项 deleteCookie.setPath(request.getContextPath()); // 3. 将存活时间设为 0,触发浏览器立即清除机制 deleteCookie.setMaxAge(0); // 4. 写入响应头,通知客户端立即淘汰该同名同路径 Cookie response.addCookie(deleteCookie);
getMaxAge
Cookie 类提供了 public int getMaxAge() 方法用于读取当前实例设置的存活秒数。在实际开发中,该方法存在一个极易踩坑的读写不对称边界:
下发阶段可读:在服务端刚刚创建
Cookie并调用setMaxAge(3600)后,紧接着在同一请求周期内调用cookie.getMaxAge(),可以正常返回3600。**回传阶段恒为
-1**:当浏览器在后续请求中通过Cookie: rememberUser=zhangsan请求头将数据回传给服务端时,HTTP 请求头仅传输name=value键值对,完全不包含Max-Age、Path、Domain等元数据属性。容器在解析请求头并调用new Cookie(name, value)组装request.getCookies()数组时,所有对象的maxAge均保持默认值-1。因此,服务端无法通过getMaxAge()获知客户端某个 Cookie 还剩余多少秒过期。java// 1. 读取客户端请求头回传的 Cookie 数组 Cookie[] cookies = request.getCookies(); if (cookies != null) { for (Cookie cookie : cookies) { // 2. 请求头不含生命周期元数据,此处返回值恒为默认的 -1 int maxAge = cookie.getMaxAge(); } }
响应报头指令映射
在 HTTP 协议演进过程中,控制 Cookie 过期时间先后出现了 Expires 与 Max-Age 两个响应报头属性。Servlet 容器在底层通过 CookieProcessor 将 Java 层的 maxAge 数值转换为标准报头指令:
# 1. 负数(maxAge = -1):不输出任何过期属性,作为会话级 Cookie
Set-Cookie: tempToken=a8f9d2
# 2. 正数(maxAge = 604800):输出相对秒数,兼容模式下可能附带 Expires
Set-Cookie: rememberUser=zhangsan; Max-Age=604800; Expires=Thu, 05 Nov 2026 09:08:00 GMT
# 3. 零值(maxAge = 0):输出 Max-Age=0 或纪元起始时间,指令浏览器立即删除
Set-Cookie: rememberUser=; Path=/app; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:10 GMTMax-Age
Max-Age 是 RFC 2109 引入并在现行标准 RFC 6265 中成为首选的生命周期属性,表示从客户端接收到响应那一刻起计算的相对存活秒数。
规避时钟偏差:由于
Max-Age采用相对时长倒计时,即使客户端操作系统的本地系统时间被人为调快或调慢,也不会影响 Cookie 在客户端的实际存活时长。最高优先级:根据 RFC 6265 规范,若同一个
Set-Cookie报头中同时出现了Max-Age与Expires属性,现代浏览器一律优先采纳Max-Age的值,并忽略Expires。
Expires
Expires 是早期 Netscape 规范定义的属性,采用 GMT(格林尼治标准时间)格式的绝对时间戳(如 Thu, 05 Nov 2026 09:08:00 GMT)指定过期时刻。
客户端时钟依赖:浏览器通过对比本地系统时钟与
Expires的绝对时间来判断是否过期。若服务端时钟与客户端系统时钟存在较大偏差,会导致 Cookie 提前失效或延期驻留。零值兼容转换:在 Tomcat 等容器实现的
Rfc6265CookieProcessor中,当开发者调用setMaxAge(0)时,为了兼容部分旧版客户端,容器除了处理Max-Age=0外,还会将Expires格式化为一个早已过去的 Unix 纪元起始时间常量(Thu, 01 Jan 1970 00:00:10 GMT),确保任何客户端收到后均判定为已过期并立即清理。
滑动续期机制
与服务端 HttpSession 每次访问自动重置空闲超时时间的默认行为不同,持久化 Cookie 的过期时间自下发那一刻起就是静态固定的。如果一个 Cookie 设置了 setMaxAge(1800)(30 分钟),即便用户在这 30 分钟内高频点击页面,只要服务端没有重新下发 Set-Cookie,该 Cookie 依然会在第 30 分钟整准时失效。

为了实现类似上图的滑动过期(Sliding Expiration)效果,服务端需要在接收到请求时,将目标 Cookie 重新设置 maxAge 并再次调用 response.addCookie(cookie) 下发,用新的倒计时覆盖浏览器本地的旧倒计时:
// 1. 遍历请求中的 Cookie,定位需要续期的会话凭证
Cookie[] cookies = request.getCookies();
if (cookies != null) {
for (Cookie cookie : cookies) {
if ("authToken".equals(cookie.getName())) {
// 2. 重新赋予 1800 秒(30 分钟)的存活周期并保持原有路径
cookie.setMaxAge(1800);
cookie.setPath(request.getContextPath());
// 3. 重新写入响应报头,覆盖浏览器本地旧的到期时间
response.addCookie(cookie);
break;
}
}
}Cookie 作用域匹配
浏览器本地可能同时存储来自数百个不同站点、不同业务模块的数千条 Cookie。为了防止客户端在发起 HTTP 请求时将无关站点的敏感凭据泄露给第三方服务器,或者将仅用于后台管理模块的 Cookie 无谓地附加到前台静态资源请求中,RFC 6265 规范与 Servlet Cookie 类共同定义了由域名(Domain)与路径(Path)组成的双维作用域裁剪机制。
双维裁剪模型
在浏览器的存储引擎(Cookie Jar)内部,单条 Cookie 的唯一性并非仅由键名(name)决定,而是由 (name, domain, path) 三元组联合主键共同标识。每当浏览器准备向目标 URL 发起 HTTP 请求时,都会遍历本地存储列表,依次执行域名校验与路径校验;只有两个维度同时匹配成功的 Cookie,才会被序列化至 Cookie 请求报头中发送给服务端。
| 作用域维度 | 控制方法 | 响应报头属性 | 缺省默认行为 | 匹配核心规则 |
|---|---|---|---|---|
| 域名作用域 | setDomain(String) | Domain | 启用 Host-Only 标记,仅限当前精确主机名 | 请求主机名与 Domain 完全相等,或以 .Domain 为后缀的各级子域名 |
| 路径作用域 | setPath(String) | Path | 取签发该 Cookie 的请求 URI 所在的父级目录 | 请求 URI 路径与 Path 完全相等,或以 Path 为目录级前缀的子路径 |
# 1. 服务端下发全站子域共享 Cookie 与特定模块路径 Cookie
HTTP/1.1 200 OK
Set-Cookie: ssoToken=t_01; Domain=example.com; Path=/
Set-Cookie: traceId=tr_99; Path=/Example/cookie
# 2. 客户端向匹配子域名与子路径的目标资源发起请求
GET /Example/cookie/a/index.jsp HTTP/1.1
Host: www.example.com
# 3. 路径更长的 traceId 排在前面,路径较短的 ssoToken 排在后面
Cookie: traceId=tr_99; ssoToken=t_01路径作用域
路径作用域用于在同一台主机(或同一域名体系)内部,按 URL 目录层级隔离不同 Web 应用或不同业务子模块的 Cookie。
默认父目录绑定
如果在 Servlet 中实例化 Cookie 后未调用 setPath 方法(即 path 属性保持 null),容器在生成 Set-Cookie 响应报头时不会输出 Path 属性。此时浏览器会自动将该 Cookie 的默认路径计算为当前请求 URI 除去末尾资源名后的父目录路径:
默认目录截取:若客户端访问
http://localhost:8080/Example/cookie/loginServlet时服务端下发了未指定Path的 Cookie,浏览器会自动将其路径绑定为/Example/cookie。向上隔离与向下穿透:该 Cookie 仅对
/Example/cookie及其下属子目录(如/Example/cookie/a/index.jsp)可见;若浏览器转而访问上级目录/Example/index.jsp或同级兄弟目录/Example/order/list,则不会携带该 Cookie。

结合上图所示的场景,假设浏览器本地已针对 localhost 存储了三条路径各异的 Cookie:
Cookie1的路径配置为/Example/cookieCookie2的路径配置为/Example/Cookie3的路径配置为/Example1/cookie
当浏览器向 http://localhost:8080/Example/cookie/a/index.jsp 发起请求时,目标请求路径 /Example/cookie/a/index.jsp 同时是 /Example/cookie(Cookie1)与 /Example/(Cookie2)的子路径,而与 /Example1/cookie(Cookie3)不匹配。因此,浏览器最终仅将 Cookie1 和 Cookie2 归还给服务器。
setPath
Cookie 类提供 public void setPath(String uri) 方法显式指定客户端回传该 Cookie 的 URL 路径前缀。传入的 uri 必须以斜杠 / 开头,且浏览器在判定是否匹配时遵循严格的目录边界前缀规则(而非单纯的字符串前缀):
目录边界约束:若
setPath("/Example")(末尾无斜杠),根据 RFC 6265 的path-match算法,只有当请求路径完全等于/Example,或者在/Example之后紧跟斜杠/(如/Example/a)时才算匹配成功;像/Example1/cookie虽然字符串以/Example开头,但因跨越了目录名边界,绝不会匹配成功。当前 Web 应用级共享:在实际企业开发中,最常见的需求是让某个 Servlet 下发的 Cookie 在当前 Web 应用的所有 Servlet 与 JSP 页面间共享。此时应传入
request.getContextPath()(例如/shop),避免因触发签发的 Servlet 位于深层子路径而导致上层路径无法读取。同容器多应用全局共享:若同一个 Tomcat 容器下部署了多个独立的 Web 应用(如
/portal与/order),需要通过 Cookie 传递公共状态,则可将路径设为服务器根路径setPath("/")。同名多路径并存与回传排序:若浏览器中同时存在键名相同但
Path不同的两条 Cookie(例如一条Path=/Example,另一条Path=/Example/cookie),当访问/Example/cookie/a/index.jsp时,两条同名 Cookie 都会被发送;浏览器会按照Path字符长度从长到短(最具体路径优先)的顺序排列在Cookie请求头中。java// 1. 创建应用级 Cookie,绑定当前 Web 应用的上下文根路径(如 /shop) Cookie appCookie = new Cookie("cartId", "c_98210"); appCookie.setPath(request.getContextPath()); // 2. 创建容器级全局 Cookie,绑定服务器根路径以跨多个 Web 应用共享 Cookie globalCookie = new Cookie("ssoTicket", "t_55109"); globalCookie.setPath("/"); // 3. 将两个不同路径作用域的 Cookie 写入响应头 response.addCookie(appCookie); response.addCookie(globalCookie);
getPath
Cookie 类提供 public String getPath() 方法用于获取当前对象绑定的路径字符串。与 getMaxAge() 类似,该方法在请求读取阶段同样存在元数据丢失现象:
下发前可读取:在服务端调用
setPath("/Example/cookie")之后,于当前响应周期内调用getPath()会原样返回"/Example/cookie"。回传后恒为空:由于浏览器发送的
Cookie请求头仅包含name=value序列,不包含; Path=...属性,因此从request.getCookies()数组取出的任何Cookie实例,调用getPath()的返回值恒为null。这也意味着当客户端因不同路径存在多个同名 Cookie 并同时回传时,服务端仅凭getName()与getPath()无法直接区分哪个值来自哪个路径,只能依赖浏览器“最长路径排在数组最前方”的默认顺序进行判断。java// 1. 下发阶段:显式设置 Path 后,同一请求周期内可正常读取该路径字符串 Cookie outbound = new Cookie("module", "order"); outbound.setPath("/Example/cookie"); String configuredPath = outbound.getPath(); // 2. 回传阶段:浏览器发送的 Cookie 请求头不含 Path 属性 Cookie[] inboundCookies = request.getCookies(); if (inboundCookies != null) { for (Cookie item : inboundCookies) { // 3. 容器解析请求头构造的实例未赋路径值,此处返回值恒为 null String requestCookiePath = item.getPath(); } }
域名作用域
域名作用域决定了浏览器在访问哪些主机名(Host)时允许携带该 Cookie,是实现同父域下多子系统单点登录(SSO)或状态共享的基础机制。
Host-Only 默认隔离
当开发者创建 Cookie 后未调用 setDomain 方法(即 domain 属性保持 null)时,容器生成的 Set-Cookie 报头不会包含 Domain 属性。浏览器收到此类报头后,会在内部为该 Cookie 开启 Host-Only(仅限当前主机) 布尔标记:
精确主机名匹配:带有
Host-Only标记的 Cookie,仅在后续请求的目标主机名与签发该 Cookie 的主机名逐字符完全一致时才会发送。子域名严格隔离:假设用户在访问
[www.judith.com](https://www.judith.com)时收到了一条未设置Domain的 Cookie,那么不仅平级子域名console.judith.com无法收到该 Cookie,就连下一级子域名sub.www.judith.com同样无法收到。
如下图所示,在现代反向代理(如 Nginx)架构中,企业常将门户站点 [www.judith.com](https://www.judith.com)(转发至项目 1)与控制台站点 console.judith.com(转发至项目 2)部署在同一个一级域名 judith.com 下。若保持默认的 Host-Only 隔离策略,用户在门户站点登录后,跳转至控制台站点时浏览器不会携带登录态 Cookie,从而导致会话断裂。

setDomain
为了打通上述同属一个一级域名的多个子站点,需调用 Cookie 类的 public void setDomain(String domain) 方法显式声明父级共享域名:
子域名通配共享:当在
[www.judith.com](https://www.judith.com)或console.judith.com下发 Cookie 时调用setDomain("judith.com"),浏览器会将该 Cookie 的Host-Only标记置为false,并允许judith.com本身以及[www.judith.com](https://www.judith.com)、console.judith.com等所有后缀匹配的二级、三级子域名共享该 Cookie。前导点号(Leading Dot)规范演进:在早期的 RFC 2109 规范中,要求
Domain必须以点号开头(如.judith.com);而在现行的 RFC 6265 规范及 Tomcat 8.5+ 默认使用的Rfc6265CookieProcessor中,前导点号已被废弃(若传入.judith.com,浏览器会自动忽略前导点号并等同于judith.com处理;若容器开启严格校验,前导点号甚至可能触发异常)。因此标准写法是直接传入不含前导点号的父域名"judith.com"。跨顶级域名与公共后缀拦截:出于安全防御考虑,浏览器严禁将
Domain设置为与当前请求主机不匹配的外部域名(例如judith.com下发的 Cookie 试图设置setDomain("google.com")会被浏览器直接丢弃);同时严禁将Domain设置为.com、.cn、.co.uk、.github.io等公共后缀(Public Suffix List),防止恶意子站点污染整个顶级域下的所有网站。端口与协议无关性:Cookie 的作用域仅校验域名与路径,不区分端口号与协议(除非额外开启
Secure属性)。在同一主机localhost下,localhost:3001与localhost:3002默认共享所有同路径的 Cookie。java// 1. 创建需要在多个二级子域名之间共享的单点登录凭证 Cookie ssoCookie = new Cookie("ssoToken", "eyJhbGciOiJIUzI1NiJ9"); // 2. 指定父级域名(RFC 6265 规范下无需添加前导点号,会自动转为小写) ssoCookie.setDomain("judith.com"); ssoCookie.setPath("/"); // 3. 下发响应报头:Set-Cookie: ssoToken=...; Domain=judith.com; Path=/ response.addCookie(ssoCookie);
getDomain
Cookie 类提供 public String getDomain() 方法用于读取当前实例设置的域名字符串。
自动小写转换:根据规范,域名对大小写不敏感。在
Cookie.setDomain(String domain)的源码实现中,传入的字符串会被立即执行domain.toLowerCase(Locale.ENGLISH)转换;因此紧接着调用getDomain()获取到的始终是全小写形式的字符串。回传阶段恒为空:与
getPath()、getMaxAge()完全一致,客户端回传的Cookie请求头不携带; Domain=...属性,服务端通过request.getCookies()解析得到的对象调用getDomain()返回值恒为null。java// 1. 下发阶段:调用 setDomain 时容器内部已统一转换为小写字符串 Cookie domainCookie = new Cookie("region", "cn-east"); domainCookie.setDomain("JUDITH.COM"); String lowerDomain = domainCookie.getDomain(); // 2. 回传阶段:从请求报头解析出的 Cookie 数组不包含域名元数据 Cookie[] cookies = request.getCookies(); if (cookies != null) { for (Cookie cookie : cookies) { // 3. 客户端仅回传键值对,此处调用 getDomain() 返回值恒为 null String inboundDomain = cookie.getDomain(); } }
Cookie 安全属性
由于 Cookie 直接保存在客户端浏览器中,且默认随每一次匹配的 HTTP 请求自动回传,一旦存储了会话标识(如 JSESSIONID)或身份令牌,便会成为网络监听、恶意脚本注入与跨站伪造攻击的首要目标。为此,RFC 6265 规范与 Servlet API 提供了 HttpOnly、Secure 与 SameSite 三大安全控制属性,分别从客户端脚本隔离、传输链路加密以及跨站发送限制三个维度构筑防御边界。
安全威胁与防御矩阵
在默认未开启任何安全属性的情况下,客户端 Cookie 主要面临三类典型安全威胁:

结合上图所示的攻击链路与防线机制,三大安全属性的职责边界如下:
防御跨站脚本窃取(XSS):如上图下半部分所示,当页面存在跨站脚本漏洞(XSS)时,攻击者注入的恶意 JavaScript 脚本可通过读取客户端存储凭据并上传至攻击者服务器,实施站外重放攻击。为 Cookie 添加
HttpOnly属性后,浏览器将禁止任何客户端脚本访问该 Cookie,从源头切断脚本导出链路。防御跨站请求伪造(CSRF):如上图上半部分所示,攻击者网站可诱导已登录用户的浏览器向受信任业务服务发起跨站请求,利用浏览器“自动携带目标站点 Cookie”的特性冒用用户身份。通过配置
SameSite属性,浏览器可在跨站上下文中拦截 Cookie 的自动附带。防御中间人明文窃听(MITM):在未加密的 HTTP 明文链路上,经过路由节点或公共无线网络的流量可被直接抓包嗅探。通过开启
Secure属性,可强制浏览器仅在 HTTPS(SSL/TLS)加密通道中发送该 Cookie。
| 安全属性 | 核心防御目标 | 作用维度 | 响应报头指令示例 | Servlet API 支持版本 |
|---|---|---|---|---|
HttpOnly | 跨站脚本窃取(XSS) | 禁止 document.cookie 等客户端脚本读写 | ; HttpOnly | Servlet 3.0+(setHttpOnly) |
Secure | 链路明文嗅探(MITM) | 仅限 HTTPS 加密连接传输 Cookie | ; Secure | Servlet 1.0+(setSecure) |
SameSite | 跨站请求伪造(CSRF) | 限制第三方跨站请求自动携带 Cookie | ; SameSite=Strict | Servlet 6.0+(setAttribute) |
# 1. 下发同时启用加密传输、禁止脚本读取与严格同站策略的会话凭证
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=9F8E7D6C; Path=/app; Secure; HttpOnly; SameSite=Strict
# 2. 下发允许跨站携带的三方内嵌 Cookie(SameSite=None 必须搭配 Secure)
Set-Cookie: thirdPartyTrack=t_102; Path=/; Secure; SameSite=NoneHttpOnly
HttpOnly 属性由微软在 IE6 SP1 中率先引入,随后被纳入 RFC 6265 标准,专门用于隔离浏览器渲染引擎中的脚本执行环境与网络传输层的 Cookie 存储。
setHttpOnly
Servlet 3.0 规范在 Cookie 类中新增了 public void setHttpOnly(boolean isHttpOnly) 方法。默认情况下,新建 Cookie 实例的 httpOnly 属性为 false(注:Servlet 容器自身生成的 JSESSIONID 会话 Cookie 默认已自动开启 HttpOnly)。
脚本读写双重阻断:一旦调用
setHttpOnly(true)并随响应下发,浏览器在收到; HttpOnly标记后,不仅禁止前端 JavaScript 通过document.cookie读取该条目(读取结果中完全不包含该键值对),同时也禁止脚本在客户端通过赋值document.cookie = "accessToken=xxx"覆盖修改同名条目。网络层无感透明:开启
HttpOnly仅封锁浏览器端的脚本 API(包括document.cookie与 Web Worker 脚本),完全不影响浏览器在发起常规页面跳转或XMLHttpRequest、Fetch异步请求时在 HTTP 请求报头中自动携带该 Cookie。非 XSS 根治方案:需要明确的是,
HttpOnly只能防止攻击者将 Cookie 字符串直接窃取并外带至站外服务器重放;若存在 XSS 漏洞,恶意脚本依然可以在当前页面上下文内直接调用fetch()发起携带有该 Cookie 的恶意业务请求,因此仍需配合输入输出转义与内容安全策略(CSP)。java// 1. 创建保存敏感身份令牌的 Cookie 实例 Cookie tokenCookie = new Cookie("accessToken", "eyJhbGciOiJIUzI1NiJ9"); tokenCookie.setPath(request.getContextPath()); // 2. 开启 HttpOnly 保护,阻止浏览器端 JavaScript 脚本访问 tokenCookie.setHttpOnly(true); // 3. 写入响应流,容器将在 Set-Cookie 报头末尾追加 ; HttpOnly 标记 response.addCookie(tokenCookie);
isHttpOnly
Cookie 类提供 public boolean isHttpOnly() 方法用于检查当前对象是否启用了脚本隔离。
下发阶段可校验:在服务端构造
Cookie并调用setHttpOnly(true)后,同一请求周期内调用isHttpOnly()返回true。**回传阶段恒为
false**:由于客户端发送的Cookie请求头仅包含name=value键值对,不会回传; HttpOnly标记,因此从request.getCookies()获取的实例调用isHttpOnly()恒返回默认值false。java// 1. 下发阶段:显式开启 HttpOnly 后,同一周期内调用 isHttpOnly() 返回 true Cookie outbound = new Cookie("sessionKey", "s_8812"); outbound.setHttpOnly(true); boolean isProtected = outbound.isHttpOnly(); // 2. 回传阶段:浏览器发送的 Cookie 请求头仅含键值对,不携带 HttpOnly 标记 Cookie[] cookies = request.getCookies(); if (cookies != null) { for (Cookie item : cookies) { // 3. 容器解析请求头新建的 Cookie 实例未设置该属性,此处恒返回 false boolean inboundFlag = item.isHttpOnly(); } }
Secure
Secure 属性用于约束浏览器在网络传输层面的协议选择,确保包含敏感信息的 Cookie 绝不会在明文 HTTP 连接中裸奔。
setSecure
Cookie 类通过 public void setSecure(boolean flag) 方法控制该属性(默认值为 false)。当传入 true 时,容器会在 Set-Cookie 响应头中追加 ; Secure 指令。
HTTPS 单向放行:浏览器收到带有
Secure标记的 Cookie 后,只有当后续请求采用加密协议(如https://或wss://)时,才会将该 Cookie 附加到请求报头中;若用户通过明文http://访问同一域名下的相同路径,浏览器会自动过滤掉该 Cookie。非加密源下发限制:自 Chrome 52 与 Firefox 52 起,现代浏览器强化了规范校验——若服务端本身正处于不安全的
http://连接下,却试图通过Set-Cookie下发带有Secure标记的 Cookie,或者试图覆盖更新已存在的SecureCookie,浏览器会直接拒绝写入。本地回环测试豁免:为了方便开发者在本地环境调试,现代主流浏览器将
http://localhost与[http://127.0.0.1](http://127.0.0.1)视为受信任的安全上下文(Potentially Trustworthy Origin),即使未配置 SSL 证书,本地开发时下发和回传SecureCookie 依然可以正常生效。java// 1. 创建存储支付校验凭据的敏感 Cookie Cookie payCookie = new Cookie("payTicket", "pt_99201"); payCookie.setPath(request.getContextPath()); // 2. 开启 Secure 属性,限制浏览器仅在 HTTPS 加密连接下回传该凭据 payCookie.setSecure(true); // 3. 写入响应头,生成包含 ; Secure 标记的 Set-Cookie 指令 response.addCookie(payCookie);
getSecure
Cookie 类提供 public boolean getSecure() 方法读取当前实例的 secure 布尔值。
动态联动请求协议:在企业应用中,若同一套代码既要在本地或内网 HTTP 环境运行,又要在生产 HTTPS 环境部署,常利用
request.isSecure()的返回值动态传参给cookie.setSecure(request.isSecure())(若处于 Nginx 反向代理后端,需确保容器配置了RemoteIpValve正确识别X-Forwarded-Proto: https)。回传元数据丢失:与
isHttpOnly()一致,客户端回传的Cookie请求头不含; Secure属性,因此在request.getCookies()返回的实例上调用getSecure()恒返回false。服务端若需判断当前请求是否经由安全通道传输,应调用request.isSecure()而非cookie.getSecure()。java// 1. 下发阶段:可根据当前请求是否为 HTTPS 动态设置并读取 Secure 状态 Cookie cookie = new Cookie("channel", "tls"); cookie.setSecure(request.isSecure()); boolean configuredSecure = cookie.getSecure(); // 2. 回传阶段:从请求报头解析得到的 Cookie 数组丢失了 Secure 属性标记 Cookie[] cookies = request.getCookies(); if (cookies != null) { for (Cookie item : cookies) { // 3. 无论客户端是否通过 HTTPS 传输,此处 getSecure() 均返回默认值 false boolean inboundSecure = item.getSecure(); } }
SameSite
在传统的 Cookie 作用域模型中,浏览器仅检查目标 URL 的 Domain 与 Path 是否匹配,而完全不关心发起请求的源页面(Origin / Site)是谁。这一设计缺陷直接催生了跨站请求伪造(CSRF)攻击。

如上图时序所示,当用户先登录合法网站 goodsite.com 并在浏览器本地保存了登录 Cookie 后,若在不关闭浏览器的情况下被诱导访问了诱饵网站,诱饵网站只需在页面中隐藏一个指向 [http://goodsite.com/vote](http://goodsite.com/vote) 的 form 表单并由脚本自动触发 submit(),浏览器就会在跨站发起该 POST 请求时自动附上 goodsite.com 的登录 Cookie,从而以用户合法身份执行恶意操作。
为了从浏览器底层阻断此类跨站自动附带行为,RFC 6265bis 引入了 SameSite 属性,通过比对“当前页面所在站点”与“请求目标站点”是否属于同一注册域(eTLD+1,如 [www.example.com](https://www.example.com) 与 api.example.com 属于同站,而 evil.com 与 example.com 属于跨站),提供三种渐进式控制策略:
| 跨站请求触发场景 | HTML / 脚本调用方式 | 未设置(旧版浏览器) | SameSite=None | SameSite=Lax(现代默认) | SameSite=Strict |
|---|---|---|---|---|---|
| 超链接导航 | 页面点击 a href 链接跳转 | 发送 Cookie | 发送 Cookie | 发送 Cookie | 不发送 |
| 页面预渲染 | 页面声明 link rel="prerender" | 发送 Cookie | 发送 Cookie | 发送 Cookie | 不发送 |
| GET 表单提交 | 提交 form method="GET" | 发送 Cookie | 发送 Cookie | 发送 Cookie | 不发送 |
| POST 表单提交 | 提交 form method="POST" | 发送 Cookie | 发送 Cookie | 不发送 | 不发送 |
| 异步脚本请求 | 调用 XMLHttpRequest 或 fetch | 发送 Cookie | 发送 Cookie | 不发送 | 不发送 |
| 内嵌子框架 | 页面嵌套 iframe src | 发送 Cookie | 发送 Cookie | 不发送 | 不发送 |
| 静态图片加载 | 页面引用 img src | 发送 Cookie | 发送 Cookie | 不发送 | 不发送 |
Strict
SameSite=Strict 是最为严格的同站隔离策略。一旦设置为 Strict,只要浏览器判定当前请求的发起源与目标 URL 处于跨站(Cross-Site)关系,在任何场景下均拒绝发送该 Cookie。
极致安全防护:彻底杜绝任何形式的跨站请求伪造,适用于后台管理系统、资金转账、密码修改等高安全敏感度模块。
外链跳转体验割裂:由于
Strict连常规的顶层超链接导航(点击a标签)也会拦截,假设用户已在浏览器登录了内部办公系统,当他从外部邮件客户端或第三方门户网站点击超链接跳转到该办公系统时,首次打开的请求不会携带登录 Cookie,页面会显示为“未登录”状态,必须刷新一次页面或站内二次点击才能恢复登录态。
Lax
SameSite=Lax 是兼顾安全性与用户体验的折中策略,也是自 Chrome 80、Edge 86 及 Firefox 69+ 起,当服务端未显式声明 SameSite 属性时现代浏览器的缺省默认行为。
放行安全顶层导航:当用户从外部站点通过点击
a超链接或提交GET表单触发浏览器地址栏改变的顶层导航(Top-Level Navigation),且 HTTP 方法属于安全只读方法(GET、HEAD)时,浏览器允许携带Lax策略的 Cookie,从而保证了外链跳转依然维持登录状态。拦截高危跨站子请求:对于上一节时序图中典型的跨站
POST表单提交、跨站fetch/AJAX异步请求,以及第三方页面通过iframe、img发起的静默请求,浏览器一律禁止携带该 Cookie,从而有效防御绝大多数 CSRF 攻击。
None
SameSite=None 表示显式关闭跨站限制,允许浏览器在同站与所有跨站上下文(包括第三方 iframe 内嵌页面、跨站 POST 表单与跨域异步请求)中无条件发送该 Cookie。
强制绑定
Secure属性:根据现代浏览器安全规范,若显式指定SameSite=None,必须同时在同一条Set-Cookie报头中开启Secure属性(即写作; Secure; SameSite=None);如果仅声明SameSite=None而不带Secure,浏览器会直接判定该报头非法并拒绝存储。典型适用场景:主要用于需要嵌入到其他不同一级域名网站
iframe中运行的第三方插件、跨域单点登录(SSO)回调网关或跨站支付回调接口。
setAttribute
在 Servlet 5.0(Jakarta EE 9)及更早期的 javax.servlet 版本中,标准 Cookie 类并未提供设置 SameSite 的专属方法。直到 Servlet 6.0(Jakarta EE 10,对应 Tomcat 10.1+),jakarta.servlet.http.Cookie 正式新增了通用扩展属性方法 public void setAttribute(String name, String value) 与 public String getAttribute(String name),使开发者能够以标准面向对象方式配置 SameSite:
// 1. 构建跨站敏感业务 Cookie,并启用 HTTPS 与 HttpOnly 基础防护
Cookie authCookie = new Cookie("authSession", "s_44910");
authCookie.setPath(request.getContextPath());
authCookie.setSecure(true);
authCookie.setHttpOnly(true);
// 2. 通过 Servlet 6.0 新增的 setAttribute 注入 SameSite 同站控制策略
authCookie.setAttribute("SameSite", "Strict");
// 3. 读取已绑定的扩展属性值并写入响应报头
String sameSitePolicy = authCookie.getAttribute("SameSite");
response.addCookie(authCookie);setSameSiteCookies
若项目仍运行在 Servlet 4.0(Tomcat 9)或 Servlet 5.0(Tomcat 10.0)环境中,Cookie 类尚无 setAttribute 方法。此时除了在 META-INF/context.xml 中配置 <CookieProcessor sameSiteCookies="Lax"/> 外,也可在代码中直接调用 Tomcat 容器提供的 Rfc6265CookieProcessor.setSameSiteCookies(String) 生成带 SameSite 的响应报头字符串:
// 1. 实例化 Tomcat 默认的 RFC 6265 报头处理器
Rfc6265CookieProcessor processor = new Rfc6265CookieProcessor();
// 2. 配置全局 SameSite 策略为 Lax(可选值:unset、none、lax、strict)
processor.setSameSiteCookies("Lax");
// 3. 将 Cookie 实例序列化为包含 SameSite=Lax 的完整 Set-Cookie 报头值
Cookie cookie = new Cookie("prefs", "compact");
String headerValue = processor.generateHeader(cookie, request);
response.addHeader("Set-Cookie", headerValue);CookieProcessor 报头解析
在 Servlet 规范中,javax.servlet.http.Cookie(或 jakarta.servlet.http.Cookie)仅是一个纯粹的内存数据载体(POJO),自身并不包含任何将对象序列化为 Set-Cookie 响应报头字符串、或将 Cookie 请求报头字节流反序列化为对象数组的逻辑。为了解耦 HTTP 协议规范演进(从早期的 Netscape、RFC 2109、RFC 2965 到现行的 RFC 6265)与底层连接器(Connector)实现,Tomcat 自 8.0.15 版本起引入了 org.apache.tomcat.util.http.CookieProcessor 策略接口,专门接管 Cookie 报头的双向解析与生成。
容器级组件挂载
在 Tomcat 的容器层级架构中,CookieProcessor 并非绑定在全局 Server 或 Connector 上,而是作为 Web 应用上下文容器 StandardContext(即 Context 接口的标准实现类)的内部子组件进行挂载。

结合上图所示的 Tomcat 容器与连接器 UML 类图,報头解析组件在容器中的协作关系如下:
应用级隔离挂载(
StandardContext):每个部署在 Tomcat 中的独立 Web 应用都对应一个StandardContext实例。StandardContext内部持有private CookieProcessor cookieProcessor成员变量(Tomcat 8.5+ 在容器启动startInternal()时默认初始化为new Rfc6265CookieProcessor()),使得同一个 Tomcat 实例下的不同 Web 应用可以独立配置各自的 Cookie 解析策略与字符集,互不干扰。跨层桥接调用(
Connector与StandardContext):当客户端请求经由Connector进入容器管道后,连接器生成的Request与Response对象会通过getContext().getCookieProcessor()获取当前 Web 应用专属的处理器实例,完成底层网络字节流与上层 Servlet API 之间的转换。
CookieProcessor
org.apache.tomcat.util.http.CookieProcessor 接口定义了字节流解析、响应头序列化与字符集获取三个核心契约方法:
// 1. 解析请求头中的 Cookie 字节流并填充至底层 ServerCookies 容器
void parseCookieHeader(MimeHeaders headers, ServerCookies serverCookies);
// 2. 将 Java 层的 Cookie 实例序列化为符合规范的 Set-Cookie 响应头字符串
String generateHeader(Cookie cookie, HttpServletRequest request);
// 3. 返回当前处理器解析与编码字节流时使用的字符集
Charset getCharset();parseCookieHeader
该方法负责读取 Coyote 底层封装的原始 HTTP 请求报头集合(MimeHeaders),从中检索所有名为 "Cookie" 的报头行,按照对应 RFC 规范的词法规则切分出键值对,并将解析结果填充至 ServerCookies 结构中。此阶段仅操作底层的 ByteChunk 字节块偏移量,避免过早创建大量 Java String 对象。
generateHeader
该方法负责将业务层传入的 javax.servlet.http.Cookie(或 jakarta.servlet.http.Cookie)实例转换为完整的 Set-Cookie 响应报头值字符串(不包含 "Set-Cookie: " 报头名称前缀)。在拼接过程中,该方法会校验键名与键值的字符合法性,并依次追加 Max-Age、Expires、Domain、Path、Secure、HttpOnly 及 SameSite 等元数据属性。
getCharset
该方法返回处理器在将请求字节流解码为字符串、以及将响应报头字符串编码为字节流时所采用的 java.nio.charset.Charset 字符集(如 UTF-8 或 ISO-8859-1)。
协议规范演进与实现类
围绕 CookieProcessor 接口,Tomcat 提供了抽象基类 CookieProcessorBase 以及针对新旧两套 HTTP 规范的具体实现类:Rfc6265CookieProcessor 与 LegacyCookieProcessor。
| 对比维度 | Rfc6265CookieProcessor(Tomcat 8.5+ 默认) | LegacyCookieProcessor(Tomcat 8.0 默认,现已废弃) |
|---|---|---|
| 遵循协议标准 | RFC 6265(现行 HTTP State Management 标准) | RFC 6265、RFC 2109、RFC 2965 及 Netscape 混合规范 |
| 默认字符集 | UTF-8(直接支持 UTF-8 字节序列) | ISO-8859-1(US-ASCII 兼容单字节编码) |
| 前导点号域名 | 严禁 Domain 以 . 开头(如 .example.com 抛异常) | 允许前导点号域名 |
| 特殊分隔符处理 | 严禁键值包含空格、逗号、分号、冒号等分隔符 | 可通过配置将含特殊字符的值自动包裹双引号转义 |
| 演进状态 | Tomcat 8.5 / 9.0 / 10.x / 11.x 唯一推荐实现 | Tomcat 8.5 起标记弃用,Tomcat 10.0+ 已彻底移除 |
CookieProcessorBase
CookieProcessorBase 是实现 CookieProcessor 接口的抽象父类,内部封装了与具体 RFC 词法无关的公共逻辑:
古早纪元时间常量:维护
ANCIENT_DATE(格式化为"Thu, 01 Jan 1970 00:00:10 GMT")线程安全日期格式化器,供子类在遇到maxAge == 0时快速生成立即过期的Expires属性。SameSite策略持有:维护private SameSiteCookies sameSiteCookies = SameSiteCookies.UNSET属性,暴露getSameSiteCookies()与setSameSiteCookies(String)方法,统一支撑容器级的同站策略注入。
Rfc6265CookieProcessor
Rfc6265CookieProcessor 继承自 CookieProcessorBase,严格遵循现行 RFC 6265 规范,是 Tomcat 8.5 及后续所有版本的默认实现。
基于 BitSet 的高速词法校验:内部维护
domainValid等位图(BitSet),在生成报头时对name(Token 规则)、value(cookie-octet规则)、domain和path进行逐字符校验。严格的语法边界:
value字符限制:仅允许十六进制0x21、0x23 至 0x2B、0x2D 至 0x3A、0x3C 至 0x5B、0x5D 至 0x7E 范围内的可见字符以及0x80至0xFF的扩展字节;凡是出现空格(0x20)、双引号(")、逗号(,)、分号(;)或反斜杠(\),均直接抛出IllegalArgumentException。domain格式限制:要求域名必须由字母、数字和连字符组成,且首尾字符不能是点号(.)或连字符(-)。若旧项目代码传入cookie.setDomain(".example.com"),在Rfc6265CookieProcessor下会直接抛出IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie。
LegacyCookieProcessor
LegacyCookieProcessor 同样继承自 CookieProcessorBase,用于兼容早期 Servlet 容器遵循的 Netscape、RFC 2109 与 RFC 2965 规范(注:该类在 Tomcat 9 中已标记为 @Deprecated,并在 Tomcat 10 / Jakarta EE 9 中被正式移除)。
V0 与 V1 版本自动升降级:当
cookie.getVersion()为0(Netscape 格式)但键值中包含了空格或分隔符时,若开启了相关兼容开关,处理器会自动将其升级为Version=1(RFC 2109 格式)并在键值外围包裹双引号"..."。精细化容错开关:提供
allowEqualsInValue(允许值中出现等号)、allowHttpSepsInV0(允许 V0 格式中出现 HTTP 分隔符)、allowNameOnly(允许无等号的纯键名 Cookie)以及alwaysAddExpires(即使为 V1 版本也强制附带Expires属性)等配置项,专用于拯救无法修改源码的历史遗留系统。java// 1. 使用默认的 Rfc6265CookieProcessor 序列化标准 Cookie Rfc6265CookieProcessor rfc6265 = new Rfc6265CookieProcessor(); Cookie modernCookie = new Cookie("token", "v2_9981"); String modernHeader = rfc6265.generateHeader(modernCookie, request); // 2. 实例化遗留处理器并开启允许分隔符属性以兼容含冒号或空格的旧版值 LegacyCookieProcessor legacy = new LegacyCookieProcessor(); legacy.setAllowHttpSepsInV0(true); // 3. 序列化包含特殊分隔符的旧版 Cookie(自动包裹双引号或按 Version 0 输出) Cookie legacyCookie = new Cookie("legacyMeta", "role:admin"); String legacyHeader = legacy.generateHeader(legacyCookie, request);
请求报头懒加载解析
当客户端携带着 Cookie 请求头访问 Tomcat 时,容器在接收网络数据包阶段并不会立即解析 Cookie,而是采用按需懒加载(Lazy Evaluation)+ 零拷贝字节块(ByteChunk)的设计模式。若一次请求从头到尾没有任何 Filter 或 Servlet 调用 request.getCookies()(且容器无需通过 Cookie 提取 JSESSIONID),则整个请求周期内完全不会发生 Cookie 字符串解析与对象分配开销。
如上图 UML 类图所示,业务层 Servlet 在 doGet / doPost 中拿到的 HttpServletRequest 实例,实际运行类型是采用门面模式(Facade Pattern)封装的 org.apache.catalina.connector.RequestFacade,其内部组合持有了真正的核心请求对象 org.apache.catalina.connector.Request。

RequestFacade
当开发者在业务代码中调用 request.getCookies() 时,调用链首先进入 RequestFacade.getCookies(),该方法校验内部 request 引用非空后,直接委派给 org.apache.catalina.connector.Request.getCookies()。
parseCookies
org.apache.catalina.connector.Request 在执行 getCookies() 时,首先调用自身的 parseCookies() 方法触发懒加载解析流程:
单次解析幂等缓存:
Request内部维护布尔标记cookiesParsed与结果数组Cookie[] cookies。首次调用getCookies()时cookiesParsed为false,触发底层解析并将标记置为true;同一请求周期内后续任意多次调用getCookies(),均直接返回已缓存的数组引用。委派
CookieProcessor解析:parseCookies()从StandardContext获取当前生效的CookieProcessor,将 Coyote 底层的原始请求头MimeHeaders与预分配容器ServerCookies一并传入processor.parseCookieHeader(...)。异常容错跳过:在最后遍历
ServerCookies实例化new Cookie(name, value)的循环中,Tomcat 使用了try-catch (IllegalArgumentException)块包裹单条记录的构造过程——如果客户端请求头中夹杂了某条键名非法的脏 Cookie,容器仅忽略该条非法记录并继续解析其余合法 Cookie,不会导致整个请求抛出 500 异常中断。java// 1. 检查当前请求周期内是否已解析过 Cookie,实现懒加载与单次解析缓存 protected void parseCookies() { if (cookiesParsed) { return; } cookiesParsed = true; // 2. 获取 Coyote 底层预分配的 ServerCookies 容器并清空复用空间 ServerCookies serverCookies = coyoteRequest.getServerCookies(); serverCookies.recycle(); // 3. 提取当前 StandardContext 绑定的 CookieProcessor 执行报头字节流解析 CookieProcessor processor = getContext().getCookieProcessor(); processor.parseCookieHeader(coyoteRequest.getMimeHeaders(), serverCookies); // 4. 将零拷贝的 ServerCookie 字节块延时转换为标准 Servlet Cookie 数组 int count = serverCookies.getCookieCount(); if (count <= 0) { return; } cookies = new Cookie[count]; for (int i = 0; i < count; i++) { ServerCookie scookie = serverCookies.getCookie(i); Cookie cookie = new Cookie(scookie.getName().toString(), scookie.getValue().toString()); cookies[i] = cookie; } }
ServerCookies
在 CookieProcessor.parseCookieHeader 内部,Tomcat 并未直接使用 String.split(";") 切割报头,而是借助 org.apache.tomcat.util.http.ServerCookies 与 ServerCookie 实现零拷贝(Zero-Copy)解析:
字节偏移量切片(
MessageBytes/ByteChunk):网络套接字读取的 HTTP 请求头最初存放在一段连续的字节缓冲区(byte[])中。Rfc6265CookieProcessor在扫描分号;和等号=时,仅将键名与键值的起始偏移量(start)和结束偏移量(end)记录到ServerCookie内部的MessageBytes结构中,全程不分配任何堆内存字符串。对象池化复用:
ServerCookies内部维护的ServerCookie[]数组随coyoteRequest一起被池化复用(默认初始容量为 4,不足时双倍扩容,受ServerCookies.limit默认上限 200 保护以防御哈希碰撞与内存耗尽攻击)。当请求结束调用recycle()时,仅重置指针偏移量而不销毁对象,大幅降低高并发下的 GC 压力。
响应报头序列化下发
与请求端懒加载相对应,当业务层调用 response.addCookie(cookie) 下发状态时,调用链经由 ResponseFacade 委派至 org.apache.catalina.connector.Response.addCookie(Cookie)。
addCookie
在 org.apache.catalina.connector.Response.addCookie(Cookie) 源码中,容器按以下三步完成报头生成与挂载:
响应提交状态拦截:首先检查当前响应是否处于
RequestDispatcher.include()包含转发上下文(included为true),或者响应缓冲区是否已经刷出提交(isCommitted()为true)。若满足任一条件,直接return忽略本次调用(因为按照 Servlet 规范,被include的子 Servlet 无权修改响应头,且已提交的响应无法再追加 HTTP 头部)。调用
generateHeader序列化:通过getContext().getCookieProcessor().generateHeader(cookie, getRequest())将Cookie对象格式化为符合 RFC 规范的字符串。**写入底层
MimeHeaders**:调用addHeader("Set-Cookie", header, processor.getCharset()),将生成的报头字符串连同处理器指定的字符集写入 Coyote 层的org.apache.coyote.Response头部列表中,等待响应提交时一并刷入 Socket 输出流。java// 1. 若响应流已提交(Committed)或处于 include 包含上下文,则直接忽略写入 public void addCookie(final Cookie cookie) { if (included || isCommitted()) { return; } // 2. 调用当前 StandardContext 的 CookieProcessor 生成报头字符串 CookieProcessor processor = getContext().getCookieProcessor(); final String header = processor.generateHeader(cookie, getRequest()); // 3. 按处理器指定的字符集将 Set-Cookie 报头追加至底层响应头集合 addHeader("Set-Cookie", header, processor.getCharset()); }
容器解析策略配置
在实际工程部署中,可通过 Web 应用目录下的 META-INF/context.xml(或全局 conf/context.xml)中的 <CookieProcessor> 标签,声明式调整当前应用的报头解析器类型与全局 SameSite 属性:
<Context>
<!-- 1. 默认推荐:配置 RFC 6265 处理器并全局声明 SameSite 策略 -->
<CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor"
sameSiteCookies="Lax" />
<!-- 2. 遗留兼容:切换为旧版处理器以放宽前导点号域名与特殊分隔符限制 -->
<!--
<CookieProcessor className="org.apache.tomcat.util.http.LegacyCookieProcessor"
allowHttpSepsInV0="true"
alwaysAddExpires="true" />
-->
</Context>API: CookieProcessor
报头解析
voidparseCookieHeader():(MimeHeaders headers, ServerCookies serverCookies),请求头解析。扫描 HTTP 请求的底层MimeHeaders原始报头集合,提取所有名为Cookie的报头行,按照当前协议规范的词法规则切分键值对,并以零拷贝字节块偏移量的形式填充至ServerCookies容器中。
注意事项:
- 零拷贝延迟实例化:
parseCookieHeader在解析过程中仅移动底层ByteChunk的起始与结束偏移量指针并记录在ServerCookie槽位中,不会直接创建javax.servlet.http.Cookie(或jakarta.servlet.http.Cookie)对象;直到上层业务代码显式调用request.getCookies()时,容器才会遍历ServerCookies完成字符串解码与对象实例化。- 脏数据容错策略:当请求报头中某一个键值对存在词法格式错误(如非法控制字符或缺失键名)时,实现类通常会记录调试日志并直接跳过该非法字段,继续解析同一报头行中的后续合法键值对,避免因单个损坏的 Cookie 导致整个 HTTP 请求中断。
import org.apache.tomcat.util.http.CookieProcessor;
import org.apache.tomcat.util.http.MimeHeaders;
import org.apache.tomcat.util.http.Rfc6265CookieProcessor;
import org.apache.tomcat.util.http.ServerCookie;
import org.apache.tomcat.util.http.ServerCookies;
public class CookieProcessorParseExample {
public static void main(String[] args) {
// 1. 构造底层 MimeHeaders 并写入模拟的客户端 Cookie 请求报头字节块
MimeHeaders headers = new MimeHeaders();
headers.addValue("Cookie").setString("theme=dark; lang=zh-CN");
// 2. 初始化容量上限为 4 的 ServerCookies 容器并调用 parseCookieHeader 解析
ServerCookies serverCookies = new ServerCookies(4);
CookieProcessor processor = new Rfc6265CookieProcessor();
processor.parseCookieHeader(headers, serverCookies);
// 3. 遍历解析后的零拷贝 ServerCookie 槽位并输出键值对
for (int i = 0; i < serverCookies.getCookieCount(); i++) {
ServerCookie sc = serverCookies.getCookie(i);
System.out.println(sc.getName().toString() + " -> " + sc.getValue().toString());
}
}
}报头生成
- generateHeader():响应头序列化。将业务层构建的 Servlet
Cookie实例及其生命周期、作用域、安全控制等元数据属性,序列化为符合目标 RFC 规范的Set-Cookie响应报头值字符串(不含Set-Cookie:报头名本身)。String:(Cookie cookie),无上下文报头生成。仅根据传入的Cookie实例自身持有的属性拼接生成Set-Cookie响应报头字符串。String:(Cookie cookie, HttpServletRequest request),请求感知报头生成。结合当前HttpServletRequest请求上下文与Cookie实例属性生成Set-Cookie响应报头字符串。
注意事项:
- 重载方法演进与废弃:单参重载
generateHeader(Cookie)在 Tomcat 8.5.42 与 Tomcat 9.0.21 中已被标记为@Deprecated,并引入了带default默认实现的双参重载generateHeader(Cookie, HttpServletRequest);自 Tomcat 10.0(Jakarta Servlet 5.0)起,单参重载被彻底移除,双参方法成为接口的唯一标准抽象方法。- 非法字符即时拦截:在调用
generateHeader序列化期间,处理器会对value、domain和path执行严格的 BitSet 字符集校验。例如在默认的Rfc6265CookieProcessor下,若domain以点号.开头或value中包含空格、逗号、分号,该方法会立即抛出IllegalArgumentException。
```java {7,14,19} /generateHeader/
import javax.servlet.http.Cookie;
import org.apache.tomcat.util.http.CookieProcessor;
import org.apache.tomcat.util.http.Rfc6265CookieProcessor;
public class CookieProcessorGenerateExample {
public static void main(String[] args) {
// 1. 构建配置了生命周期、路径与安全属性的 Servlet Cookie 实例
Cookie cookie = new Cookie("SESSIONID", "A1B2C3D4");
cookie.setMaxAge(3600);
cookie.setPath("/portal");
cookie.setHttpOnly(true);
cookie.setSecure(true);
// 2. 调用单参重载方法直接根据 Cookie 属性生成 Set-Cookie 报头值
CookieProcessor processor = new Rfc6265CookieProcessor();
String headerWithoutReq = processor.generateHeader(cookie);
System.out.println("单参生成: " + headerWithoutReq);
// 3. 调用双参重载方法结合请求上下文生成 Set-Cookie 报头值
String headerWithReq = processor.generateHeader(cookie, null);
System.out.println("双参生成: " + headerWithReq);
}
}
```
编码配置
CharsetgetCharset():(),字符集获取。返回当前CookieProcessor实例在将请求报头字节流解码为 Java 字符串、以及将generateHeader生成的响应报头字符串写入底层网络字节缓冲区时所使用的Charset字符集对象。
注意事项:
- 不同实现类的默认字符集差异:
Rfc6265CookieProcessor的getCharset()固定返回StandardCharsets.UTF_8,允许报头字节流中包含非 ASCII 的 UTF-8 扩展多字节序列;而旧版LegacyCookieProcessor默认返回StandardCharsets.ISO_8859_1。- 跨网关乱码规避:尽管
Rfc6265CookieProcessor底层支持 UTF-8 字符集,但由于部分中间代理服务器与老旧客户端对报头中的裸多字节字符处理不一致,生产环境中仍建议在业务层先通过URLEncoder.encode转换为纯 ASCII 字符后再交由处理器编码。
import java.nio.charset.Charset;
import org.apache.tomcat.util.http.CookieProcessor;
import org.apache.tomcat.util.http.LegacyCookieProcessor;
import org.apache.tomcat.util.http.Rfc6265CookieProcessor;
public class CookieProcessorCharsetExample {
public static void main(String[] args) {
// 1. 获取 RFC 6265 处理器默认采用的 UTF-8 字符集
CookieProcessor rfcProcessor = new Rfc6265CookieProcessor();
Charset rfcCharset = rfcProcessor.getCharset();
System.out.println("Rfc6265 默认字符集: " + rfcCharset.name());
// 2. 获取遗留处理器默认采用的 ISO-8859-1 单字节字符集
CookieProcessor legacyProcessor = new LegacyCookieProcessor();
Charset legacyCharset = legacyProcessor.getCharset();
System.out.println("Legacy 默认字符集: " + legacyCharset.name());
}
}