# Egg Controller

> 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: `eggjs/egg-controller` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add eggjs/egg-controller`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eggjs/egg-controller/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: eggjs (https://skillmd.com/u/eggjs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/eggjs/egg-controller

---


# 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