用途
该技能面向使用 TanStack Start 框架(具体为 @tanstack/react-start v1.168.58)的开发者,帮助创建同源、类型安全的 RPC 服务端函数,即通过 createServerFn 定义的函数。这些函数仅在服务端运行,但可从 loader、组件、hooks 及其他服务端函数中调用。
主要能力
- 创建服务端函数:使用 createServerFn 定义函数,支持指定 HTTP 方法(如 POST),并通过 .validator() 进行 Zod 输入验证,.handler() 编写服务端逻辑。
- 调用方式:可从 loader、组件、hooks 中直接调用;当函数抛出 redirect() 或 notFound() 时,组件内必须使用 useServerFn 包装,以将抛出行为接入路由器。普通数据函数使用 useServerFn 为可选。
- 序列化约束:默认开启严格序列化,验证器输入和处理器返回类型必须可序列化;FormData 可作为 POST 输入,Response 可作为输出;strict: false 仅关闭 TypeScript 检查,不改变运行时行为。
- 安全规则:服务端函数是独立 HTTP 端点,路由的 beforeLoad 重定向仅保护 UI,不保护 RPC;对于涉及私有数据的函数,认证必须放在 .handler() 或中间件内。
- 架构分离:服务端函数包装器放在 .functions.ts(可安全从任意位置导入),仅服务端的辅助代码(数据库查询、密钥、文件系统访问)放在 .server.ts,共享 Zod 模式放在 schemas.ts。构建时客户端包会用 RPC 桩替换函数体,因此从客户端组件静态导入 .functions.ts 是安全的。
- 模板:提供完整 CRUD 模块模板(crud-server-functions.md)和 FormData 提交与 Zod 验证模板(form-with-validation.md)。
使用方式
基本模式为:从 @tanstack/react-start 导入 createServerFn,用 .validator() 声明输入模式,用 .handler() 编写服务端逻辑,然后在客户端调用。若函数抛出 redirect() 或 notFound(),在组件中使用 useServerFn(signup) 包装后再调用。开发前需先通过 Context7 和 Exa 核对当前 API,并探索目标代码库;变更后运行 fuse-ai-pilot:sniper。
适用场景
- 应用内部类型安全的 RPC 调用
- 在 loader 中进行数据获取
- 从事件处理器发起变更操作
- 需要 Zod 验证的 FormData 表单提交
限制
- 不适用于原始外部/公开 HTTP 端点(应使用 start-server-routes 技能)
- 不适用于可组合的认证/日志中间件链(应使用 start-middleware 技能)
- 不适用于 Next.js/Remix 的 "use server" 模式、getServerSideProps、Remix loader/action 或 react-router-dom
- 不要在 loader 中放置数据库查询或密钥,因为 loader 是同构的(客户端和服务端都会运行)
- 不要动态 import() 服务端函数,会破坏打包器的 tree-shaking
- 不要依赖路由守卫保护服务端函数
暂未提供
该技能的收费、价格、平台可用性、效果指标等具体信息暂未提供。