请求生命周期

本文档详细说明一个 HTTP 请求从进入到返回响应的完整生命周期。

概览

客户端请求
  ↓
Vite 开发服务器 / Nitro 生产服务器
  ↓
中间件链（按注册顺序执行）
  ├── i18n 中间件
  └── auth 中间件
  ↓
路由匹配
  ├── 文件路由匹配
  └── API 路由匹配
  ↓
路由处理器
  ├── 页面组件渲染（SSR/CSR）
  └── API 处理器执行
  ↓
响应返回客户端

阶段详解

1. 请求入口

所有请求首先经过 Vite 开发服务器（开发环境）或 Nitro 生产服务器（生产环境）。

在 TanStack Start 中，服务器入口由 src/start.ts 定义，Nitro 在此处注册所有中间件和路由。

2. 中间件链

中间件按注册顺序依次执行，每个中间件可以：

• 修改请求对象
• 短路返回响应（如重定向）
• 将数据注入请求上下文

i18n 中间件

国际化中间件是第一个执行的中间件，负责语言检测和路由处理：

请求路径: /docs/architecture
  ↓
检测 Accept-Language 头
  ↓
匹配支持的语言: en-US / zh-CN
  ↓
重定向到: /zh-CN/docs/architecture

auth 中间件

认证中间件在 i18n 之后执行，负责：

• 解析会话 Cookie
• 调用 Better Auth 验证会话
• 将用户信息注入请求上下文

3. 路由匹配

TanStack Start 的路由匹配基于文件系统：

页面路由

页面请求匹配到对应的路由文件后，TanStack Start 会：

1. 加载路由的 loader 数据（服务端数据获取）
2. 渲染根布局（__root.tsx）
3. 渲染当前页面的 React 组件
4. 将 HTML 流式返回客户端
5. 客户端 Hydration 后接管交互

API 路由

API 请求通过 $.ts 通配路由转发到对应的处理器：

• /api/auth/* → Better Auth 处理器
• /api/rpc/* → oRPC 路由处理器

4. API 处理流程

oRPC 请求处理

POST /api/rpc/user.create
  ↓
oRPC Router 匹配路由
  ↓
Zod Schema 校验请求参数
  ↓
Server Function 执行业务逻辑
  ↓
Drizzle ORM 查询数据库
  ↓
Zod Schema 校验响应数据
  ↓
返回 JSON 响应

Better Auth 请求处理

POST /api/auth/sign-up
  ↓
Better Auth 中间件处理
  ↓
验证请求参数
  ↓
创建用户记录
  ↓
发送验证邮件（可选）
  ↓
返回会话信息

5. 响应返回

处理完成后，响应按以下格式返回：

Server Functions

TanStack Start 的 Server Functions 是特殊的 RPC 调用：

• 从客户端直接调用服务端函数，无需手动定义 API 路由
• 函数参数和返回值自动经过序列化/反序列化
• 与 oRPC 集成后，获得完整的类型安全和校验能力

// 客户端代码
const result = await api.user.create({ name: "张三", email: "zhangsan@example.com" });

// TypeScript 类型自动推导，无需手动定义接口

错误处理

请求处理过程中的错误按以下方式处理：

1. Zod 校验错误——返回 400 状态码和字段级错误信息
2. 认证错误——返回 401 状态码，重定向到登录页
3. 未找到资源——返回 404 状态码或显示 404 页面
4. 服务器错误——返回 500 状态码，错误信息记录到日志

相关文档

• 架构概览 — 系统分层设计
• 项目结构 — 仓库布局说明
• API 文档 — oRPC 接口定义