执行契约
- 适用场景
- Webhook、外部客户端或标准 HTTP 集成需要稳定端点。
- 不要使用
- 仅供同一 Start 应用内部调用且需要端到端类型时，优先 Server Function。
- 前置检查
- 定义方法、路径、输入、状态码、响应 Schema、鉴权方式和幂等要求。
- 验证结果
- 用独立 HTTP 客户端测试成功、无权限、非法输入和未找到响应。
- 失败模式
- 外部调用出现 HTML 或 200 错误体时，检查是否显式返回 Response、状态码和 Content-Type。
- 安全边界
- 外部入口必须验证身份、授权、输入大小与重放风险；不要依赖浏览器同源保护。
选择条件
应用内部、同源、需要端到端类型的 RPC 使用 Server Function。Webhook、移动端、第三方集成或必须遵守独立 HTTP 契约的入口使用 Server Route。
最小实现
在文件路由的 server.handlers 中返回 Response。所有失败分支都要显式选择状态码；页面级 notFound() 控制流不是 Server Route 的 404 响应。
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/api/health.json')({
server: {
handlers: {
GET: async () => Response.json(
{ ok: true },
{ headers: { 'Cache-Control': 'no-store' } },
),
},
},
})安全与验证
把 params、search、headers 和 body 当作 unknown。写入前验证并执行认证、授权和速率限制；返回稳定错误对象，不泄露内部异常。对身份相关响应使用 no-store 或 private，不能使用 public 共享缓存。