tomevault-io EGG 控制器
控制器选择决策树
需要暴露什么接口/客户端协议？
1. HTTP 接口？例如 HTML/JSON/SSR/SSE，可以使用 HTTPController，参考 `references/http-controller.md`
2. 定时任务，可以使用 Schedule，参考 `references/schedule.md`
3. MCP 接口，可以使用 MCPController，参考 `references/mcp-controller.md`
需要做参数校验？
4. 使用 Ajv + TypeBox 做入参校验，参考 `references/ajv-validate.md`
需要给控制器加中间件（日志、鉴权、耗时统计等横切逻辑）？
5. 使用 Middleware，支持函数式写法和 AOP 写法，参考 `references/middleware.md`
控制器快速参考
HTTPController
- 装饰器：
@HTTPController、@HTTPMethod - 参数：
@HTTPParam、@HTTPQuery、@HTTPBody、@HTTPHeaders、@Cookies、@Request、@Context - 详细文档：
references/http-controller.md
MCPController
- 装饰器：
@MCPController、@MCPTool、@MCPPrompt、@MCPResource - 特点：集成 LLM、Zod 验证、登录态支持
- 详细文档：
references/mcp-controller.md
Schedule
- 装饰器：
@Schedule<T> - 模式：Worker/All
- 详细文档：
references/schedule.md
Ajv 参数校验
- 导入：
import { Ajv, Type, Static } from 'egg/ajv' - 方式：
@Inject() ajv: Ajv，调用ajv.validate(schema, data) - 特点：TypeBox 定义一次 Schema，同时获得校验和 TypeScript 类型
- 详细文档：
references/ajv-validate.md
Middleware 中间件
- 导入：
import { Middleware } from 'egg'（AOP 类从import { Advice } from 'egg/aop'） - 写法：函数式（Koa 中间件函数）和 AOP（@Advice 类），通过
@Middleware()应用 - 特点：支持类级别和方法级别，函数式和 AOP 不能在同一个
@Middleware()中混用 - 详细文档：
references/middleware.md
常见问题排查
| 现象 | 原因 | 解决方案 |
|---|---|---|
| MCP 装饰器 import 报错 | 从 'egg' 导入 |
MCP 装饰器从 '@eggjs/tegg' 导入，zod 从 '@eggjs/tegg/zod' 导入 |
| MCP Schema 报错 | 用了 z.object() 包装 |
直接用普通对象 { name: z.string() } |
| 定时任务不生效 | 放在 app/schedule 目录 |
放在模块目录中，避免和 egg 默认扫描冲突 |
| Ajv 校验 import 报错 | 从 typebox 或 ajv 导入 |
统一从 'egg/ajv' 导入 Type、Static、Ajv 等 |
| type 推导不完整 | 用 type 定义 |
用 interface Foo extends Static<typeof Schema> {} 代替 |
| Middleware 混用报错 | 函数和 Advice 类放同一个 @Middleware() |
分开写多个 @Middleware()，每个内部类型一致 |
| AOP Middleware 不生效 | Advice 类没加 @Advice() 装饰器 |
必须同时有 @Advice() 装饰器才能被识别为 AOP |
最佳实践
- 控制器精简：业务逻辑委托给 Service 层
- 参数验证：使用装饰器和类型定义
- 错误处理：根据协议转换错误和响应码
- RESTful 设计：遵循 HTTP 方法和资源命名
- 响应一致性：统一响应格式
参考资料
详细的控制器开发文档：
references/http-controller.md- HTTP 接口完整指南references/mcp-controller.md- MCP 接口开发references/schedule.md- 定时任务references/ajv-validate.md- Ajv 参数校验references/middleware.md- Middleware 中间件（函数式 + AOP）
核心概念（egg-core skill）：模块、依赖注入、对象生命周期
单元测试（egg-unittest skill）：HTTP 接口测试、Service 测试、Mock