| name | egg-controller |
| description | Use when creating API endpoints, implementing protocol handlers, exposing interfaces for specific clients, adding parameter validation, or applying middleware to controllers. Covers HTTP, MCP and Schedule controllers, Ajv/TypeBox parameter validation, and Middleware (function-style and AOP) for EGG framework applications. |
| allowed-tools | Read |
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
