# v3.0 重构：三阶段升级

这是 erest 的重大版本更新,包含架构重组、Schema 体系统一、发布物改造和工具链升级。

## 核心变更

### Stage 1 - Schema 统一 (Zod 唯一)
- 删除 ISchemaType 双轨体系,所有 schema 统一使用 Zod
- 参数校验改为 `bind()` 阶段预编译,热路径零分配
- `apiParamsCheck` 改为预编译校验器 `compileValidate`,性能提升 ~2x (4.49M ops/s vs 2.39M)
- 新增 `plugin/zod-meta.ts` 统一处理 Zod 内部结构读取
- 移除公开方法: `createSchema()`, `paramsChecker()`, `schemaChecker()`, `apiParamsCheck()` 等

### Stage 2 - 架构重组
- **框架适配器改为插件化**:
  - 核心包移除内置实现,改用独立子包提供
  - 新增 `@erest/express`, `@erest/koa`, `@erest/leizmweb`
  - `bind()` 成为唯一绑定入口,接收 `adapter` 实例
- **删除 deprecated 方法**:
  - `bindRouter()`, `bindRouterToApp()`, `bindKoaRouterToApp()` → 用 `bind({ adapter, ... })`
  - `checkerExpress`, `checkerKoa`, `checkerLeiWeb` → 内置于各 adapter
- **删除 privateInfo 反射洞口**:
  - 新增受控访问器: `getError()`, `getInternalGroups()`, `getMockHandler()`, `getDocsView()`, `getTestView()`, `getHooks()`

### Stage 3 - 可观测性 + AI 友好
- **生命周期 Hook** (不参与控制流的观察者):
  - `onRequest(ctx)` - 注入 traceId、开始计时
  - `onValidate(ctx, result)` - 记录校验耗时
  - `onError(ctx, err)` - 结构化错误日志
  - `onResponse(ctx)` - 结束计时、状态码
- **新增 AGENTS.md** - 架构导航与决策树,面向修改者(人与 AI)
- **erest-gen codegen** - 从 Zod schema 生成 handler 骨架

## 发布物改造

### ESM-only (BREAKING)
- **erest v3.0+ 仅发布 ESM 产物** (dist/lib),不再有 CJS
- `require('erest')` 的 CommonJS 工程需迁移为 `import` 或动态 `import()`
- TypeScript `module: nodenext` 下的默认导出现在可直接使用

### 工具链升级
- **Biome → Oxlint + Oxfmt**
  - 移除 `biome.json`,新增 `.oxlintrc.json` + `.oxfmtrc.json`
  - src/lib 启用 `typescript/no-explicit-any` 报错,src/test 关闭
  - 全仓 0 真实 any,0 eslint 违规
- **Supertest 替换为原生 fetch** (Node 18+)
  - 新增 `test-server.ts` 归一化 app 形态
  - 重写 `TestAgent` 支持完整的链式 API
  - 手动 cookie jar 替代 supertest agent
  - 删除 `cjs-compat.ts` + supertest 依赖

## 项目清理
- 删除历史遗留: `.travis.yml`, `.coveralls.yml`, `sonar-project.properties`, OSSAR workflow
- 从 git 移除 docs/ typedoc 产物 (59 文件),CI 自动构建部署
- 删除 package-lock.json (工程改用 pnpm)
- 精简 .gitignore

## Examples 改造
- Workspace 化: `examples/` 作为 pnpm 子包,依赖 `erest: workspace:*`
- 修复既有 bug: hooks/define handler 改为标准化 (ctx, next) 签名
- CI 添加 `pnpm --filter erest-example test`

## 测试与文档
- 删除 231 个 ISchemaType 内部结构 hack 测试
- 补充 cookie session 跨请求测试
- 新增 test-docs-plugins.ts 验证文档生成器
- 最终: 源码 626 测试 + examples 12 测试全绿
- docs CI 自动构建 typedoc 到 GitHub Pages

## 迁移
见 MIGRATION.md (v3.0 完整迁移指南)

## 关键指标
- 参数校验性能提升 ~2x (`compileValidate` ~4.49M ops/s)
- params.ts 代码行数从 855 行缩减为 244 行
- 包体积减小 (移除 ISchemaType 代码)
- 热路径零分配 ✓
- TS NodeNext 类型安全 ✓
- 三框架无缝复用 ✓

## Breaking Changes
- 仅发布 ESM 产物(CJS 工程需迁移)
- ISchemaType 及相关公开方法已删除
- `bind()` 接收 adapter 参数替代 framework 字符串
- privateInfo 反射改为受控访问器