fastify-wrap 0.1.0

package/README.md

@@ -0,0 +1,980 @@
+# fastify-api
+
+Fastify 之上的一层薄封装。开发者只需写 controller / service / dao，路由注册、JWT 鉴权、JSON Schema 校验、统一异常处理、DB 连接池全部自动处理。
+
+**核心理念：极简。不包装 Happy Path，不做 `{ code, data, message }` 统一响应格式。Controller 返回什么就是什么，异常由框架统一捕获。**
+
+## 安装
+
+```bash
+npm install fastify-wrap
+```
+
+## 快速开始
+
+### 1. 入口文件
+
+```typescript
+// src/main.ts
+import { createApp } from 'fastify-wrap';
+import config from './config';
+
+const app = await createApp(config);
+await app.listen({ port: 3000 });
+```
+
+```typescript
+// src/config.ts
+import type { AppConfig } from 'fastify-wrap';
+import { createDbSecretResolver } from 'fastify-wrap';
+
+const config: AppConfig = {
+  db: {
+    host: '127.0.0.1',
+    port: 3306,
+    user: 'root',
+    password: 'root',
+    database: 'mydb',
+  },
+  auth: {
+    jwtSecret: 'your-secret',
+  },
+  signature: {
+    resolveSecret: createDbSecretResolver(),
+  },
+};
+
+export default config;
+```
+
+多环境部署详见[多环境配置](#多环境配置)。
+
+### 2. 写 Controller
+
+```typescript
+// src/modules/user/controller/UserController.ts
+import { Controller, Get, Post, Public, Login, Valid } from 'fastify-wrap';
+import type { FastifyRequest } from 'fastify';
+
+@Controller('/api/users')
+export class UserController {
+
+  @Post('/')
+  @Public()
+  @Valid({
+    body: {
+      type: 'object',
+      required: ['name'],
+      properties: { name: { type: 'string', minLength: 1 } },
+    },
+  })
+  async create(request: FastifyRequest) {
+    // request.body 已通过 JSON Schema 校验
+    return { id: '1', name: request.body.name };
+  }
+
+	@Get('/me')
+	@Login()
+	async profile(request: FastifyRequest) {
+	  // request.user 已注入（JWT 鉴权通过后）
+	  return request.user;
+	}
+
+	@Get('/admin')
+	@Login('admin')
+	async adminOnly() {
+	  return { secret: 42 };
+	}
+  }
+
+  // Controller 只需 request，无需 reply：
+  // - 返回值自动序列化为 JSON
+  // - JWT 签名用 signToken() 全局函数
+  // - 文件下载用 @Stream 装饰器
+```
+
+文件放到约定目录即自动发现，无需手动注册路由。
+
+### 3. RPC 风格 Controller
+
+加 `@Rpc(name)` 将类切换为 RPC 风格。无需 `@Controller`，无需在每个方法上加 `@Post`——框架自动扫描所有 public 方法，URL 由模块目录 + 控制器名 + 方法名自动推导。
+
+```typescript
+import { Rpc, Login, Body, signToken } from 'fastify-wrap';
+import type { User } from 'fastify-wrap';
+import { Type } from '@sinclair/typebox';
+
+@Rpc('users')                     // 控制器名，URL: /{module}/users/*
+@Login()                          // 类级别：所有方法默认需要 JWT（可被方法级 @Login/@Public 覆盖）
+export class UsersController {
+
+  // POST /{module}/users/create
+  @Body(Type.Object({ name: Type.String() }))
+  @Response('创建用户', Type.Object({ id: Type.String() }))
+  create(body: { name: string }, user: User): { id: string } {
+    return { id: 'u_001' };
+  }
+
+  // POST /{module}/users/login — public 端点，覆盖类级 @Login
+  @Public()
+  @Body(Type.Object({ code: Type.String() }))
+  @Response('登录', Type.Object({ token: Type.String() }))
+  async login(body: { code: string }): Promise<{ token: string }> {
+    const token = await signToken({ id: 'openid_xxx' });
+    return { token };
+  }
+
+  // POST /{module}/users/profile — 继承类级 @Login
+  @Response('获取用户信息', Type.Object({ id: Type.String() }))
+  profile(_body: Record<string, never>, user: User): { id: string } {
+    return { id: user.id };
+  }
+}
+```
+
+RPC 方法签名 `(body, user)`：第一个参数是已校验的请求体，第二个参数是 `request.user`。
+
+路由推导规则：
+
+| 来源 | 推导逻辑 |
+|------|----------|
+| module | 模块文件夹名，可通过 `route.config.ts` 覆盖 |
+| controller | `@Rpc(name)` 参数，默认为类名 |
+| method | 方法名，保持不变 |
+
+```typescript
+// src/modules/user/route.config.ts
+export const module = 'u';
+// → URL: /u/{controller}/{method}
+```
+
+**`urlPrefix` 是完整的路径前缀段，支持多级路径。** 可以包含 `/` 构造嵌套路由：
+
+```typescript
+// src/modules/user-rpc/route.config.ts
+export const urlPrefix = 'api/urpc';
+// → URL: /api/urpc/{controller}/{method}
+```
+
+不配置时 URL 前缀默认使用模块目录名。仅在 `@Rpc` 控制器中生效，`@Controller` 不受影响。
+
+**模块级 token 隔离**：`route.config.ts` 可配置 `module`，校验 token 的 `user.type`，防止跨模块 token 滥用：
+
+```typescript
+// src/modules/admin/route.config.ts
+export const urlPrefix = 'api/admin';  // URL 路径（可选，默认使用模块目录名）
+export const module = 'admin';          // 模块归属，所有 @Rpc 路由要求 user.type === 'admin'
+```
+
+`@Login()` 的参数与模块配置的 `module` 是同一概念——两者都声明"此路由需要什么系统的 token"，区别仅在于作用范围。优先级：**方法级 > 类级 > 模块级**：
+
+| 配置 | 校验 | 作用范围 |
+|------|------|----------|
+| `@Login('admin')`（方法上） | HMAC + JWT + `user.type === 'admin'` | 单个方法 |
+| `@Login('admin')`（类上） | 同上 | 整个 Controller，可被方法级覆盖 |
+| 模块 `module:'admin'` | 同上 | 整个模块，可被类/方法级覆盖 |
+| `@Login()`（无参数） | HMAC + JWT（不校验 type） | 方法/类 |
+| `@Public()` | 跳过所有 | 单个方法 |
+
+| 限制 | 说明 |
+|------|------|
+| HTTP 方法 | 全部使用 `@Post`，不可更改 |
+| 参数 | 只用 `@Body`，不支持 `@Query`/`@Params` |
+| URL | 不支持路径参数 `:id` |
+
+### 4. contextPath
+
+部署在反向代理子路径下时，配置 `contextPath`，Controller 代码无需变动：
+
+```typescript
+const app = await createApp({
+  db: { ... },
+  contextPath: '/myapp',
+});
+// @Controller('/api/users') → 响应地址：/myapp/api/users
+```
+
+搭配 nginx：
+
+```nginx
+location /myapp/ {
+    proxy_pass http://127.0.0.1:3000;
+}
+```
+
+## 配置项
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `db` | `object` | 是 | MySQL 连接（host / port / user / password / database / connectionLimit） |
+| `auth.jwtSecret` | `string` | 否 | JWT 密钥，不设则跳过鉴权 |
+| `signature` | `object` | 否 | HMAC 签名鉴权配置（resolveSecret / timestampWindowMs / nonceStore） |
+| `redis` | `object` | 否 | Redis 连接（host / port / password / db），配置后签名 nonce 自动切换 Redis 存储 |
+| `contextPath` | `string` | 否 | 路径前缀，如 `/myapp`，Controller 代码无需变动 |
+| `swagger` | `object` | 否 | Swagger / OpenAPI 文档配置（title / description / version / uiPrefix） |
+| `migrate` | `boolean` | 否 | 启动时执行 `src/migrations/*.sql`，默认 false |
+
+## 多环境配置
+
+源码保留 3 份环境配置文件作为参考，构建时只复制目标那份为 `config.ts` 参与编译。
+
+### 目录结构
+
+```
+src/
+├── main.ts
+├── config.ts                    ← 构建时由脚本写入（.gitignore）
+└── config/
+    ├── development.ts            ← 源码参考：本地开发
+    ├── test.ts                   ← 源码参考：测试环境
+    └── production.ts             ← 源码参考：生产环境
+```
+
+### 构建脚本
+
+```json
+{
+  "scripts": {
+    "build:dev":  "copy src\\config\\development.ts src\\config.ts >nul 2>&1 & npx tsc",
+    "build:test": "copy src\\config\\test.ts src\\config.ts >nul 2>&1 & npx tsc",
+    "build:prod": "copy src\\config\\production.ts src\\config.ts >nul 2>&1 & npx tsc"
+  }
+}
+```
+
+### 配置文件写法
+
+```typescript
+// src/config/production.ts
+import type { AppConfig } from 'fastify-wrap';
+
+const config: AppConfig = {
+  db: {
+    host: process.env.DB_HOST!,        // 敏感信息从环境变量注入
+    port: Number(process.env.DB_PORT),
+    user: process.env.DB_USER!,
+    password: process.env.DB_PASSWORD!,
+    database: process.env.DB_NAME!,
+    connectionLimit: 20,               // 生产环境提高连接数
+  },
+  auth: {
+    jwtSecret: process.env.JWT_SECRET!,
+  },
+  swagger: false,                      // 生产环境关闭文档
+  migrate: false,                      // 生产环境不在应用进程内执行迁移
+};
+
+export default config;
+```
+
+### 入口文件
+
+```typescript
+// src/main.ts
+import { createApp } from 'fastify-wrap';
+import config from './config';
+
+const app = await createApp(config);
+await app.listen({ port: 3000 });
+```
+
+### Docker 部署
+
+```dockerfile
+FROM node:24-alpine
+WORKDIR /app
+COPY . .
+RUN npm install && npm run build:prod
+CMD ["node", "dist/main.js"]
+```
+
+敏感信息通过环境变量注入，不写在配置文件里：
+
+```bash
+# 测试环境（生产用 build:prod，方法同上）
+docker run -d \
+  -e DB_HOST=192.168.1.10 \
+  -e DB_PORT=3306 \
+  -e DB_USER=app \
+  -e DB_PASSWORD=test123 \
+  -e DB_NAME=mydb_test \
+  -e JWT_SECRET=test-secret \
+  my-app:latest
+```
+
+## 项目结构
+
+```
+src/
+├── main.ts
+└── modules/
+    └── user/
+        ├── controller/UserController.ts   ← @Controller/@Get/@Post 声明路由
+        ├── service/UserService.ts         ← 纯业务流程编排
+        ├── dao/
+        │   ├── UserDao.ts                 ← db.query/db.queryOne/db.execute
+        │   └── UserDao.sql.ts             ← SQL 常量（禁止内联 SQL）
+        ├── dto/
+        │   ├── CreateUserRequest.ts
+        │   └── UserResponse.ts
+        ├── entity/UserEntity.ts
+        └── enums/UserStatus.ts
+```
+
+## 装饰器
+
+| 装饰器 | 作用 |
+|--------|------|
+| `@Controller('/prefix')` | 声明路由前缀，类必须 `export` |
+| `@Get('/path')` | GET 路由 |
+| `@Post('/path')` | POST 路由 |
+| `@Put('/path')` | PUT 路由 |
+| `@Delete('/path')` | DELETE 路由 |
+| `@Login()` | 需要 JWT + 签名验证。支持类级别（作用于所有方法）和方法级别（覆盖类级设置） |
+| `@Login('admin')` | 需要 JWT + 校验 `user.type === 'admin'` + 签名验证。支持类级别和方法级别 |
+| `@Public()` | 跳过签名验证（公开接口） |
+| `@Valid(schema)` | 绑定 Fastify JSON Schema 校验 |
+| `@Body(def)` | 声明式请求体校验 |
+| `@Query(def)` | 声明式查询参数校验 |
+| `@Params(def)` | 声明式路径参数校验 |
+| `@Response(description, def, statusCode?)` | 声明响应 Schema，用于 OpenAPI 文档生成，默认 200 |
+| `@Rpc(name?)` | RPC 风格控制器。无需 `@Controller`，方法自动扫描，签名 `(body, user)`。`name` 覆盖控制器名，默认类名。 |
+| `@Stream(description?)` | 流式下载端点，方法返回 `StreamResponse { name, content }`。`description` 注入 OpenAPI 响应描述。 |
+| `@File(description?)` | 文件下载端点，方法返回 `FileResponse { name, path }`。`description` 注入 OpenAPI 响应描述。 |
+| `@Multipart()` | 标记 multipart/form-data 文件上传端点。替代 `@Body`（输入层），仍需 `@Response`（输出层）。 |
+
+### 声明式校验
+
+比手写 JSON Schema 更简洁的类型工具：
+
+```typescript
+import {
+  Body, Query, Params,
+  String, Number, Boolean, Email, Required, ArrayOf, Enum, Min, Max,
+} from 'fastify-wrap';
+
+@Controller('/api/users')
+class UserController {
+
+  @Post('/')
+  @Body({
+    name: Required(String),
+    email: Required(Email),
+    age: Number,
+    tags: ArrayOf(String),
+    status: Enum(['active', 'inactive']),
+  })
+  create(request: FastifyRequest) {
+    // request.body 已校验
+  }
+
+  @Get('/')
+  @Query({ page: Number, keyword: String })
+  list(request: FastifyRequest) { ... }
+
+  @Get('/:id')
+  @Params({ id: Required(String) })
+  show(request: FastifyRequest) { ... }
+}
+```
+
+`@Body`/`@Query`/`@Params` 自动生成标准 JSON Schema，与 `@Valid` 等价但可读性更高。
+
+## Swagger / OpenAPI
+
+配置 `swagger` 即可自动生成 OpenAPI 文档，路由、参数、Schema 全部自动提取：
+
+```typescript
+const app = await createApp({
+  db: { ... },
+  swagger: {
+    title: 'My API',
+    description: 'API 文档',
+    version: '1.0.0',       // 可选，默认读取 package.json version
+    uiPrefix: '/docs',       // 可选，默认 /docs
+  },
+});
+```
+
+启动后访问 `/docs` 即可浏览 Swagger UI，`/docs/json` 获取 OpenAPI JSON。
+
+配置 `contextPath` 时自动联动，例如 `contextPath: '/myapp'` → Swagger UI 在 `/myapp/docs`。
+
+依赖自动补充 `@fastify/swagger` + `@fastify/swagger-ui`。
+
+## 统一响应
+
+**Happy path**：Controller `return data`，原样输出 JSON，不做包装。
+
+```json
+{ "id": "1", "name": "张三" }
+```
+
+**Error path**：自动捕获异常，统一格式：
+
+```
+HTTP 401 ← JWT 鉴权失败 / HMAC 签名失败
+HTTP 403 ← 角色权限不足
+HTTP 404 ← 路由不存在
+HTTP 422 ← BusinessException、NotFoundException、Schema 校验失败
+HTTP 500 ← ServiceException、未预期异常（message 通用化，不暴露堆栈）
+```
+
+业务/校验异常：
+```json
+{ "error": "手机号已存在" }
+```
+
+鉴权异常：
+```json
+{ "code": "login", "error": "Authorization token is invalid" }
+{ "code": "error", "error": "签名验证失败" }
+{ "code": "retry", "error": "凭证无效或已过期" }
+```
+
+## 异常
+
+```typescript
+import { BusinessException, NotFoundException, ServiceException } from 'fastify-wrap';
+
+throw new BusinessException('库存不足');      // → 422  { error: '库存不足' }
+throw new NotFoundException('用户不存在');     // → 422  { error: '用户不存在' }
+throw new ServiceException('推送失败');        // → 500  { error: '服务器内部错误' }
+```
+
+## API 签名鉴权
+
+所有接口默认需要 HMAC 签名验证。`@Public()` 标记的接口跳过签名，`@Login()` 标记的接口在签名基础上额外要求 JWT 登录。
+
+签名验证按 `module_name` 隔离——admin 的 clientId 无法调用其他模块的接口。
+
+### 鉴权模型
+
+```
+1. 线下派发 clientId + secretKey
+2. 客户端每次请求计算 HMAC-SHA256 签名
+3. 服务端验证时间戳、nonce、签名，按 module_name 过滤
+```
+
+### 客户端签名算法
+
+```
+stringToSign = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + BODY
+signature = base64(HMAC-SHA256(secretKey, stringToSign))
+```
+
+请求头：
+
+| Header | 说明 |
+|--------|------|
+| `X-App-Key` | 客户端 ID |
+| `X-Timestamp` | 毫秒时间戳 |
+| `X-Nonce` | 随机 UUID |
+| `X-Signature` | 签名结果 |
+
+### 服务端配置
+
+框架内置两种 `SecretResolver` 驱动：
+
+```typescript
+import { createDbSecretResolver, createRedisSecretResolver } from 'fastify-wrap';
+
+// DB 驱动 — 从 MySQL 的 api_keys 表查签名密钥
+createDbSecretResolver();
+
+// Redis 驱动 — 从 Redis 查 clientId，值存 JSON
+// Redis key = `${keyPrefix}${moduleName}:${clientId}`（不同模块隔离）
+createRedisSecretResolver({
+  keyPrefix: 'client:secret:',  // 默认 'client:secret:'
+});
+```
+
+配置示例：
+
+```typescript
+const app = await createApp({
+  db: { ... },
+  signature: {
+    resolveSecret: createDbSecretResolver(),
+    timestampWindowMs: 5 * 60 * 1000,  // 可选，默认 5 分钟
+  },
+});
+```
+
+也可自定义 `resolveSecret` 函数对接任意存储。
+
+### 路由使用
+
+默认所有接口需签名，`request.user.id` 为 clientId：
+
+```typescript
+@Controller('/api/app')
+export class AppController {
+
+  @Get('/data')
+  async data(request: FastifyRequest) {
+    return { clientId: request.user.id };
+  }
+
+  @Get('/profile')
+  @Login()
+  async profile(request: FastifyRequest) {
+    // 签名通过 + JWT 登录通过 → request.user 为 JWT 用户
+    return request.user;
+  }
+}
+```
+
+签名失败统一返回 `401 { code: 'error' | 'retry', error: string }`：
+
+- `code: 'error'` — 不可重试（签名不匹配、缺少参数、timestamp/nonce 异常）
+- `code: 'retry'` — 凭证无效或过期，客户端刷新凭证后重试
+
+服务端日志会详细记录失败原因和客户端数据。支持 nonce 防重放（内存或 Redis，自动切换）、timestamp 时间窗口校验、constant-time 签名比对。
+
+### 文件上传
+
+上传时签名逻辑不变：将 JSON 元数据签名后以 `_sign_body` 字段嵌入 `multipart/form-data`，文件以 `file` 字段附带：
+
+```typescript
+@Controller('/api/app')
+class AppController {
+
+  @Post('/upload')
+  async upload(request: FastifyRequest) {
+    const body = request.body as Record<string, unknown>;
+    // body.file → { type: 'file', fieldname, filename, mimetype, file, _buf }
+    // body._sign_body → { type: 'field', value: '{"fileName":"a.png",...}' }
+  }
+}
+```
+
+### 文件下载
+
+```typescript
+import { Controller, Get, Stream } from 'fastify-wrap';
+import type { StreamResponse } from 'fastify-wrap';
+
+@Controller('/api/report')
+class ReportController {
+
+  @Get('/export')
+  @Stream('导出CSV报表')
+  async exportCSV(): Promise<StreamResponse> {
+    const csv = ['name,phone', '张三,138xxxx'].join('\n');
+    return { name: 'report.csv', content: csv };
+  }
+}
+```
+
+Controller 只需返回 `{ name, content }`，框架自动设置 `Content-Disposition` 并流式返回。无需 `reply` 参数。
+
+`content` 支持 `string` 和 `Buffer`，适用 CSV / Excel / 图片等任意二进制数据。
+
+## JWT 工具
+
+### signToken — 全局 JWT 签名
+
+```typescript
+import { signToken } from 'fastify-wrap';
+
+const token = await signToken({ id: 1, role: 'admin', type: 'admin' });
+```
+
+全局可用，无需传递 `reply` 对象。在 `createApp()` 初始化 JWT 插件后自动生效。
+
+## DB 工具
+
+```typescript
+import { db } from 'fastify-wrap';
+
+// 查多行
+const users = await db.query<UserRow>('SELECT * FROM users WHERE status = ?', [0]);
+
+// 查单行
+const user = await db.queryOne<UserRow>('SELECT * FROM users WHERE id = ?', [id]);
+
+// 增删改
+await db.execute('UPDATE users SET name = ? WHERE id = ?', ['李四', id]);
+```
+
+无需手动 `getConnection` / `release`，自动管理连接池。
+
+### 事务
+
+```typescript
+import { db, Transaction } from 'fastify-wrap';
+
+await db.transaction(async (tx: Transaction) => {
+  await tx.execute('UPDATE account SET balance = balance - 100 WHERE id = ?', [1]);
+  await tx.execute('UPDATE account SET balance = balance + 100 WHERE id = ?', [2]);
+});
+// 成功自动 commit，异常自动 rollback + release
+```
+
+事务内使用 `tx.query` / `tx.queryOne` / `tx.execute`，接口与 `db` 一致。
+
+## Redis 工具
+
+```typescript
+import { redis } from 'fastify-wrap';
+
+await redis.set('key', 'value', 60);            // 带 TTL（秒）
+const val = await redis.get('key');              // → 'value' | null
+await redis.del('key');
+const exists = await redis.exists('key');        // → boolean
+
+// 原子 SET NX EX（用于分布式锁/防重放）
+const ok = await redis.setnx('lock:order:123', '1', 30);
+```
+
+配置：
+
+```typescript
+createApp({
+  db: { ... },
+  redis: {
+    host: '127.0.0.1',
+    port: 6379,
+    password: 'optional',
+    db: 0,
+  },
+});
+```
+
+配置 Redis 后，签名验证的 nonce 防重放自动切换为 `RedisNonceStore`（跨实例安全）。不配 Redis 则用内存 `MemoryNonceStore`。
+
+也可显式传入自定义 NonceStore：
+
+```typescript
+import { SignatureStrategy, RedisNonceStore } from 'fastify-wrap';
+
+const strategy = new SignatureStrategy({
+  resolveSecret,
+  nonceStore: new RedisNonceStore(),
+});
+```
+
+## 分页
+
+```typescript
+import type { PageResult } from 'fastify-wrap';
+
+@Get('/')
+async list(): Promise<PageResult<UserResponse>> {
+  return {
+    items: [...],
+    total: 100,
+    page: 1,
+    pageSize: 20,
+  };
+}
+```
+
+## 枚举规范
+
+```typescript
+// DB number → 数值枚举
+export enum UserStatus {
+  NORMAL,   // 0
+  LOCKED,   // 1
+}
+
+// DB string → 字符串枚举
+export enum OrderType {
+  NORMAL = 'NORMAL',
+  RUSH = 'RUSH',
+}
+```
+
+所见即所得，无额外 code/description 字段。
+
+## 二次开发
+
+框架设计为可扩展，以下是在其之上做二次开发的常见模式。
+
+### 定制校验错误消息
+
+框架内置 `errorRules`，覆盖 24 个 JSON Schema 关键字的默认中文提示。可通过 `addRule` 覆盖：
+
+```typescript
+import { addRule } from 'fastify-wrap';
+
+// 全局生效，框架启动前调用一次即可
+addRule('required', (field) => `${field} 是必填的`);
+addRule('pattern',  (field) => `${field} 格式不对`);
+addRule('type',     (field) => `${field} 类型不匹配`);
+```
+
+不调用则使用内置默认（`password 必填`、`phone 格式错误`、`age 类型错误` 等）。未覆盖的关键字回退到 AJV 原始英文。
+
+完整的关键字列表见 `src/common/validation/errorRules.ts`。
+
+### 自定义 AJV 校验关键字
+
+标准 JSON Schema 关键字不够用时，通过 `addKeyword` 注册自己的规则：
+
+```typescript
+// src/main.ts — createApp 之前调用
+import Ajv from 'ajv';
+
+const ajv = new Ajv();
+ajv.addKeyword({
+  keyword: 'isPhone',
+  validate: (_schema, data) => /^1[0-9]{10}$/.test(data),
+  errors: true,
+  error: {
+    message: (cxt) => `${cxt.instancePath.replace(/^\//, '')} 手机号格式不正确`,
+  },
+});
+```
+
+然后在 Controller 中使用：
+
+```typescript
+// Typebox 风格
+const Request = Type.Object({
+  phone: Type.String({ isPhone: true }),
+});
+
+// SchemaProp 风格
+@Body({ phone: { type: 'string', isPhone: true } })
+```
+
+关键字注册时自带的 `error.message` 会自动被 `errorRules.formatError` 使用，无需额外配置。
+
+### 自定义 SchemaProp 辅助
+
+在 `schema.ts` 中新增类型辅助，在项目中任何 Controller 直接使用：
+
+```typescript
+// src/common/validation/schema.ts
+export const Phone: SchemaProp = { type: 'string', pattern: '^1[0-9]{10}$' };
+
+export const IdCard: SchemaProp = {
+  type: 'string',
+  pattern: '^[1-9]\\d{5}(18|19|20)\\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]$',
+};
+```
+
+```typescript
+// Controller
+@Body({
+  phone: Required(Phone),
+  idCard: Required(IdCard),
+})
+```
+
+### 自定义签名 SecretResolver
+
+对接任何存储系统：
+
+```typescript
+createApp({
+  signature: {
+    resolveSecret: async (clientId: string, moduleName: string) => {
+      const row = await db.queryOne(
+        'SELECT secret_key FROM api_keys WHERE client_id = ? AND module_name = ?',
+        [clientId, moduleName],
+      );
+      return row
+        ? { appSecret: row.secret_key as string }
+        : null;
+    },
+  },
+});
+```
+
+### 自定义 NonceStore
+
+签名防重放实现可替换：
+
+```typescript
+import { SignatureStrategy } from 'fastify-wrap';
+
+class MyNonceStore {
+  async exists(nonce: string): Promise<boolean> { /* ... */ }
+  async mark(nonce: string, ttlMs: number): Promise<void> { /* ... */ }
+  async clear(/* ... */): Promise<void> { /* ... */ }
+}
+
+const strategy = new SignatureStrategy({
+  resolveSecret,
+  nonceStore: new MyNonceStore(),
+});
+```
+
+### 自定义 LoginStrategy
+
+对接非 JWT 的登录鉴权（Session、OAuth、自定义 Token）：
+
+```typescript
+import type { AuthStrategy, User } from 'fastify-wrap';
+
+class SessionStrategy implements AuthStrategy {
+  async authenticate(request: FastifyRequest, _reply: FastifyReply): Promise<User> {
+    const sessionId = request.cookies.session;
+    const user = await db.queryOne('SELECT * FROM sessions WHERE id = ?', [sessionId]);
+    if (!user) throw new AuthException('会话已过期');
+    return { id: user.id, role: user.role, type: 'session' };
+  }
+}
+```
+
+### 自定义 Controller 元数据扫描
+
+框架通过 `Reflect.defineMetadata` / `getMetadata` 管理路由元数据。装饰器和扫描逻辑在 `src/common/scanner/` 中，侵入式修改可参考：
+
+- `decorators.ts` — 新增装饰器（如 `@RateLimit`、`@Cache`）
+- `index.ts` — 扫描和路由注册（`scanControllers`）
+
+框架内置的 `@Response`、`@Stream` 均按此模式实现，是添加新装饰器的范本。
+
+新增装饰器示例：
+
+```typescript
+const RATE_LIMIT_META = Symbol('route:rateLimit');
+
+export function RateLimit(max: number, windowMs: number): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(RATE_LIMIT_META, { max, windowMs }, target, propertyKey);
+  };
+}
+```
+
+```typescript
+// scanner/index.ts 中读取
+const rateLimitMeta = Reflect.getMetadata(RATE_LIMIT_META, exported, route.handlerName);
+if (rateLimitMeta) {
+  routeDef.preHandler = [/* rate limiter hook */];
+}
+```
+
+## 自测客户端
+
+框架内置 Node.js 端 HMAC 签名客户端，无需浏览器或额外依赖，可直接用于集成测试：
+
+```typescript
+import { TestClient, ApiError, IOException } from 'fastify-wrap/client';
+
+const client = TestClient.withCredential(
+  'http://127.0.0.1:3001',
+  'app-demo-001',
+  'sk-your-secret',
+);
+
+// JSON 请求 — 成功返回 body，失败抛 ApiError
+const profile = await client.get<{ appKey: string }>('/api/app/profile');
+const echo = await client.post<{ appKey: string }>('/api/app/echo', { msg: 'hello' });
+
+// 文件上传
+const uploadRes = await client.upload<{ file: { name: string } }>(
+  '/api/app/upload',
+  { fileName: 'test.png', type: 'image/png', size: 11 },
+  { data: Buffer.from('...'), filename: 'test.png', mimetype: 'image/png' },
+);
+
+// 文件下载
+const blobRes = await client.blob('/api/app/download');
+const text: string = await blobRes.body.text();
+// blobRes.filename — 从 Content-Disposition 解析
+
+// POST 下载（带请求体的文件下载）
+const blobRes2 = await client.postBlob('/api/app/export', { format: 'csv' });
+
+// 错误处理
+try {
+  await client.get('/api/secret');
+} catch (e) {
+  if (e instanceof ApiError) {
+    console.log(e.statusCode, e.code, e.message);
+    // statusCode: 422, code: undefined, message: "..."
+  }
+  if (e instanceof IOException) {
+    console.log('Network error');
+  }
+}
+```
+
+复杂配置模式：
+
+```typescript
+const client = new TestClient({
+  baseUrl: 'http://127.0.0.1:3001',
+  getCredential: () => ({ appKey: 'k', appSecret: 's' }),
+  refreshCredential: async (appKey) => {
+    // 401 code=retry 时自动调用，传入当前 appKey
+    return { appKey: 'k2', appSecret: 's2' };
+  },
+  getToken: () => process.env.JWT_TOKEN ?? null,       // JWT Bearer token
+  onLoginRequired: () => { /* 401 code=login 时跳转登录 */ },
+  skipAuthPaths: ['/api/auth/login'],                   // 跳过签名的路径
+  toast: (msg) => console.error(msg),                   // error='toast' 时触发
+  alert: (msg) => window.alert(msg),                     // error='alert' 时触发
+  logger: true,                                          // 打印请求/响应日志
+});
+
+// 每个请求可单独控制错误处理
+await client.get('/api/resource');                          // 默认 toast
+await client.get('/api/resource', 'alert');                  // alert 弹窗
+await client.get('/api/resource', (msg) => console.log(msg));// 自定义处理
+```
+
+## 数据库迁移
+
+配置 `migrate: true` 即可在启动时自动执行 `src/migrations/` 下的 `.sql` 文件：
+
+```typescript
+const app = await createApp({
+  db: { ... },
+  migrate: true,
+});
+```
+
+约定：
+
+- SQL 文件放在 `src/migrations/`，按文件名字母序执行
+- 框架自动创建 `migrations` 追踪表，已执行的不会重复跑
+- 无需手动登库执行 DDL
+
+```sql
+-- src/migrations/001_create_users.sql
+CREATE TABLE IF NOT EXISTS users (
+  id INT AUTO_INCREMENT PRIMARY KEY,
+  name VARCHAR(50) NOT NULL
+);
+```
+
+## 依赖
+
+- Fastify 5
+- @fastify/jwt（JWT 鉴权）
+- @fastify/multipart（文件上传）
+- @fastify/mysql + mysql2（MySQL 连接池）
+- @fastify/redis + ioredis（Redis，可选）
+- @fastify/swagger + @fastify/swagger-ui（API 文档，可选）
+- reflect-metadata（装饰器元数据）
+- fast-glob（Controller 自动扫描）
+
+TypeScript `experimentalDecorators` 和 `emitDecoratorMetadata` 必须启用。
+
+## 参考
+
+- [多环境配置设计](./docs/env-config-design.md)
+- [JWT 登录设计思路](./docs/jwt-login-design.md)
+- [HMAC 签名鉴权方案设计](./docs/signature-design.md)
+- [DB 事务设计](./docs/db-transaction-design.md)
+- [数据库迁移设计](./docs/migration-design.md)
+- [声明式校验设计](./docs/validation-design.md)
+- [Swagger / OpenAPI 自动文档设计](./docs/swagger-design.md)
+- [优雅关闭设计](./docs/shutdown-design.md)
+
+## 待实现
+
+| 特性 | 说明 |
+|------|------|
+| CORS | `@fastify/cors`，跨域支持 |
+| 安全头 | `@fastify/helmet`，CSP / HSTS / X-Frame-Options 等 |
+| 请求 ID / 链路追踪 | 为每个请求注入 trace-id，日志可串联 |
+| 限流 | 基于令牌桶或滑动窗口的速率限制 |
+| 缓存抽象 | 防穿透（空值缓存）、防击穿（单飞锁）、防雪崩（随机 TTL） |