Servlet里有一类对象你天天在用但很少认真翻过它的文档Cookie算一个。多数人第一次接触javax.servlet.http.Cookie是在做登录功能的时候跟着教程敲三行代码new 一个、setMaxAge、addCookie页面刷新一下确实生效了然后这事就翻篇了。等到项目丢到真实环境里“记住我”忽然不灵或者同一个应用首页能读到值、二级目录下的页面读不到再或者 value 里塞了中文容器直接甩一个 500 出来——这时候才回头翻规范发现这个小东西的属性项比想象中多得多行为边界也比想象中窄得多。这篇内容就围绕 Servlet 编程里的 Cookie 对象展开讲清楚它为什么存在、服务端与浏览器之间的读写链路长什么样、那几个属性分别在什么时机起作用、中文值和特殊字符为什么会被容器直接拒掉以及删除不干净、同名冲突、path 对不上这几类问题的排查顺序。适合已经能跑通一个 Hello World 级别登录 Demo、但对 Cookie 的认知还停留在“能存能取”这一层的同学也适合工作一两年想把会话跟踪这块基础彻底钉死的人。文中所有代码都基于标准 Servlet API不绑定具体容器版本但涉及版本差异的地方我会单独点出来。1. 无状态协议下“记住用户”这件事到底由谁承担1.1 一次请求走完服务端就把你忘光了HTTP 的设计哲学是“一问一答答完即忘”。浏览器发一个请求服务端处理、返回响应连接关掉这次交互在服务端的内存里几乎不留痕迹。这套模型在拉取静态资源时极其高效但一旦碰到“这个用户刚才是不是登录过”这种问题就立刻暴露出短板服务端没有任何内建机制能识别出“这两个请求来自同一个人”。这件事的性质需要说清楚不是 Servlet 缺功能而是 HTTP 协议本身就不提供状态。所以任何一个会话跟踪方案本质上都是在客户端和服务端之间约定一个“暗号”让服务端能凭这个暗号把前后的请求串起来。业界的做法大致就那么几种URL 重写把 sessionId 拼在链接后面、隐藏表单域把标识塞进 form 的 hidden input、Cookie以及后来的各种 Token 方案。前两种只在特定场景下能用——URL 重写会污染地址栏、隐藏域只能跟着表单走用户一旦手动敲地址或者点收藏夹就断链。Cookie 之所以成为 Servlet 规范里最正统的方案是因为它把“携带标识”这件事从业务代码里剥离出来交给了浏览器自动完成。Servlet 容器启动、处理第一个请求、创建HttpSession、往响应里塞一个Set-Cookie: JSESSIONIDxxx——这一整套动作背后站着的就是Cookie对象。所以你把 Cookie 搞明白了Session 那一节的很多“玄学现象”也顺带就通了。1.2 Cookie 在浏览器与服务端之间往返的那条链路把链路拆开看Cookie 的一生只有两个方向的动作服务端 → 浏览器响应头里出现Set-Cookie浏览器收到后按域名和路径把这条记录存进自己的 Cookie 存储区。注意是“存”不是“用”这一步纯粹是落盘。浏览器 → 服务端之后每一次请求只要目标域名和路径匹配浏览器会自动把这条 Cookie 放进请求头Cookie: namevalue里带上去。这个过程完全不需要前端写任何代码fetch、XMLHttpRequest、表单提交、直接在地址栏敲回车全都一样。这里有个容易被忽略的细节请求头里的 Cookie 只带 name 和 value不带任何属性。这意味着服务端拿到手的只是一个字符串键值对至于这条 Cookie 当初设了多长的有效期、挂在哪个路径下、是不是 HttpOnly服务端一概无从得知。这些属性是给浏览器看的是浏览器判断“要不要存”“什么时候过期”“什么时候发出去”的依据服务端只能通过request.getCookies()拿到最终的键值对结果。理解这一点后面很多问题就顺了。比如“为什么我读不到自己设置的 path”——因为 path 根本不在请求头里传输“为什么我删了 Cookie 但它还在”——因为你只是在服务端发了个删除指令浏览器有没有照做取决于你那条指令的域名、路径、名字是否和被删的那条完全对上。再看一次典型的往返第一次请求登录成功 POST /app/login -- 200 OK Set-Cookie: uid10086; Max-Age604800; Path/app; HttpOnly 后续请求自动携带 GET /app/profile Cookie: uid10086 -- 200 OK整个机制的巧妙之处在于“自动”二字风险也藏在“自动”二字里只要你浏览这个域名浏览器就会主动把 Cookie 交出去不管发起请求的是你自己写的页面还是别的站点诱导浏览器发出的请求。Cross-Site Request Forgery 这类问题能成立根子上就是这条自动携带的规则。2. Cookie 对象在 Servlet 里的读写全流程2.1 服务端把 Cookie 交给浏览器new 与 addCookie 之间发生了什么Cookie在 Java 侧就是一个普普通通的 POJO构造方法只有两个Cookie(String name, String value)和已经废弃的Cookie(String name, String value, String path)。new 出来之后它只是堆里一个对象和响应没有任何关系必须显式调用response.addCookie(cookie)容器才会在生成响应头的时候把它序列化成Set-Cookie。这段代码几乎是所有教程的起点WebServlet(/login) public class LoginServlet extends HttpServlet { Override protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { String username req.getParameter(username); String remember req.getParameter(remember); if (on.equals(remember)) { Cookie cookie new Cookie(username, URLEncoder.encode(username, UTF-8)); cookie.setMaxAge(60 * 60 * 24 * 7); // 单位是秒这里是 7 天 cookie.setPath(req.getContextPath().isEmpty() ? / : req.getContextPath()); cookie.setHttpOnly(true); resp.addCookie(cookie); } resp.sendRedirect(req.getContextPath() /index.jsp); } }几个点值得单独拎出来说。setMaxAge的单位是秒不是毫秒也不是天写成60 * 60 * 24 * 7是七天写成1000 * 60 * 60 * 24 * 7就变成七十天了这种错很常见。setPath我用了req.getContextPath()而不是硬编码/是为了避免应用部署在/app这种子路径下时Cookie 溢出去污染同域下的其他应用。setHttpOnly(true)是防 XSS 顺手偷 Cookie 的第一道闸只要这个值不需要前端 JS 读就应该加上。还有一点同一个响应里对同名 Cookie 多次addCookie结果不一定如你所愿。较老的规范实现里两个同名 Cookie 会连着输出两个Set-Cookie头浏览器收到后通常以后者为准但顺序由实现决定新版 Servlet 规范对这块做了收敛。稳妥的做法是保证一个响应里不重复设置同名 Cookie需要覆盖就直接算好最终值再塞一次。2.2 服务端从请求里把 Cookie 捞回来getCookies 的边界读侧的 API 只有一个request.getCookies()返回Cookie[]。它的两个陷阱必须记住第一没有 Cookie 时返回的是null不是空数组。直接for (Cookie c : req.getCookies())会喜提 NPE。这是新手最常踩的一个尤其出现在“第一次访问”的场景里——你自己测试的时候浏览器可能已经有旧 Cookie 了换个无痕窗口立刻崩。第二返回的数组里只有 name 和 value 有值getMaxAge()永远返回 -1getPath()永远返回 null。前面已经解释过原因这里再强调一遍是因为很多人会写出if (c.getName().equals(uid) c.getMaxAge() 0)这种永远不会成立的判断。实用写法是把读取封装成一个小工具public static String getCookieValue(HttpServletRequest req, String name) { Cookie[] cookies req.getCookies(); if (cookies null) { return null; } for (Cookie c : cookies) { if (name.equals(c.getName())) { return c.getValue(); } } return null; }遍历顺序上有个隐含前提理论上不可能出现两个 name 完全相同的 Cookie 同时出现在请求头里——因为浏览器判定 Cookie 唯一性的依据是name domain path 三元组同名但 path 不同的两条 Cookie 是可以共存的而它们只在路径同时匹配的请求里才会一起发出去。如果你在/app和/下各存了一条uid访问/app/x时两条都会命中浏览器按路径长度从长到短排列RFC 6265 规定更具体的路径优先于是getCookies()里先出现的会是/app那条。这个顺序在排查“值怎么不对”时非常有用不是乱序的。3. 决定 Cookie 实际行为的几个属性3.1 maxAge正数、负数、0 是三件完全不同的事maxAge是 Cookie 上语义最有意思的一个属性三种取值对应三种完全不同的生命周期取值含义存储位置典型用途正数 N从现在起 N 秒后过期落盘浏览器进程关掉也不丢记住用户名、免登录令牌负数含默认 -1会话 Cookie浏览器关掉即失效内存临时会话标识、单次流程状态0立即过期等于删除——退出登录、清理痕迹会话 Cookie 这个行为值得展开一句。它所谓“关掉浏览器就消失”准确说是“关闭整个浏览器进程”而不是关掉标签页。有些浏览器提供了“恢复上次会话”的功能会把内存里的会话 Cookie 一起恢复导致你以为失效了的东西其实还在。如果要严格保证某条 Cookie 在服务端可控的时限内有效就别依赖会话 Cookie 的隐式过期老老实实给一个正数。另一个常被写错的地方是setMaxAge的值最终会以Max-Age响应头输出而部分老浏览器和某些代理对Max-Age的支持并不一致容器可能会同时输出一个Expires头做兼容。你在抓包里看到两个头并存是正常现象不是配错了。3.2 path 与 domain设了读不到多半栽在这里path用一句话概括它限制的是“哪些请求会自动带上这条 Cookie”不是“哪些代码能读到它”。默认情况下如果你不调用setPath浏览器会按 RFC 6265 的规则取发出该响应的请求 URI 的目录部分作为默认 path。比如你在/app/user/login这个地址返回了Set-Cookie默认 path 就是/app/user那么访问/app/index时浏览器不会带上它——现象就是“明明设置成功了首页死活读不到”。这个问题在本地开发时特别隐蔽你可能正好只在同一个目录下测试怎么都对。一上线前端页面和接口不在一个路径前缀下立刻暴露。domain则是控制 Cookie 的作用域能否跨子域。默认情况下/app下设置的 Cookie 只能被www.example.com这个精确主机读取。如果希望a.example.com和b.example.com共享需要显式设置cookie.setDomain(.example.com)注意前导点不同容器对是否保留前导点的处理略有差异。但这里有个硬性限制你只能把 domain 设成当前域名本身或它的父域不能设成兄弟域或完全不相干的域。a.example.com能设置.example.com但设不了.other.com。这个限制由浏览器执行是 Cookie 无法被当作跨站追踪手段的根本原因之一。还有一条实践建议能精确就不要放大。网关层、鉴权层和应用层往往部署在同一域的不同路径下如果所有 Cookie 都往/上怼键名一冲突就是一场灾难。给每个业务模块一个专属前缀路径是对未来的自己好。3.3 Secure、HttpOnly 与 SameSite三个不该等到出事才补的开关这三个属性都不是“功能开关”而是“风险收敛开关”上线前不补事后补的代价通常包括改代码、改部署、清存量 Cookie。HttpOnly打开后document.cookie读不到这条 Cookie。它挡不住 XSS 本身但能把 XSS 的危害从“窃取会话”降级到“篡改当前页面”。成本几乎为零只要这条值不需要前端 JS 直接读一律加上。Secure打开后浏览器只在加密通道下才发送这条 Cookie。它的作用不是加密内容Cookie 内容本身在传输层就已经被保护了而是防止你在明文通道下漏出标识。开发环境用本地地址跑的时候要留意某些配置下SecureCookie 在明文环境下会被浏览器直接丢弃导致“本地怎么都存不上”这时应该按环境区分配置而不是把Secure关掉。SameSite控制跨站请求时是否携带 Cookie取值一般是Strict、Lax、None。设置为None时通常必须同时打开Secure。在 Servlet 6.0 之前规范里的Cookie类没有直接暴露这个设置入口只能靠容器配置或在响应头里手工拼Servlet 6.0 之后提供了cookie.setAttribute(SameSite, Lax)这样的通用属性设置方法用起来顺多了。如果项目跑在较老的规范上那就去容器配置里统一设默认值别在业务代码里手工拼Set-Cookie字符串——转义和格式出错的概率太高。4. 中文值与特殊字符最容易被容器直接拒掉的地方4.1 value 里塞中文为什么直接 500经常看到的现象是存英文没问题改成中文立刻抛异常堆栈里指向response.addCookie那一行异常信息大意是“cookie value 包含非法字符”。根因在于 Cookie 的语法基础是 RFC 6265它对cookie-value允许出现的字符做了严格限定只能是一段被称为 cookie-octet 的 ASCII 可见字符子集明确排除空格、双引号、逗号、分号、反斜杠这些。中文是多字节字符完全超出这个集合现代容器在输出前会做校验不合法就直接拒绝而不是像早期那样悄悄截断或乱码。这是好事它把问题暴露在了开发阶段而不是等到线上才发现 Cookie 被浏览器丢掉。顺便说一句非 ASCII 的问题不止出现在value上name同样受限而且name的限制更严不能为空、不能以$开头、不能包含分隔符。给 Cookie 起名字这件事稳妥的做法是只用字母、数字、下划线和短横线。4.2 URLEncoder 与 Base64 两条路怎么选解决中文问题有两条常见路径各有适用场景第一条是URLEncoder/URLDecoder。把原始值按 UTF-8 编码成百分号转义序列读回来的时候再解一次。它的优点是结果对人可读性尚可、调试时看得懂缺点是编码后的字符串会变长一个中文字符变成 9 个字符而且URLEncoder原本是为表单编码设计的它会把空格编码成而不是%20虽然对 Cookie 场景影响不大但解码时要注意别用错方法。String raw 张三; String encoded URLEncoder.encode(raw, StandardCharsets.UTF_8); // %E5%BC%A0%E4%B8%89 Cookie c new Cookie(nickname, encoded); // 读取侧 String value getCookieValue(req, nickname); String nickname value null ? null : URLDecoder.decode(value, StandardCharsets.UTF_8);第二条是 Base64。更通用的做法把任意字节序列转成纯 ASCII天生满足 Cookie 的字符约束。它比 URL 编码更短一个中文字符变 8 个字符左右而且不依赖字符集的语义适合存放结构化内容。String raw {\uid\:10086,\n\:\张三\}; String encoded Base64.getUrlEncoder().withoutPadding() .encodeToString(raw.getBytes(StandardCharsets.UTF_8)); Cookie c new Cookie(profile, encoded);注意我用的是getUrlEncoder().withoutPadding()而不是标准 Base64——标准 Base64 会输出、/、这三个字符在某些解码链路上会被当作空格处理放在 Cookie 值末尾虽然大部分情况没事但没必要给自己埋雷。URL 安全变体把换成-、/换成_配合去掉填充输出就是纯字母数字加两个符号非常稳。选择上我的建议是纯文本值用 URLEncoder结构化内容JSON、序列化对象用 URL 安全的 Base64。另外无论选哪种读侧一定要做空值判断和异常兜底——Cookie 是用户完全可控的输入你把一段乱码丢给URLDecoder.decode它会抛IllegalArgumentException这个异常如果没接住整个请求就崩了。用户手工改一下 Cookie 就能让你的接口 500这属于典型的输入校验缺失。5. 三个可以直接抄的场景实现5.1 记住用户名从勾选到回填的完整闭环这是最经典的入门场景但真要做到“干净”需要考虑三件事什么时候写、什么时候读、什么时候清。写登录成功且用户勾选了“记住我”时写入有效期给 7 到 30 天值做 URL 编码加HttpOnly因为回填是服务端渲染时做的不需要 JS 参与。这里有个细节要注意存的应该是用户名而不是密码也不要存“用户名密码的某种组合”然后自动登录那等于把长期凭证明文放在用户机器上。读在渲染登录页之前读取。如果是 JSP 渲染可以在页面顶部用脚本片段取值但更推荐的做法是让 Servlet 先取好通过request.setAttribute传给视图层避免视图里出现大段 Java 代码。清用户主动取消勾选、或者退出登录时发一条同名同路径、Max-Age0的 Cookie 覆盖掉。// 清除 Cookie c new Cookie(username, ); c.setMaxAge(0); c.setPath(req.getContextPath().isEmpty() ? / : req.getContextPath()); resp.addCookie(c);这段代码里setPath那一行是灵魂。删除 Cookie 的本质是发一条同名、同域、同路径、maxAge 为 0 的 Cookie 去覆盖它这三个维度只要有任何一个对不上浏览器就会认为这是两条不同的 Cookie于是旧的还在新的白删。我见过太多“退出登录之后用户名还在”的案例最后都是 path 写成了/而当初写入时用的是/app。5.2 免登录令牌Cookie 里该放什么、不该放什么“下次自动登录”这个功能很多人的第一版实现是往 Cookie 里塞usernamexxx; passwordxxx这属于把家门钥匙焊在门口。正确的心智模型是Cookie 里放的应该是一个无意义的随机串服务端拿这个串去查自己的存储才知道它对应谁。一个可落地的简化方案登录成功时生成一个足够长的随机串比如 32 字节的安全随机数转成十六进制或 Base64存进服务端的令牌表记录token - userId 过期时间 设备标识。把 token 写进 CookiemaxAge给 14 天HttpOnly必开Secure视环境开。每次请求进来先查会话没有会话就查 Cookie 里的 token命中且未过期就重建会话。用户改密码、点“退出所有设备”时把令牌表里对应的记录全部作废。这个方案的关键在于令牌可撤销。它比“把签名信息塞进 Cookie 自己做校验”要笨一些需要一张表但换来了“随时踢人下线”的能力这在真实业务里几乎是一定会被提的需求。这里必须提一句边界不要把敏感信息直接放进 Cookie哪怕做了编码。Base64 是编码不是加密atob一下全出来了。Cookie 存储在任何时候都应该被当作“用户可见、用户可改”的公开区域。你如果非要放结构化数据至少做一次服务端签名读的时候验签验不过就当没有。5.3 浏览记录列表型数据的塞法“最近浏览过的商品”这类需求很多人第一反应是存 Session但 Session 一过期就没了而且多节点部署还得考虑共享。用 Cookie 落盘反而更合适——数据本来就跟用户设备绑定不需要跨设备同步。方案是把列表序列化成 JSON做 URL 安全的 Base64塞进一条 CookieListLong ids new ArrayList(recentIds); ids.add(0, currentProductId); // 去重并截断到 10 条 ListLong trimmed ids.stream().distinct().limit(10).collect(Collectors.toList()); String json JSON.toJSONString(trimmed); String value Base64.getUrlEncoder().withoutPadding() .encodeToString(json.getBytes(StandardCharsets.UTF_8)); Cookie c new Cookie(recent, value); c.setMaxAge(60 * 60 * 24 * 30); c.setPath(/); resp.addCookie(c);这里必须精打细算长度。单个 Cookie 的容量上限在主流浏览器里大约是 4KB包含 name、value 和属性。10 个商品 ID 大概 80 字节编码后 110 字节左右非常安全但如果你的“浏览记录”里存的是商品标题、图片地址、价格几十个商品就能轻松顶到上限超出的部分会被浏览器直接丢弃而且不报错——现象是“有时候记录全没了”极难排查。所以列表型 Cookie 只存 ID 这类轻量标识展示数据走一次查询别偷懒。6. Cookie 删不掉、删不干净的真实排查链路6.1 删除动作的本质是覆盖前面提过一次这里把完整的排查顺序列清楚因为这是实践中最容易卡住的一类问题。现象是调用退出接口响应 200刷新页面用户名还在。第一步抓包看响应头里到底有没有Set-Cookie。有时候是业务代码走了 else 分支根本没执行删除逻辑先排除这个。第二步看这条Set-Cookie的Max-Age是不是 0或者Expires是不是一个过去的时间点。setMaxAge(0)是正确写法写成setMaxAge(-1)那是会话 Cookie不但不删还会把原来的持久化 Cookie 覆盖成会话级别。第三步也是最关键的一步逐字段比对删除用的 Cookie 和当初写入的 Cookie重点看 name、path、domain 三项。name 必须完全相同大小写敏感path 必须完全相同/app和/app/在某些实现里会被视为不同值domain 必须完全一致一个有前导点一个没有浏览器可能认为是两个域。第四步确认没有别的地方在重复写入。比如拦截器、过滤器里给每个响应都补了一条同名 Cookie你在业务层删了过滤器又给写回去了抓包会看到响应里同时有两条Set-Cookie且顺序在业务逻辑之后。如果这四步都排除了还是删不掉那就要怀疑是不是有同名的 Cookie 在另一个路径下存在你以为删的是 A实际读的时候拿到的是 B。这时候在浏览器开发者工具里看 Cookie 列表把 Path 那一列展开通常一眼就能看出问题。6.2 同名 Cookie 的覆盖顺序与多应用共存的坑“同名覆盖”这件事有一个常被误解的点两个同名 Cookie 是否互相覆盖取决于它们的 domain 和 path 是否也相同。三元组完全相同才会覆盖否则就是两条独立记录共存。这个特性会在一种场景下咬人你有一个老系统部署在/legacy下新系统部署在/下两边都用uid这个键名。用户在两个系统间跳转的时候浏览器会在访问/legacy/*时同时带上两条uid而这两个值是完全不同步的。表现出来就是“用户在新系统登录了进老系统还是旧身份”或者“在老系统退出了登录新系统看着还登着”。排查这种问题时如果只盯着自己那一侧代码永远找不到原因。处理办法有两个方向一是加前缀新系统统一用app_uid这类带业务前缀的键名物理隔离成本最低二是收窄 path让每个应用的 Cookie 只在自己路径下生效但这条路有个前提就是所有相关请求都必须落在该路径下网关转发、静态资源这些容易漏。实际项目里我更推荐第一种改个名字的事别跟路径较劲。还有一条Cookie 的数量限制是按域名算的不是按 path 算。主流浏览器每个域名能存的 Cookie 数量在几十到上百条的量级具体数值各家不同。一个长期运营的项目如果每个功能模块都随手塞一两百字节的 Cookie 且只增不减几年下来真的会碰到上限。到那时候的表现是“新功能的 Cookie 存不进去而且没有任何错误提示”非常难查。所以从一开始就养成习惯给每条 Cookie 一个明确的生命周期用完就清别把它当免费的本地存储。7. Cookie 的能力边界与 Session 的分工7.1 为什么登录状态这件事不该塞进 Cookie回到最开始那个链路浏览器会自动携带 Cookie且把 Cookie 内容原封不动交给服务端。这两条决定了 Cookie 值天然是不可信输入任何直接信任其中内容的写法都是在裸奔。于是就有了分工Cookie 只负责“带一个标识”真正的状态数据放在服务端这个组合就是 Session。Session 的工作方式是容器生成一个 sessionId通过 Cookie默认键名通常类似JSESSIONID下发给浏览器服务端自己维护sessionId - 数据的映射。用户看到的是“登录状态保持了”实际发生的是“每次请求带个号码服务端拿号码查自己的本子”。这个分工带来三个直接好处状态数据不出服务端攻击面小得多数据量不受 4KB 限制可以随时在服务端作废。代价是服务端要有地方存这些数据单机时代无所谓多节点时代就要引入共享存储或者会话粘滞。这就是为什么很多项目最终走向了“Cookie 里放一个签名的 Token状态数据放服务端缓存”的混合方案——它保留了 Cookie 的轻量又拿回了无状态扩展的能力。理解这条演进线比背下 Session 的 API 有用得多。因为你在设计任何一个需要“跨请求记住点什么”的功能时脑子里应该先问三个问题这个数据敏感吗它需要被服务端撤销吗它会有多大三个问题的答案基本就决定了该往 Cookie 里放什么、放多少。7.2 浏览器侧的几个硬限制与扩容思路最后把几个硬性边界集中列一下都是开发和运维都会碰到的限制项大致量级触发后的表现单条 Cookie 大小约 4KB含 name、value、属性超出部分被静默丢弃只在控制台留提示单域名 Cookie 条数几十到上百条随浏览器而异新 Cookie 无法写入无错误抛出域与路径匹配只能设置当前域或其父域设置被浏览器忽略值字符集受限 ASCII 子集容器侧直接抛异常或浏览器侧丢弃碰到容量不够常规的扩容思路有几种拆分多条 Cookie把一个大 JSON 拆成data_0、data_1这只解决单条超限不解决条数超限把数据挪到服务端Cookie 只留一个 key这是最干净的方案再有就是把这类数据从 Cookie 迁移到浏览器本地存储但本地存储不会被自动携带需要前端配合而且同样要面对 XSS 的风险。我个人的经验是只要某个 Cookie 的值开始接近 1KB就应该停下来想一想是不是放错地方了。Cookie 最适合的形态始终是“短小、无意义、只作标识”的一小段字符串它天生就不是用来存数据的容器。把它用在正确的定位上前面那些 path 对不上、删不掉、容量爆掉的问题绝大多数根本不会发生。