# Egg Controller

> Egg Controller is an Agent Skill for development published in the eggjs/egg repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

- Skill name: `egg-controller`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/eggjs/egg/blob/HEAD/packages/skills/egg-controller/SKILL.md
- Repository: eggjs/egg (18,994 GitHub stars when collected)

## SKILL.md

# 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

---

Source: https://www.openparable.com/skill/development/egg-controller (OpenParable). Cite the canonical URL above.
