aptx-api-plugin-csrf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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。

在接入 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 不存在	❌

选项	类型	默认值	说明
`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 { 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,
}));

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
  }
});

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;
  }
});

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（始终同源）

环境	`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

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	常见问题、故障排查、调试技巧

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