用途:在 TanStack Start 中编写服务器函数与服务器路由的中间件。中间件可组合,一个中间件可依赖其他中间件形成有序链。需从 @tanstack/react-start 导入 createMiddleware,技能针对 v1.168.58。
主要能力:请求中间件(createMiddleware(),作用于全部服务器请求,仅含 .server(),无输入校验、无客户端逻辑)与服务器函数中间件(createMiddleware({ type: 'function' }),仅作用于服务器函数,含 .client() 与 .server(),支持 .validator() 校验)。请求中间件不能依赖服务器函数中间件;服务器函数中间件可依赖两者。附带认证 + 基于权限的授权工厂模板,以及客户端中间件(请求头、自定义 fetch、遥测)模板。
必要用法与规则:方法链顺序由 TypeScript 强制为 .middleware() → .validator() → .client() → .server(),其他顺序会类型报错。形状校验不等于授权:对来自 sendContext 的值作为查询键、过滤条件或路径参数使用前,必须基于服务器信任的会话重新校验访问权限。客户端 context 默认不发送到服务器,需通过 next({ sendContext }) 显式选择;客户端发送的任何内容都可能被伪造,会话应来自服务器可信来源(cookie + DB)。.client() 在 SSR 时运行于服务器,浏览器专属 API 需用 typeof window !== 'undefined' 守卫。staticFunctionMiddleware(来自 @tanstack/start-static-server-functions,实验性)必须始终位于链末。
限制:不用于定义 RPC 本身(用 start-server-functions)、原始 HTTP 端点(用 start-server-routes)或路由级 UX 守卫(用 router beforeLoad)。工作流要求实现前用 Context7 与 Exa 核对当前 API 并探索目标代码库,改动后运行 fuse-ai-pilot:sniper。实施细节与完整模板见随附的 auth-authorization.md、client-middleware.md、types.md、context.md、global.md 文档。