aptx-api-plugin-csrf（aptx API plugin csrf 文档）

aptx-api-plugin-csrf

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

1. 使用 createCsrfMiddleware({cookieName, headerName, sameOriginOnly, getCookie}) 创建中间件
2. 根据环境选择配置：

- 浏览器环境：使用默认 getCookie（自动使用 document.cookie） - SSR/Node 环境：必须提供自定义 getCookie 函数

1. 保持 sameOriginOnly: true（默认），避免跨域请求误注入 CSRF 头
2. 确认前后端约定的 cookie/header 名称一致
3. 将中间件挂载到 RequestClient.use() 或构造函数

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

快速参考

何时添加 CSRF token:

最小模板

浏览器环境

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

环境适配要点

环境差异

关键约束

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

详细文档