aptx-api-plugin-csrf
在接入 CSRF 插件时，执行以下流程：
- 使用
createCsrfMiddleware({ cookieName, headerName, sameOriginOnly, getCookie }) 创建中间件
- 根据环境选择配置：
- 浏览器环境：使用默认
getCookie（自动使用 document.cookie）
- SSR/Node 环境：必须提供自定义
getCookie 函数
- 保持
sameOriginOnly: true（默认），避免跨域请求误注入 CSRF 头
- 确认前后端约定的 cookie/header 名称一致
- 将中间件挂载到
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
详细文档