java cookie utils

admin 2026年02月04日 16:20 101 0

Java Cookie Utils是封装HTTP Cookie操作的工具类，简化Cookie的创建、设置、获取与删除等流程，支持设置路径、域名、过期时间等属性，并提供中文编码处理（如URL编码/解码），通过request.getCookies()获取请求中的Cookie，response.addCookie()添加响应Cookie，常用于用户登录状态管理、个性化配置存储等场景，提升Cookie操作的便捷性与安全性。

Java Cookie 工具类：高效处理 HTTP Cookie 的实用指南

在 Web 开发中，Cookie 是一种不可或缺的客户端存储技术，用于在用户浏览器和服务器之间传递状态信息（如用户登录状态、购物车数据、用户偏好设置等），Java 原生的 javax.servlet.http.Cookie 类提供了基本的 Cookie 操作功能，但在实际开发中，我们往往需要更加便捷的工具类来简化编码工作——例如处理 Cookie 的编码/解码、过期时间设置、安全属性配置等，本文将围绕 Java Cookie 工具类（Cookie Utils），从核心功能、代码实现到最佳实践，全面介绍如何高效处理 HTTP Cookie，提升开发效率并确保安全性。

Cookie 核心属性回顾

在实现工具类前,我们需要先明确 Cookie 的核心属性，这些是工具类需要重点封装的对象：

属性名	类型	说明
`name`	String	Cookie 的名称（必填，需符合 RFC 6265 规范，不能包含空格、逗号等特殊字符）
`value`	String	Cookie 的值（建议 URL 编码，避免特殊字符问题）
`maxAge`	int	存活时间（秒）：`-1` 表示会话 Cookie（浏览器关闭后删除），`0` 表示立即删除
`domain`	String	域名（如 `".example.com"`，可跨子域；未设置时默认当前域名）
`path`	String	路径（如 `"/api"`，只有匹配该路径的请求才会携带 Cookie）
`secure`	boolean	是否仅通过 HTTPS 传输（生产环境建议开启）
`httpOnly`	boolean	是否禁止 JavaScript 访问（防止 XSS 攻击，建议开启）
`sameSite`	String	同站策略（`Strict`/`Lax`/`None`，防范 CSRF 攻击，需结合 `secure` 使用）

注意事项：

Cookie 名称和值应符合 RFC 6265 标准，避免使用空格、逗号、分号等特殊字符
对于包含中文等非 ASCII 字符的值，必须进行 URL 编码
SameSite 属性在现代浏览器中已成为安全标配，建议根据业务场景合理配置

原生 Cookie 操作的痛点

直接使用 HttpServletRequest 和 HttpServletResponse 处理 Cookie 时，开发人员常遇到以下问题：

编码繁琐：Cookie 值需手动 URL 编码/解码，否则中文等特殊字符会导致乱码问题
属性设置复杂：每次创建 Cookie 都需单独设置 domain、path、maxAge 等属性，重复代码多且容易遗漏
删除逻辑不直观：删除 Cookie 需重新创建同名 Cookie 并设置 maxAge=0，容易因 path 或 domain 不匹配导致删除失败
同名 Cookie 处理：一个域名/路径下可能存在多个同名 Cookie（不同路径下），原生 API 需遍历数组手动处理
安全属性配置不统一：安全相关的属性（如 secure、httpOnly、sameSite）容易被忽略，存在安全隐患

Cookie Utils 工具类核心功能设计

针对上述痛点,Cookie Utils 工具类应封装以下核心功能：

创建 Cookie（支持链式调用）

提供流畅的 API，允许连续设置 Cookie 属性（如域名、路径、过期时间等），提高代码可读性。

编码/解码处理

自动对 Cookie 值进行 URL 编码（写入时）和解码（读取时），解决中文等特殊字符的乱码问题。

添加到响应

将 Cookie 添加到 HttpServletResponse，自动处理 Set-Cookie 头的拼接，并确保属性顺序符合浏览器要求。

从请求中获取

从 HttpServletRequest 中解析 Cookie，支持按名称获取单个 Cookie 或获取所有 Cookie，返回 Optional 避免 NPE。

删除 Cookie

通过覆盖同名 Cookie 并设置 maxAge=0 实现删除，自动匹配原始 domain 和 path，确保删除操作成功。

同名 Cookie 处理

提供获取最新同名 Cookie 或按路径过滤的方法，处理多路径下的同名 Cookie 问题。

批量操作

支持批量添加、删除 Cookie，减少重复代码。

安全属性默认配置

提供安全相关的默认配置方法,确保 Cookie 安全性。

Cookie Utils 工具类代码实现

以下是一个基于 Java Servlet 的 Cookie Utils 工具类完整实现，支持链式调用和常用操作：

import javax.servlet.http.Cookie;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.UnsupportedEncodingException;
import java.net.URLDecoder;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Optional;
import java.util.stream.Collectors;
/**
 * Cookie 工具类，简化 Cookie 的创建、设置、获取和删除操作
 */
public final class CookieUtils {
    private CookieUtils() {
        // 工具类不允许实例化
    }
    /**
     * 创建 Cookie（支持链式调用）
     *
     * @param name  Cookie 名称
     * @param value Cookie 值
     * @return CookieBuilder
     */
    public static CookieBuilder newCookie(String name, String value) {
        return new CookieBuilder(name, value);
    }
    /**
     * 从请求中获取指定名称的 Cookie
     *
     * @param request HttpServletRequest
     * @param name    Cookie 名称
     * @return Optional<Cookie>（避免 NPE）
     */
    public static Optional<Cookie> getCookie(HttpServletRequest request, String name) {
        if (request == null || name == null) {
            return Optional.empty();
        }
        Cookie[] cookies = request.getCookies();
        if (cookies == null || cookies.length == 0) {
            return Optional.empty();
        }
        return Arrays.stream(cookies)
                .filter(cookie -> name.equals(cookie.getName()))
                .findFirst();
    }
    /**
     * 从请求中获取所有指定名称的 Cookie（处理同名 Cookie）
     *
     * @param request HttpServletRequest
     * @param name    Cookie 名称
     * @return List<Cookie>
     */
    public static List<Cookie> getCookies(HttpServletRequest request, String name) {
        if (request == null || name == null) {
            return Collections.emptyList();
        }
        Cookie[] cookies = request.getCookies();
        if (cookies == null || cookies.length == 0) {
            return Collections.emptyList();
        }
        return Arrays.stream(cookies)
                .filter(cookie -> name.equals(cookie.getName()))
                .collect(Collectors.toList());
    }
    /**
     * 删除指定名称的 Cookie（需匹配 domain 和 path）
     *
     * @param response HttpServletResponse
     * @param name     Cookie 名称
     * @param domain   Cookie 域名（需与创建时一致）
     * @param path     Cookie 路径（需与创建时一致）
     */
    public static void deleteCookie(HttpServletResponse response, String name, String domain, String path) {
        Cookie cookie = new Cookie(name, "");
        cookie.setMaxAge(0);
        if (domain != null) {
            cookie.setDomain(domain);
        }
        if (path != null) {
            cookie.setPath(path);
        }
        response.addCookie(cookie);
    }
    /**
     * 删除指定名称的 Cookie（使用默认域名和路径）
     *
     * @param response HttpServletResponse
     * @param name     Cookie 名称
     */
    public static void deleteCookie

标签： #cookie #utils #工具