aptx-api-plugin-csrf

在接入 CSRF 插件时，执行以下流程：

1. 使用 createCsrfMiddleware({ cookieName, headerName, sameOriginOnly, getCookie }) 创建中间件
2. 根据环境选择配置：
   • 浏览器环境：使用默认 getCookie（自动使用 document.cookie）
   • SSR/Node 环境：必须提供自定义 getCookie 函数
3. 保持 sameOriginOnly: true（默认），避免跨域请求误注入 CSRF 头
4. 确认前后端约定的 cookie/header 名称一致
5. 将中间件挂载到 RequestClient.use() 或构造函数

注意: 需要同时安装 @aptx/api-core 作为 peer dependency。

---

快速参考

选项	类型	默认值	说明
cookieName	string	"XSRF-TOKEN"	CSRF cookie 名称
headerName	string	"X-XSRF-TOKEN"	写入 CSRF token 的 header 名称
sameOriginOnly	boolean	true	仅在同源请求中附加 token
getCookie	(name) => string | undefined	浏览器默认使用 document.cookie	自定义 cookie 读取函数（SSR 必须提供）

何时添加 CSRF token:

场景	添加 token
Cookie 存在 + sameOriginOnly: false	✅
Cookie 存在 + sameOriginOnly: true + 同源请求	✅
Cookie 存在 + sameOriginOnly: true + 跨域请求	❌
Cookie 不存在	❌

---

最小模板

浏览器环境

import { RequestClient } from "@aptx/api-core";
import { createCsrfMiddleware } from "@aptx/api-plugin-csrf";

const client = new RequestClient({
  middlewares: [
    createCsrfMiddleware({
      cookieName: "XSRF-TOKEN",
      headerName: "X-XSRF-TOKEN",
      sameOriginOnly: true,
      // 浏览器环境下不需要 getCookie，自动使用 document.cookie
    })
  ]
});

渐进式增强

import { createCsrfMiddleware } from "@aptx/api-plugin-csrf";

const client = new RequestClient();
client.use(createCsrfMiddleware({
  cookieName: "XSRF-TOKEN",
  headerName: "X-XSRF-TOKEN",
  sameOriginOnly: true,
}));

SSR/Next.js 环境

import { createCsrfMiddleware } from "@aptx/api-plugin-csrf";
import { cookies } from 'next/headers';

const csrf = createCsrfMiddleware({
  cookieName: "XSRF-TOKEN",
  headerName: "X-XSRF-TOKEN",
  sameOriginOnly: true,
  getCookie: (name) => {
    const cookieStore = cookies();
    return cookieStore.get(name)?.value;  // SSR 必须提供 getCookie
  }
});

Node.js/Express 环境

import { createCsrfMiddleware } from "@aptx/api-plugin-csrf";

const csrf = createCsrfMiddleware({
  cookieName: "XSRF-TOKEN",
  headerName: "X-XSRF-TOKEN",
  sameOriginOnly: true,
  getCookie: (name) => {
    const cookies = req.cookies;  // 从 cookie-parser 或 req.headers.cookie 读取
    const value = cookies?.[name];
    return value ? decodeURIComponent(value) : undefined;
  }
});

---

环境适配要点

环境差异

环境	document.cookie	window.location	默认 getCookie	默认 isSameOrigin
浏览器	✓ 可用	✓ 可用	✓ 使用 document.cookie	✓ 检查 origin
SSR (Next.js)	✗ undefined	✗ undefined	✗ 需要自定义 getCookie	✓ 返回 true（始终同源）
Node.js	✗ undefined	✗ undefined	✗ 需要自定义 getCookie	✓ 返回 true（始终同源）

关键约束

• SSR/Node 环境必须提供 getCookie 函数，否则会报错 document is not defined
• getCookie 返回原始 cookie 值，中间件会自动 decodeURIComponent，不要手动解码
• 默认 sameOriginOnly: true 对大多数用例是安全的
• Cookie 值在读取时自动进行 URL 解码，然后添加到 header

---

详细文档

文档	内容
API Details	完整 API 文档、配置选项详解、默认实现
Environment Adaptation	浏览器/SSR/Node 环境详细适配指南
Testing Guide	测试策略、测试示例代码
Troubleshooting	常见问题、故障排查、调试技巧