字
字节笔记本
2026年5月3日
TanStack Start - Server Routes 服务端路由
API中转
¥120
服务端路由是 TanStack Start 的强大功能，允许你在应用中创建服务端端点，适用于处理原始 HTTP 请求、表单提交、用户认证和 API 端点。
简单示例
ts
// routes/hello.ts
export const Route = createFileRoute('/hello')({
server: {
handlers: {
GET: async ({ request }) => {
return new Response('Hello, World!')
},
},
},
})同文件双用途
服务端路由可以与应用路由在同一文件中定义：
tsx
// routes/hello.tsx
export const Route = createFileRoute('/hello')({
server: {
handlers: {
POST: async ({ request }) => {
const body = await request.json()
return new Response(JSON.stringify({ message: `Hello, ${body.name}!` }))
},
},
},
component: HelloComponent,
})文件路由约定
| 文件 | API 路由 |
|---|---|
routes/users.ts | /users |
routes/users/$id.ts | /users/:id |
routes/users/$id/posts.ts | /users/:id/posts |
routes/api/file/$.ts | /api/file/* |
中间件支持
为特定处理程序添加中间件
tsx
export const Route = createFileRoute('/hello')({
server: {
handlers: ({ createHandlers }) =>
createHandlers({
GET: {
middleware: [loggerMiddleware],
handler: async ({ request }) => {
return new Response('Hello, World!')
},
},
}),
},
})为所有处理程序添加中间件
tsx
export const Route = createFileRoute('/hello')({
server: {
middleware: [authMiddleware, loggerMiddleware],
handlers: {
GET: async ({ request }) => { return new Response('Hello!') },
POST: async ({ request }) => { return new Response('Created') },
},
},
})处理程序上下文
| 属性 | 类型 | 描述 |
|---|---|---|
request | Request | 传入的请求对象 |
params | 对象 | 路由的动态路径参数 |
context | 对象 | 请求上下文，用于在中间件间传递数据 |
动态路径参数
ts
// routes/users/$id.ts
export const Route = createFileRoute('/users/$id')({
server: {
handlers: {
GET: async ({ params }) => {
const { id } = params
return new Response(`User ID: ${id}`)
},
},
},
})处理请求体
| 方法 | 用途 |
|---|---|
request.json() | JSON 数据 |
request.text() | 纯文本 |
request.formData() | 表单数据 |
实际应用示例
RESTful API
ts
// routes/api/users/$id.ts
export const Route = createFileRoute('/api/users/$id')({
server: {
middleware: [authMiddleware],
handlers: {
GET: async ({ params }) => {
const user = await db.users.findById(params.id)
if (!user) return new Response('Not found', { status: 404 })
return Response.json(user)
},
PUT: async ({ params, request }) => {
const body = await request.json()
const user = await db.users.update(params.id, body)
return Response.json(user)
},
DELETE: async ({ params }) => {
await db.users.delete(params.id)
return new Response(null, { status: 204 })
},
},
},
})表单处理
ts
export const Route = createFileRoute('/contact')({
server: {
handlers: {
POST: async ({ request }) => {
const formData = await request.formData()
const name = formData.get('name')
const email = formData.get('email')
await sendEmail({ name, email })
return Response.json({ success: true })
},
},
},
component: ContactForm,
})API 速查
| API | 用途 |
|---|---|
server.handlers | 定义 HTTP 方法处理程序 |
server.middleware | 路由级中间件 |
createHandlers() | 创建带中间件的处理程序 |
params | 访问路径参数 |
context | 访问中间件上下文 |
request | 原始请求对象 |
分享: