用途:Server Functions 是用 createServerFn 创建的类型安全 RPC,只在服务端运行,但可从 loader、组件、hook、事件处理器或其他 server function 调用。
主要能力:支持 GET(默认)与 POST;用 .validator() 做输入校验,可传函数或 Zod schema,也支持 FormData;用 useServerFn 在事件处理器中调用;服务端上下文工具包括 getRequest、getRequestHeader、setResponseHeader、setResponseHeaders、setResponseStatus;可抛 Error、redirect、notFound。
使用方式:从 @tanstack/react-start 导入 createServerFn,链式调用 .validator().handler();在 loader 中直接调用,在组件中用 useServerFn 包装后调用。写操作后应 await 写入并 router.invalidate({ sync: true }) 使路由缓存失效。文件组织建议 users.functions.ts 放 server function、users.server.ts 放仅服务端逻辑、schemas.ts 放共享校验。静态导入 server function 是安全的,构建时会替换为 RPC stub。
限制与安全:server function 是 API 端点,可被独立调用,鉴权必须在 handler 或 middleware 内强制,路由 beforeLoad 只是 UX 而非数据边界;loader 是同构的,数据库、文件系统、密钥必须放进 createServerFn;不要用 "use server"、getServerSideProps 或 Next.js/Remix 模式;鉴权响应不可用 Cache-Control: public,应使用 private 或 no-store 并加 Vary;避免动态导入 server function、忘记调用函数、在 loader 中自请求相对 API URL。当函数会抛 redirect/notFound 时必须用 useServerFn 包装。