start-server-routes

用途

本技能用于在 TanStack Start 中定义原生 HTTP 端点（server routes）。这类端点与普通应用路由一起放在 src/routes/ 下，通过在 createFileRoute（从 @tanstack/react-router 导入）上设置 server 属性实现，并返回标准 Response 对象。技能目标版本为 @tanstack/react-start v1.168.58。

当端点需要从应用外部调用时（如 webhook、公开 REST 接口、跨域请求），应选择 server route，而非 server function。仅限自身应用内调用的类型安全 RPC 不属于本技能范围。

主要能力

处理器上下文：提供 { request, params, context, pathname, next }。
参数解析：支持从文件名解析动态参数（$id）与通配参数（$）。
中间件：可通过 server.middleware（作用于全部处理器）或 createHandlers（作用于单个处理器）配置。
双重身份：同一文件可同时作为 UI 路由（component）和 API 路由（server）。
模板：内置带参数与中间件的完整 REST 资源模板。

使用方式

基本 GET 示例：

// src/routes/api/hello.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/hello')({
  server: {
    handlers: {
      GET: async ({ request }) => new Response('Hello, World!'),
    },
  },
})

带动态参数与状态码的 JSON 示例：

// src/routes/api/users/$id.ts
export const Route = createFileRoute('/api/users/$id')({
  server: {
    handlers: {
      GET: async ({ params }) => {
        const user = await findUser(params.id)
        if (!user) return new Response('Not found', { status: 404 })
        return Response.json(user)
      },
    },
  },
})

目录结构示例：

src/routes/
├── api/
│   ├── hello.ts              # /api/hello
│   ├── users/$id.ts          # /api/users/$id（动态参数）
│   └── file/$.ts             # /api/file/$（通配参数）
└── webhooks/stripe.ts        # /webhooks/stripe（外部 POST）

关键规则

路由选择：可从应用外部调用的端点用 server route；内部类型安全 RPC 用 server function。
路径唯一：同一路由路径只能有一个处理器文件解析。routes/users.ts、routes/users/index.ts 和 routes/users.index.ts 都会解析到 /users，重复会报错。
必须 await 请求体方法：request.json()、.text()、.formData() 返回 Promise，不 await 得到的是 Promise 而非数据。
必须返回 Response：使用 Response.json(...) 返回 JSON，或用 new Response(body, { status, headers })。
可同时承载 UI 与 API：在 server 旁添加 component 即可。

适用场景

webhook 接收、公开 REST 接口、跨域端点等需要从应用外部访问的场景；以及需要在同一文件同时提供页面与接口的场景。

限制

不适用于仅限自身应用调用的类型安全 RPC（应使用 start-server-functions）、可复用中间件链（应使用 start-middleware）或 UI 路由渲染。技能建议实现前先通过 Context7 与 Exa 核对当前 API 并查看目标代码库，变更后运行 fuse-ai-pilot:sniper。

技能介绍

用途

主要能力

使用方式

关键规则

适用场景

限制