用途:Server Functions 是 TanStack Start 中用 createServerFn 创建的类型安全 RPC,只在服务端运行,但可从 loader、组件、hook、事件处理器或其它服务端函数调用。
主要能力:支持 GET(默认)与 POST 方法;用 .validator() 做输入校验,可传普通函数或 Zod schema,也支持 FormData;支持抛出错误、redirect、notFound;提供请求上下文工具 getRequest、getRequestHeader、setResponseHeader、setResponseHeaders、setResponseStatus,用于读取请求与设置响应头和状态码;可配合 middleware 组合使用。
使用方式:定义 createServerFn({ method: 'POST' }).validator(...).handler(async ({ data }) => ...),在 loader 中直接调用;在组件事件处理器中通过 useServerFn 包装后调用。文件建议拆分:.functions.ts 放 createServerFn 包装(可安全静态导入),.server.ts 放仅服务端辅助逻辑,schemas.ts 放共享校验。
适用场景:数据库查询、文件系统访问、密钥 API 调用等仅服务端逻辑,应放入 createServerFn,而不是直接写在同构的 loader 中。
限制与注意事项:Server Functions 是 API 端点,可绕过路由 UI 直接调用,涉及私有数据必须在 handler 或 middleware 内做鉴权;不要使用 "use server"、getServerSideProps 或 Next.js/Remix 模式;避免动态 import 服务端函数;调用时必须加括号;鉴权响应不要用 Cache-Control: public,应使用 private 或 no-store 并配合 Vary;当函数抛出 redirect 或 notFound 时需用 useServerFn 包装。