SuperAPI AI 工具集

server-routes

通用与其它

查看项目

更新于 10-15 23:41

技能介绍

用途:Server Routes 是 TanStack Router 中与页面路由并列定义在 src/routes 目录下的服务端 API 端点,使用 createFileRoute 的 server 属性处理原始 HTTP 请求。当调用方需要明确的 HTTP 契约时使用它;若数据仅供 Start 应用内部使用,应优先使用 server function 并在 loader 中直接调用,因为 loader 在 SSR 和客户端导航时都会运行,fetch('/api/...') 不是可移植的 loader 写法。

主要能力:同一文件可同时定义服务端路由与 UI 路由;支持 GET、POST、PUT、DELETE 等 HTTP 方法处理器;处理器接收 request、params、context、pathname、next;支持动态路径参数(如 /users/$id)与 splat 通配参数(params._splat);可用 request.json()、request.text()、request.formData() 读取请求体;可用 Response.json 返回 JSON,并自定义状态码与响应头。

中间件:可在 server.middleware 中为所有处理器配置中间件,也可通过 createHandlers 为特定方法单独配置,二者可组合,路由级中间件先执行。

文件约定:遵循基于文件的路由约定,如 routes/users.ts 对应 /users,routes/users/$id.ts 对应 /users/$id,routes/api/file/$.ts 为 splat,routes/my-script[.]js.ts 转义点号。每个路由只能有一个处理器文件,routes/users.ts 与 routes/users/index.ts 会冲突。

限制与常见错误:必须为每个读写私有数据的处理器做认证与授权,router 的 beforeLoad 重定向不能保护 /api/...;读取请求体必须 await;TypeScript 类型不能替代响应 schema 校验,需在边界处校验输入并断言序列化输出。

共享数据:不要让 SSR loader 调用自身的 server route,应把业务逻辑放入 server-only 服务,再按需通过 server route 与 server function 两个边界暴露。