weifuwu 0.63.0 → 0.64.0

package/docs/saas.md

@@ -0,0 +1,246 @@
+# SaaS 地基模块（weifuwu）
+
+五个模块（限流 / 邮件 / 用户系统 / 消息系统 / 队列）+ AI 对话，以中间件形态随包提供，`app.use(...)` 一行接入。
+
+> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+
+四个内建模块组成一个"基本 SaaS 底座"：认证、异步任务、限流、邮件——零新增依赖
+（只依赖已自研的 redis / postgres 客户端与 node 标准库）。
+
+## rateLimit — 限流
+
+```ts
+import { rateLimit } from 'weifuwu'
+
+app.use(redis())                                        // 依赖 ctx.redis
+app.use(rateLimit({ windowMs: 60_000, max: 100 }))      // 全局限流（默认固定窗口）
+
+app.get('/api/search', async (req, ctx) => {
+  await ctx.limit('search', { max: 30, windowMs: 60_000 })  // 手动限流，超限抛 429
+})
+
+// 登录/注册防爆破：ctx.limit 默认按 IP 维度（每 IP 独立计数）
+app.post('/api/auth/register', async (req, ctx) => {
+  await ctx.limit('register', { max: 5, windowMs: 60_000 }) // 每 IP 每分钟 5 次
+})
+
+// 系统级总量限制：scope: 'global' 全局共享维度
+await ctx.limit('total-jobs', { max: 1000, windowMs: 60_000, scope: 'global' })
+
+// 登录防爆破（配合 userSystem）：组合键 ip:email（key 接收标准 Request，取头拿 IP）
+app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}:${req.headers.get('x-user-email')}`, max: 5, windowMs: 15 * 60_000 }))
+```
+
+| 选项 | 默认 | 说明 |
+|------|------|------|
+| `windowMs` | `60000` | 时间窗口 |
+| `max` | `100` | 窗口内最大请求 |
+| `key` | X-Forwarded-For | 限流键（生产环境配置反向代理注入） |
+| `algorithm` | `fixed` | `fixed`（INCR+EXPIRE，原子）\| `sliding`（ZSET，仅 redis） |
+| `store` | `redis` | `redis`（多实例一致）\| `memory`（仅单实例/开发） |
+
+- 响应自动带 `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` / `Retry-After`
+- 多实例共享计数：计数在 redis，水平扩展天然一致
+
+## email — 邮件发送
+
+```ts
+import { email } from 'weifuwu'
+
+app.use(email({ from: 'no-reply@your.app', adapter: 'resend', resend: { apiKey: process.env.RESEND_API_KEY } }))
+// 或 adapter: 'smtp' + smtp: { host, port, user, pass }（自研 SMTP 客户端，零依赖）
+
+app.post('/api/notify', async (req, ctx) => {
+  await ctx.email.send({ to: 'user@x.com', subject: '通知', html: '<h1>hi</h1>' })
+})
+```
+
+- 适配器：`resend`（默认，一个 POST）/ `smtp`（自研 node:net + node:tls：EHLO/STARTTLS/AUTH PLAIN/DATA/dot-stuffing，非 ASCII subject 自动 RFC2047 编码）/ 自定义函数
+- 裁剪：附件、退信/送达率（服务商职责）、批量营销不支持
+
+## userSystem — 用户系统
+
+```ts
+import { userSystem } from 'weifuwu'
+
+const db = postgres()
+await db.migrate()
+const users = userSystem({ sql: db.sql, secret: process.env.AUTH_SECRET })
+await users.migrate()          // 幂等建表（users + sessions）
+app.use(db)
+app.use(users)                 // 注入 ctx.user / ctx.auth
+users.routes(app)              // POST /api/auth/register|login|logout|refresh + GET /api/auth/me
+
+app.get('/me', (req, ctx) => ok(ctx.user))        // 已注入
+app.post('/secure', (req, ctx) => { ctx.auth.requireAuth(); ... })
+```
+
+- **安全基线**：scrypt 密码哈希（per-user salt + timing-safe，异步不阻塞）；access token = HMAC-SHA256 JWT（与 `weifuwu/client` 的 `auth()` 天然配对）；refresh token = 不透明随机串，DB 只存哈希，logout/轮换即撤销
+- **防枚举**：登录失败统一 401（不泄露邮箱是否存在）
+- **`ctx.auth` 方法面**：`register` / `login` / `logout` / `requireAuth` / `setPassword(userId, newPwd)` / `createToken(type, payload, { ttlSeconds })`（邮箱验证/密码重置自接）
+- **多租户感知**：`issueSession` 的 token payload 携带 `tenantId`（来自 `user.tenant`）——中间件自动注入 `ctx.tenantId`，并将会话字段（userId/tenantId/email/name/role）合并到 `ctx.auth`，多租户应用免写 token 解码/租户中间件（数据隔离 SQL 是应用职责）
+- **`routes` 支持 `exclude`**：`users.routes(app, { exclude: ['register'] })`——应用自定义注册流程（如注册时建租户）时跳过框架路由
+- **裁剪**：OAuth、邮箱验证邮件（给底层 API 自接）、多因素、RBAC 权限引擎（只留 `role` 字段）、租户隔离 SQL（框架只做感知，`WHERE tenant_id` 属应用层）
+
+## messager — 消息系统
+
+```ts
+import { messager } from 'weifuwu'
+
+const db = postgres()
+await db.migrate()
+const msg = messager({ sql: db.sql, redis: rds })   // redis 可选：跨进程广播
+await msg.migrate()            // 幂等建表（conversations + members + messages）
+app.use(db)
+app.use(msg)                   // 注入 ctx.msg
+msg.routes(app)                // /api/messages/*（会话/历史/发消息/已读）
+app.ws('/ws', msg.handler())        // 标准 WS 协议内置
+
+// 业务代码：持久化 + 鉴权 + 广播 + 未读 + 历史，一次调用
+const conv = await ctx.msg.createConversation(ctx.user.id, { type: 'group', memberIds: ['u2'] })
+await ctx.msg.sendMessage(conv.id, { senderType: 'user', senderId: ctx.user.id, content: '你好' })
+ctx.msg.broadcast(`conv:${conv.id}`, { type: 'order_chat', orderId: 'o1' })  // 任意实时事件
+ctx.msg.sendTo('u2', { type: 'mention' })       // 用户维度点对点
+```
+
+- **数据模型**：`_weifuwu_conversations` / `_weifuwu_conversation_members` / `_weifuwu_messages`（`sender_type + sender_id` 不 FK users——user/agent/system 消息天然可存）；direct 会话同对用户唯一、历史游标分页、未读数（`last_read_at`）、编辑/删除软删
+- **实时协议内置**：`handler()` 提供 `connected / subscribe→subscribed / unsubscribe / ping→pong`——前端 `ctx.ws.send({ type: 'subscribe', room })` 直接可用，两端协议由框架定义
+- **跨进程**：`redis` 选项 → Redis pub/sub 广播（psubscribe 模式），多实例部署天然一致；无 redis 优雅降级单进程。
+  **环回去重**：`broadcast` = 本地直发 + Redis publish，本实例的 subscriber 会收到自己 publish 的消息——publish 携带实例唯一标识 `_pid`（`wf:{pid}:{seq}`），订阅回调跳过自己的环回，保证每个事件恰好投递一次（防 token 级事件重复/乱序）
+- **与 userSystem 咬合**：`sendTo(ctx.user.id)` 按身份路由、`createConversation(ctx.user.id)` 创建者即身份、成员校验自动对齐——身份是消息的路由，消息是身份的交互
+- **裁剪**：已读回执状态机（只做未读数）、附件存储、全文搜索、消息确认/重试（可靠投递用 queue）、移动端推送
+
+## queue — 可靠任务队列
+
+```ts
+import { queue } from 'weifuwu'
+
+const q = queue()              // 默认 REDIS_URL
+app.use(q)                     // 注入 ctx.queue
+
+app.post('/api/generate', async (req, ctx) => {
+  await ctx.queue.add('llm.batch', { prompt: '...' }, { attempts: 3 })
+  return new Response(null, { status: 202 })  // 立即 202，任务后台执行
+})
+
+// 消费者（独立进程或同进程均可，多开安全）
+const worker = q.worker('llm.batch', async (job) => {
+  await runLLM(job.data)       // 失败自动重试 → 用尽进 DLQ（q:llm.batch:dead）
+}, { concurrency: 5, visibilityTimeout: 30_000 })
+await worker.start()
+await worker.stop()            // 优雅停止
+```
+
+- **语义**：at-least-once（handler 可能重复执行——幂等由业务保证）；Redis Streams 消费组，多 worker 实例不重复消费
+- **可靠性**：失败 → 延迟重试（间隔 = `visibilityTimeout`，ZSET 延迟队列）→ attempts 用尽 → DLQ；worker 崩溃 → pending 由其他实例 `XAUTOCLAIM` 接管
+- 裁剪：延迟调度（除重试外）、cron、优先级、指数退避、速率限制不支持
+
+## ai — LLM 对话（自研协议 + 零依赖客户端）
+
+```ts
+import { ai } from 'weifuwu'
+
+const a = ai()          // DEEPSEEK_API_KEY / BASE_URL / MODEL 自动读 env，默认 deepseek-v4-flash
+app.use(a)              // 注入 ctx.ai（worker/非请求场景也可直接 a.chat()）
+
+// 流式对话：路由一行返回 SSE（wf: 协议，详见 design/ai-contract.md）
+app.post('/api/chat', async (req, ctx) => {
+  const { messages } = await req.json()
+  return ctx.ai.stream({ messages }, {
+    signal: req.signal,                                    // 断开即取消 provider 请求
+    traceId: req.headers.get('x-trace-id') ?? undefined,   // 追踪关联（协议 §7）
+  })
+})
+
+// 非流式（worker/后台）：
+const res = await a.chat({ messages: [{ role: 'user', content: 'hi' }] })
+
+// agent 引擎：工具循环 + 人工审批（HITL）
+const agent = a.agent({
+  systemPrompt: '你是助手。查询天气时调用 query_weather 工具。',
+  tools: [{
+    name: 'query_weather',
+    description: '查询城市天气',
+    parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+    run: async (args, { emit }) => {
+      emit('wf:tool_progress', { toolCallId: 'x', step: 1, total: 2, message: '查询中…', status: 'running' })
+      return { city: args.city, temp: 25 }
+    },
+  }],
+  humanInTheLoop: true,   // 每个工具执行前等人工审批
+})
+
+app.post('/api/agent', async (req, ctx) => {
+  const { messages } = await req.json()
+  return agent.run(messages, { signal: req.signal, traceId: req.headers.get('x-trace-id') ?? undefined })
+})
+
+// HITL 审批响应（前端点"允许/拒绝" → POST 到这里）
+app.post('/api/approve', async (req, ctx) => {
+  ctx.ai.approve(await req.json())   // { id, decision, modifiedArgs?, note? }
+  return new Response(null, { status: 200 })
+})
+```
+
+前端解码（`weifuwu/client`）：
+
+```ts
+import { aiStream } from 'weifuwu/client'
+
+const handle = aiStream('/api/chat', { messages }, {
+  onToken: (text) => { /* 增量 append 到消息 */ },
+  onToolCall: (call) => { /* 渲染工具卡片 */ },
+  onDone: () => { /* 收尾 */ },
+  onError: (e) => { /* 按 e.code 降级 */ },
+  onEvent: (name, data) => { /* x:* 自定义事件透传 */ },
+})
+handle.abort()  // 用户停止/组件卸载/导航跳走
+```
+
+前端对话层（会话语义 + 标准界面，协议对页面透明）：
+
+```tsx
+// ctx.ui.useChat：会话语义（消息累积/工具内嵌/审批/重试），返回页面同一个 $
+const $ = ctx.ui.useChat({ url: '/api/chat', approveUrl: '/api/approve' })
+// $.messages / $.input / $.streaming / $.error / $.usage / $.step
+// $.send() / $.stop() / $.retry() / $.clear() / $.approve('approved', note?)
+
+// AiChat：标准对话界面（气泡 / 工具卡 / 审批卡 / 自动滚动 / 错误重试）
+return () => <AiChat chat={$} />
+
+// agent 模式消息内嵌：msg.toolCalls（ToolCallCard 直接消费）/ msg.approval（ApprovalCard）
+```
+
+> 分层：`ctx.ai`（后端协议）→ `aiStream`（传输解码）→ `useChat`（会话语义）→ `AiChat`（标准界面）。要完全自定义 UI 的应用用 useChat + 自有渲染；要 5 分钟出界面用 AiChat。
+
+- **协议**：`wf:` 命名空间（message_start/token/tool_call/tool_progress/usage/done/error + agent 扩展 step/approval_request），SSE 下行 + POST 上行，错误即值、未知事件透传、`x:*` 自定义事件（详见 [design/ai-contract.md](../design/ai-contract.md)）
+- **agent 引擎**：`a.agent({ systemPrompt, tools, humanInTheLoop })` 工具循环（LLM → tool_call → 执行 → 回喂 → 重复）；工具可 `emit` 进度/自定义事件、接收 `signal` 取消；HITL 审批（`ctx.ai.approve` 响应，拒绝≠终止、modified 改参、超时兜底）
+- **emitter 抽象**：`agent.stream(messages, { emit })`——`wf:*` 事件（step/token/tool_result/usage/done）可接任意通道（SSE/WS/回调），协议不焊死在传输层；`agent.runToResult(messages)` 返回结构化结果 `{ content, steps, usage }`（非流式/worker 场景）
+- **embedding**：`ctx.ai.embed(text)` / `embedMany(texts)` 向量化（默认 `DASHSCOPE_API_KEY` + `text-embedding-v4`，compatible-mode 端点）；未配置抛 `AiError('unsupported')`（惰性检查，不静默降级）——知识库/语义检索开箱即用
+- **零依赖**：自研 OpenAI 兼容客户端（fetch + SSE 解析），默认 DeepSeek，`baseUrl` 可换任意 OpenAI 兼容端点（Ollama/vLLM/Moonshot…）
+- **追踪**：前端自动生成 `X-Trace-Id` → 后端以之作为 `message_start.id` → 工具内请求继承同一 traceId，整个 agent run 一次搜完
+- **裁剪**：Anthropic 原生协议、审批持久化（连接断=会话亡）暂不支持；多 agent 编排不承诺（子 agent = 工具已支持）；embedding 仅文本（图片/多模态不做）
+
+## 组合示例：注册 → 验证邮件 → 欢迎任务 → 登录防爆破
+
+```ts
+app.use(redis())
+app.use(rateLimit({ key: (req) => `login:${req.headers.get('x-forwarded-for')}`, max: 5, windowMs: 60_000 }))  // 防爆破
+app.use(email({ from: 'no-reply@x.com', adapter: 'resend', resend: { apiKey } }))
+app.use(db)
+app.use(users)
+users.routes(app)
+
+// 注册：限流守卫 → 用户系统 → 验证邮件 → 欢迎任务入队
+app.post('/api/auth/register', async (req, ctx) => {
+  await ctx.limit(`register:${req.ip}`, { max: 10, windowMs: 60_000 })
+  const result = await ctx.auth.register(await req.json())
+  const token = ctx.auth.createToken('verify', { sub: result.user.id }, { ttlSeconds: 86400 })
+  await ctx.email.send({ to: result.user.email, subject: '验证邮箱', html: `...?token=${token}` })
+  await ctx.queue.add('welcome.flow', { userId: result.user.id })
+  return created(result)
+})
+
+const worker = q.worker('welcome.flow', async (job) => { /* 欢迎流程 */ })
+await worker.start()
+```

package/docs/server.md

@@ -0,0 +1,356 @@
+# 后端 API — HTTP 服务层（weifuwu）
+
+> 以下为完整 API 参考，按需查阅。新手建议先阅读 README 的「核心概念」和「快速开始」。
+
+> 本页为 weifuwu 官方文档拆分页 · [返回 README](../README.md)
+
+## Router
+
+Trie 路由，支持 URL 参数、通配符、中间件链、WebSocket、GraphQL。
+
+```ts
+import { Router } from 'weifuwu'
+
+const app = new Router()
+```
+
+### 路由方法
+
+每个路由方法接受 `path, ...middlewares[], handler`：
+
+```ts
+app.get('/users', handler)
+app.post('/users', handler)
+app.put('/users/:id', handler)
+app.patch('/users/:id', handler)     // PATCH
+app.delete('/users/:id', handler)    // DELETE
+app.head('/users', handler)          // HEAD
+app.options('/users', handler)       // OPTIONS
+app.all('/users', handler)           // 所有 HTTP 方法
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `path` | `string` | 路由路径，支持 `:param` 和 `*` 通配符 |
+| `...middlewares` | `Middleware[]` | 路由级中间件（可选） |
+| `handler` | `Handler` 或 `Router` | 处理器或子路由器 |
+
+### 路由级中间件
+
+```ts
+declare module 'weifuwu' { interface Context { auth: { userId: string } } }
+
+const requireAuth: Middleware = (req, ctx, next) => {
+  if (!req.headers.get('authorization')) return new Response('Unauthorized', { status: 401 })
+  ;(ctx as any).auth = { userId: '123' }
+  return next(req, ctx)
+}
+
+app.get('/users/:id', requireAuth, (req, ctx) => {
+  return Response.json({ id: ctx.params.id, auth: ctx.auth })
+})
+```
+
+### 参数与查询
+
+```ts
+app.get('/posts/:category/:slug', (req, ctx) => {
+  ctx.params.category  // URL 参数
+  ctx.params.slug      // URL 参数
+  ctx.query.page       // 查询参数 ?page=1
+  return Response.json(ctx.params)
+})
+```
+
+### 通配符
+
+```ts
+app.get('/files/*', (req, ctx) => {
+  ctx.params['*']  // 剩余路径 "a/b/c.txt"
+  return Response.json({ path: ctx.params['*'] })
+})
+```
+
+### 子路由挂载
+
+```ts
+const users = new Router()
+users.get('/', listUsers)
+users.get('/:id', getUser)
+
+app.mount('/api/users', users)
+// → GET /api/users, GET /api/users/:id
+```
+
+### 插件模式
+
+```ts
+app.plugin(app => {
+  app.get('/health', () => Response.json({ ok: true }))
+  app.use(cors())
+})
+```
+
+### 类型安全中间件工厂
+
+```ts
+import { createMiddleware } from 'weifuwu'
+declare module 'weifuwu' { interface Context { greeting: string } }
+
+const greet = createMiddleware({
+  injects: ['greeting'],           // 注入的 ctx 字段
+  depends: ['sql'],                // 前置依赖（可选）
+  setup: async (ctx) => ({
+    greeting: 'Hello ' + ctx.params.name
+  }),
+})
+
+app.use(greet)
+app.get('/hello/:name', (req, ctx) => Response.json({ msg: ctx.greeting }))
+```
+
+`createMiddleware` 自动生成 `__meta` 元数据用于运行时依赖检查。
+
+### 查看路由表
+
+```ts
+console.log(app.routes())
+// → [
+//   "GET      /users",
+//   "POST     /users",
+//   "WS       /chat",
+//   "MIDDLEWARE  [2 global]"
+// ]
+```
+
+### 路由方法速查
+
+| 方法 | 说明 |
+|------|------|
+| `app.get(path, ...mws, handler)` | GET |
+| `app.post(path, ...mws, handler)` | POST |
+| `app.put(path, ...mws, handler)` | PUT |
+| `app.patch(path, ...mws, handler)` | PATCH |
+| `app.delete(path, ...mws, handler)` | DELETE |
+| `app.head(path, ...mws, handler)` | HEAD |
+| `app.options(path, ...mws, handler)` | OPTIONS |
+| `app.all(path, ...mws, handler)` | 任意方法 |
+| `app.use(mw)` | 全局中间件 |
+| `app.ws(path, ...mws, handler)` | WebSocket |
+| `app.graphql(path?, handler)` | GraphQL |
+| `app.mount(path, subRouter)` | 挂载子路由 |
+| `app.plugin(fn)` | 插件扩展现有 Router |
+| `app.onError(handler)` | 全局错误处理 |
+| `app.wsHub(hub)` | 注入自定义 Hub（多进程 WebSocket） |
+| `app.onClose(closeable)` | 注册关闭回调 |
+| `app.routes()` | 打印路由表 |
+| `app.close()` | 关闭所有注册的 Closeable 资源 |
+
+---
+
+## serve — HTTP 服务器
+
+```ts
+import { serve, Router } from 'weifuwu'
+
+const app = new Router()
+const server = serve(app, { port: 3000 })
+
+// 等待就绪
+await server.ready
+console.log(server.port) // 实际端口
+
+// 停止
+await server.close()
+// 或
+await server.stop(2000)  // 超时毫秒
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `port` | `number` | `0`（随机） | 监听端口 |
+| `hostname` | `string` | `'0.0.0.0'` | 监听地址 |
+| `signal` | `AbortSignal` | — | 通过信号停止 |
+| `maxBodySize` | `number` | `10MB` | 请求体上限（0=无限） |
+| `timeout` | `number` | `120000` | Socket 超时（ms，2 分钟，适配 LLM 生成等长任务） |
+| `keepAliveTimeout` | `number` | `5000` | Keep-Alive 超时 |
+| `headersTimeout` | `number` | `6000` | 请求头超时 |
+| `shutdown` | `boolean` | `true` | 自动注册 SIGTERM/SIGINT |
+
+| 属性/方法 | 类型/签名 | 说明 |
+|-----------|----------|------|
+| `server.port` | `number` | 实际监听端口（未就绪时 0） |
+| `server.hostname` | `string` | 监听地址 |
+| `server.ready` | `Promise<void>` | 服务器就绪 |
+| `server.close(timeoutMs?)` | `() => Promise<void>` | 优雅关闭 |
+| `server.stop(timeoutMs?)` | `() => Promise<void>` | `close` 别名 |
+
+`sig-server` 自动注册 SIGTERM/SIGINT → `server.closeAllConnections()` → `router.close()` → `process.exit(0)`。
+
+---
+
+## cors — CORS 中间件
+
+```ts
+import { cors } from 'weifuwu'
+
+// 默认：允许所有来源
+app.use(cors())
+
+// 自定义
+app.use(cors({
+  origin: 'https://app.example.com',
+  methods: ['GET', 'POST'],
+  allowedHeaders: ['Content-Type', 'Authorization'],
+  credentials: true,
+  exposedHeaders: ['X-Total-Count'],
+  maxAge: 86400,
+}))
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `origin` | `string \| string[] \| (origin) => string` | `'*'` | `credentials: true` 时自动回显请求 origin |
+| `methods` | `string[]` | `GET,HEAD,PUT,PATCH,POST,DELETE` | 允许的方法 |
+| `allowedHeaders` | `string[]` | `Content-Type, Authorization` | 允许的请求头 |
+| `exposedHeaders` | `string[]` | — | 暴露的响应头 |
+| `credentials` | `boolean` | — | 是否允许凭据 |
+| `maxAge` | `number` | — | 预检缓存秒数 |
+
+---
+
+## serveStatic — 静态文件服务
+
+```ts
+import { serveStatic } from 'weifuwu'
+
+// 作为全局中间件（未匹配到文件时走下一个中间件）
+app.use(serveStatic('./public'))
+
+// 或挂载到特定路径
+app.get('/assets/*', serveStatic('./assets', {
+  index: 'index.html',
+  maxAge: 31536000,
+  immutable: true,
+}))
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `index` | `string` | `'index.html'` | 目录索引文件名 |
+| `maxAge` | `number` | `0` | Cache-Control max-age（秒） |
+| `immutable` | `boolean` | — | 添加 `immutable` 指令（需 maxAge） |
+
+特性：
+- ETag/304 缓存协商（`if-none-match` + `if-modified-since`）
+- MIME 类型自动检测（支持 30+ 扩展名）
+- 目录遍历保护（`..` / symlink 逃逸 → 403）
+- 目录自动跳转到 index 文件
+
+---
+
+## HttpError — HTTP 错误
+
+```ts
+import { HttpError } from 'weifuwu'
+
+app.get('/secure', () => {
+  if (!condition) throw new HttpError('Forbidden', 403)
+  // serve() 自动捕获并返回对应状态码
+})
+```
+
+| API | 说明 |
+|-----|------|
+| `new HttpError(msg, status)` | 创建 HTTP 错误，name = 'HttpError' |
+
+> 请求体上限常量 `DEFAULT_MAX_BODY`（10MB）见上方 serve 选项表 `maxBodySize`。
+
+---
+
+## 响应辅助函数
+
+> 以下为完整 API 参考，按需查阅。五个 SaaS 地基模块（rateLimit / email / userSystem / messager / queue）见文末「SaaS 地基模块」章节。
+
+消除 `Response.json(...)` 重复模式：
+
+```ts
+import { ok, created, noContent, badRequest, unauthorized, forbidden, notFound, conflict, unprocessable, tooManyRequests, serverError, redirect } from 'weifuwu'
+
+app.get('/users/:id', async (req, ctx) => {
+  const user = await findUser(ctx.params.id)
+  if (!user) return notFound('用户不存在')
+  return ok(user)
+})
+
+app.post('/users', async (req, ctx) => {
+  const body = await parseBody(req)
+  const user = await createUser(body)
+  return created(user)
+})
+```
+
+| 函数 | 状态码 | Content-Type |
+|------|--------|-------------|
+| `ok(data, init?)` | 200 | `application/json` |
+| `created(data, init?)` | 201 | `application/json` |
+| `noContent(init?)` | 204 | — |
+| `badRequest(msg?)` | 400 | `application/json` |
+| `unauthorized(msg?)` | 401 | `application/json` |
+| `forbidden(msg?)` | 403 | `application/json` |
+| `notFound(msg?)` | 404 | `application/json` |
+| `conflict(msg?)` | 409 | `application/json` |
+| `unprocessable(msg?)` | 422 | `application/json` |
+| `tooManyRequests(msg?)` | 429 | `application/json` |
+| `serverError(msg?)` | 500 | `application/json` |
+| `redirect(url, status?)` | 302 (默认) | — |
+
+---
+
+## parseBody — 请求体解析
+
+```ts
+import { parseBody } from 'weifuwu'
+
+app.post('/users', async (req, ctx) => {
+  const body = await parseBody<{ name: string; email: string }>(req)
+  // JSON 解析失败自动 throw HttpError(400)
+  return ok(body)
+})
+```
+
+| 行为 | 说明 |
+|------|------|
+| JSON 格式正确 | 返回解析后的数据 |
+| JSON 格式错误 | `throw new HttpError('Invalid JSON body', 400)` |
+| GET/HEAD 请求 | 返回 `{}` |
+
+---
+
+## 后端类型
+
+```ts
+import type { Context, Handler, Middleware, ErrorHandler, User, Closeable } from 'weifuwu'
+import type { HttpError } from 'weifuwu'
+import type { ServeOptions, Server } from 'weifuwu'
+import type { Hub, WebSocketHandler } from 'weifuwu'
+import type { WebSocket } from 'weifuwu'
+import type { CORSOptions } from 'weifuwu'
+import type { ServeStaticOptions } from 'weifuwu'
+import type { PostgresOptions, PostgresClient, PostgresInjected } from 'weifuwu'
+import type { RedisOptions, RedisClient, RedisInjected } from 'weifuwu'
+import type { MessagerOptions, MessagerClient, MessagerInjected } from 'weifuwu'
+import type { GraphQLOptions, GraphQLHandler } from 'weifuwu'
+```
+
+| 类型 | 签名 | 说明 |
+|------|------|------|
+| `Context` | `interface` | `{ params, query, mountPath, user, loaderData?, env?, [key]: unknown }` |
+| `Handler<T>` | `(req: Request, ctx: T) => Response \| Promise<Response>` | 请求处理器 |
+| `Middleware<In, Out>` | `(req, ctx: In, next) => Response` | 中间件，含 `__meta` |
+| `ErrorHandler<T>` | `(error, req, ctx: T) => Response` | 错误处理器 |
+| `Closeable` | `interface` | `{ close(): Promise<void> }` |
+| `User` | `interface` | `{ id, role?, tenant?, [key]: unknown }` |
+| `HttpError` | `class` | `extends Error`，含 `status` 属性 |
+
+---