文档中心

探索 DWeb 框架的无限可能，构建下一代高性能 Web 应用

Cookie

DWeb 框架提供了完整的 Cookie 管理功能，支持 Cookie 的设置、读取、删除和签名。

快速开始

基本使用

Code
import { CookieManager } from "@dreamer/dweb";

// 创建 Cookie 管理器
const cookieManager = new CookieManager("your-secret-key");

// 在请求处理中使用
server.setHandler(async (req, res) => {
  // 设置 Cookie
  const cookieString = cookieManager.set("username", "john", {
    maxAge: 3600, // 1 小时
    httpOnly: true,
    secure: true,
    sameSite: "lax",
  });
  res.setHeader("Set-Cookie", cookieString);

  // 读取 Cookie
  const cookies = cookieManager.parse(req.headers.get("Cookie"));
  const username = cookies.username;

  // 删除 Cookie
  const deleteCookie = cookieManager.delete("username");
  res.setHeader("Set-Cookie", deleteCookie);

  res.text("OK");
});

使用签名 Cookie

Code
// 创建带签名的 Cookie 管理器
const cookieManager = new CookieManager("your-secret-key");

// 设置签名 Cookie（异步）
const cookieString = await cookieManager.setAsync("session", "session-id", {
  maxAge: 3600,
  httpOnly: true,
});

// 解析签名 Cookie（异步，自动验证签名）
const cookies = await cookieManager.parseAsync(req.headers.get("Cookie"));
const session = cookies.session; // 自动验证签名，如果签名无效则不会包含在结果中

配置 Cookie

在 dweb.config.ts 中配置 Cookie：

Code
// dweb.config.ts
cookie: {
  // Cookie 密钥（必需）
  secret: 'your-secret-key',
  
  // 默认选项
  httpOnly: true,
  secure: false,
  sameSite: 'lax',
  maxAge: 3600,
},

在路由中使用 Cookie

在页面或 API 路由中使用 Cookie：

Code
// 在路由中使用 Cookie
import type { LoadContext } from '@dreamer/dweb';

export async function load({ getCookie, setCookie }: LoadContext) {
  // 读取 Cookie
  const token = getCookie('token');
  
  // 设置 Cookie
  setCookie('token', 'value', {
    maxAge: 3600,
    httpOnly: true,
    secure: true,
  });
  
  return { token };
}

使用场景

Code
// 用户偏好设置
const cookie = cookieManager.set("theme", "dark", {
  maxAge: 365 * 24 * 60 * 60, // 1 年
  path: "/",
});

// 会话管理（带签名）
const sessionCookie = await cookieManager.setAsync("session", sessionId, {
  maxAge: 3600, // 1 小时
  httpOnly: true,
  secure: true,
  sameSite: "strict",
});

// 购物车
const cartData = JSON.stringify(cartItems);
const cookie = cookieManager.set("cart", cartData, {
  maxAge: 7 * 24 * 60 * 60, // 7 天
  path: "/",
});

API 参考

CookieManager

Code
new CookieManager(secret?: string)

**参数**：

  • secret - 可选，用于签名 Cookie 的密钥

方法

set(name, value, options?)

设置 Cookie（同步，不支持签名）。

Code
const cookie = cookieManager.set("theme", "dark", {
  maxAge: 86400, // 1 天
  path: "/",
  domain: "example.com",
  secure: true,
  httpOnly: true,
  sameSite: "lax",
});
res.setHeader("Set-Cookie", cookie);

setAsync(name, value, options?)

设置 Cookie（异步，支持签名）。

Code
const cookie = await cookieManager.setAsync("session", "session-id", {
  maxAge: 3600,
  httpOnly: true,
});
res.setHeader("Set-Cookie", cookie);

parse(cookieHeader)

解析 Cookie（同步，不支持签名验证）。

Code
const cookies = cookieManager.parse(req.headers.get("Cookie"));
const theme = cookies.theme;

parseAsync(cookieHeader)

解析 Cookie（异步，支持签名验证）。

Code
const cookies = await cookieManager.parseAsync(req.headers.get("Cookie"));
const session = cookies.session; // 已通过签名验证

delete(name, options?)

删除 Cookie。

Code
const deleteCookie = cookieManager.delete("session", {
  path: "/",
  domain: "example.com",
});
res.setHeader("Set-Cookie", deleteCookie);

CookieOptions

Code
interface CookieOptions {
  path?: string; // Cookie 路径，默认 '/'
  domain?: string; // Cookie 域名
  expires?: Date; // 过期时间
  maxAge?: number; // 最大存活时间（秒）
  secure?: boolean; // 是否仅在 HTTPS 下发送
  httpOnly?: boolean; // 是否禁止 JavaScript 访问，默认 true
  sameSite?: "strict" | "lax" | "none"; // SameSite 属性
}

安全最佳实践

  • 使用签名 Cookie：对于敏感数据（如会话 ID），使用 setAsync 和 parseAsync 方法
  • 设置 HttpOnly：防止 XSS 攻击，禁止 JavaScript 访问 Cookie
  • 设置 Secure：在生产环境中启用，确保 Cookie 仅在 HTTPS 下传输
  • 设置 SameSite：防止 CSRF 攻击
  • 使用强密钥：签名密钥应该足够长且随机
Code
// 安全的 Cookie 配置
const cookie = await cookieManager.setAsync("session", sessionId, {
  maxAge: 3600,
  httpOnly: true, // 防止 XSS
  secure: true, // 仅 HTTPS
  sameSite: "strict", // 防止 CSRF
  path: "/",
});

相关文档