用途
中间件用于定制服务器函数(server functions)与服务器路由(server routes)的行为。中间件具备可组合性,可以依赖其他中间件,从而构成一条中间件执行链。
两类中间件
| 特性 | 请求中间件(Request Middleware) | 服务器函数中间件(Server Function Middleware) |
|---|---|---|
| 作用范围 | 所有服务器请求(SSR、路由、函数) | 仅服务器函数 |
| 方法 | .server() |
.client()、.server() |
| 输入校验 | 无 | 有(.validator()) |
| 客户端逻辑 | 无 | 有 |
| 创建方式 | createMiddleware() |
createMiddleware({ type: 'function' }) |
请求中间件不能依赖服务器函数中间件;服务器函数中间件可以依赖两种类型的中间件。
重要约束
- TypeScript 强制方法顺序:
middleware()→validator()→client()→server()。顺序错误会导致类型错误。 - 校验
sendContext的形状(例如z.string().uuid().parse(...))不是授权。一个通过校验的标识符只是格式正确的标识符,并不代表已授权。在使用客户端发送的 ID 作为查询键、过滤条件或路径参数之前,必须针对会话主体(session principal)重新检查访问权限。
主要能力
请求中间件:在所有服务器请求上运行。示例中通过 createMiddleware().server(...) 记录请求日志。
服务器函数中间件:同时具有客户端与服务端两个阶段。.client() 在 RPC 调用前与响应后在客户端运行,.server() 在处理器前后在服务器运行。
将中间件挂载到服务器函数:通过 createServerFn().middleware([authMiddleware]).handler(...),处理器中的 context 包含来自中间件的数据。
通过 next() 传递上下文:next({ context: { session } }) 可将上下文沿中间件链向下传递,下游中间件能带类型地读取 context.session。
客户端与服务端之间传递上下文(sendContext):
- 客户端 → 服务端:在
.client()中next({ sendContext: { workspaceId } }),服务端可读取,但需校验。 - 服务端 → 客户端:在
.server()中next({ sendContext: { timeFromServer } }),客户端中间件可通过result.context.timeFromServer读取。
中间件中的输入校验:结合 zodValidator 在 .validator() 中定义 schema,服务端可从 data 读取校验后的值。
全局中间件:在 src/start.ts 中通过 createStart(() => ({ requestMiddleware: [...], functionMiddleware: [...] })) 配置。
与服务器路由配合使用:可在路由的 server.middleware 中为所有处理器挂载中间件,也可在 createHandlers 中仅为特定处理器(如 POST)挂载。
中间件工厂:可创建带参数的中间件以复用模式,例如基于权限的 authorizationMiddleware(permissions)。文中强调:服务器函数是 API 端点,路由的 beforeLoad 只保护路由 UI,不保护数据,需保护读取或修改私有数据的端点。
自定义请求头与 fetch:客户端中间件可通过 next({ headers: {...} }) 设置请求头,请求头会跨中间件合并,后面的覆盖前面的,调用点请求头优先级最高。也可传入 CustomFetch。fetch 优先级从高到低:调用点 → 较后的中间件 → 较前的中间件 → createStart 全局 → 默认 fetch。
常见错误
- 严重:信任客户端的 sendContext。形状检查不等于访问检查。正确做法是三层:先用 Zod 校验形状,再结合会话主体验证成员资格(如
db.memberships.find(...)),不通过则抛错。会话本身必须来自服务器可信来源(cookie + 数据库查询),绝不能来自 sendContext。 - 中等:混淆请求中间件与服务器函数中间件。前者作用于所有请求,后者仅作用于
createServerFn调用且带.client()。 - 高:在
.client()中使用浏览器 API 会在 SSR 时崩溃。SSR 期间.client()回调在服务器运行,localStorage、window会抛 ReferenceError,需用 cookie/header 或typeof window !== 'undefined'守卫。 - 中等:方法顺序错误。
适用场景
适用于 TanStack Start 项目中对服务器函数与服务器路由进行日志记录、认证授权、上下文传递、请求头注入、自定义 fetch、输入校验等横切关注点的处理。
限制
- 请求中间件不能依赖服务器函数中间件。
- 方法调用顺序受 TypeScript 约束。
- 浏览器专用 API 在
.client()于 SSR 期间不可用。 - 客户端发送的数据不可信,必须重新做访问校验。