@eggjs/skills 4.1.2-beta.5 → 4.1.2-beta.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-present Alibaba Group Holding Limited and other contributors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/egg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: egg
-description: 本技能用于处理 EGG 框架。它提供基于用户意图在核心概念和控制器之间做选择的决策指导。作为所有 EGG 相关问题的入口点使用。
+description: 本技能用于处理 EGG 框架。它提供基于用户意图在核心概念、控制器和单元测试之间做选择的决策指导。作为所有 EGG 相关问题的入口点使用。覆盖模块架构、依赖注入、后台任务、EventBus 事件总线、AOP 切面编程、HTTP/MCP/Schedule 控制器、Ajv 参数校验、单元测试等。
 allowed-tools: Read
 ---
 
@@ -10,8 +10,9 @@ allowed-tools: Read
 
 本技能帮助根据用户意图和任务类型确定使用哪个专用的 EGG 技能。EGG 文档组织为两个主要领域：
 
-1. **核心概念**（`egg-core` skill）：模块架构、依赖注入、对象生命周期
+1. **核心概念**（`egg-core` skill）：模块架构、依赖注入、对象生命周期、EventBus 事件总线、AOP 切面编程
 2. **控制器**（`egg-controller` skill）：用于 API 端点的各种协议特定控制器
+3. **单元测试**（`egg-unittest` skill）：HTTP 接口测试、Service/DI 对象测试、Mock 模拟、BackgroundTask 和 EventBus 测试
 
 ## 技能选择逻辑
 
@@ -26,6 +27,9 @@ allowed-tools: Read
 - 模块之间的访问控制（`AccessLevel`）
 - 模块配置（`module.yml`、`package.json`）
 - 使用限定符解决命名冲突
+- 请求返回后执行异步任务（BackgroundTaskHelper）
+- 事件驱动架构（EventBus、@Event）
+- AOP 切面编程（@Advice、@Pointcut、@Crosscut）
 
 **触发关键词：**
 
@@ -34,6 +38,9 @@ allowed-tools: Read
 - context、request context、@ContextProto
 - inject、injection、dependency injection、@Inject
 - prototype、lifecycle、实例化
+- background task、异步任务、后台任务、BackgroundTaskHelper
+- eventbus、event bus、事件总线、事件驱动、@Event、emit、发布订阅、解耦
+- aop、切面、aspect、advice、pointcut、crosscut、拦截器、横切关注点
 - access level、private、public、@ModuleQualifier
 - configuration、module config
 
@@ -44,6 +51,9 @@ allowed-tools: Read
 - "如何注入服务？"
 - "如何访问其他模块的对象？"
 - "EGG 中的 AccessLevel 是什么？"
+- "如何用 EventBus 解耦异步任务？"
+- "EventBus 和 BackgroundTaskHelper 有什么区别？"
+- "如何用 AOP 给所有 Service 加日志？"
 
 ### 使用 `egg-controller` skill 当用户询问：
 
@@ -54,6 +64,8 @@ allowed-tools: Read
 - 连接到外部系统或客户端
 - 处理传入的请求/响应
 - 控制器级别的装饰器和模式
+- 参数校验（Ajv + TypeBox）
+- 控制器中间件（Middleware，函数式或 AOP 写法）
 
 **触发关键词：**
 
@@ -62,12 +74,47 @@ allowed-tools: Read
 - MCP、LLM、AI、tool
 - schedule、timer、cron、scheduled、定时
 - SSE、streaming、server-sent events
+- validate、校验、参数校验、ajv、typebox、schema
+- middleware、中间件、拦截器、洋葱模型、@Middleware
 
 **示例查询：**
 
 - "如何创建 HTTP controller？"
 - "如何实现 MCP 接口？"
 - "怎么实现定时任务？"
+- "帮我给接口加上参数校验"
+- "如何给控制器加中间件？"
+- "怎么写一个鉴权中间件？"
+
+### 使用 `egg-unittest` skill 当用户询问：
+
+**用户询问关于：**
+
+- 编写单元测试或集成测试
+- 使用 @eggjs/mock 进行测试
+- 测试 HTTP 接口（app.httpRequest）
+- 测试 Service/DI 对象
+- Mock 数据或依赖
+- 测试 BackgroundTaskHelper 或 EventBus
+
+**触发关键词：**
+
+- test、测试、单测、单元测试、unittest、unit test
+- mock、mm、@eggjs/mock、mockCsrf、mockHttpclient、mockSession、mockContext
+- httpRequest、supertest
+- getEggObject、mockModuleContextScope
+- eventWaiter、BackgroundTaskHelper 测试
+- vitest、describe、it、beforeAll
+
+**示例查询：**
+
+- "如何写单元测试？"
+- "如何测试 HTTP 接口？"
+- "如何 mock 一个 Service？"
+- "POST 请求测试报 CSRF 错误"
+- "如何测试 ContextProto 的 Service？"
+- "怎么测试后台任务是否执行完成？"
+- "怎么测试 EventBus 事件是否被正确处理？"
 
 ---
 
@@ -106,14 +153,21 @@ allowed-tools: Read
 
 ### 步骤 3：协议/用例特定指示器
 
-| 协议/用例              | 主要技能         | 次要技能 |
-| ---------------------- | ---------------- | -------- |
-| HTTP API               | `egg-controller` | -        |
-| MCP                    | `egg-controller` | -        |
-| Scheduled Tasks        | `egg-controller` | -        |
-| Cross-module injection | `egg-core`       | -        |
-| Module structure       | `egg-core`       | -        |
-| Object lifecycle       | `egg-core`       | -        |
+| 协议/用例               | 主要技能         | 次要技能 |
+| ----------------------- | ---------------- | -------- |
+| HTTP API                | `egg-controller` | -        |
+| MCP                     | `egg-controller` | -        |
+| Scheduled Tasks         | `egg-controller` | -        |
+| Parameter validation    | `egg-controller` | -        |
+| Controller Middleware   | `egg-controller` | -        |
+| Background tasks        | `egg-core`       | -        |
+| Event-driven / EventBus | `egg-core`       | -        |
+| AOP / 切面编程          | `egg-core`       | -        |
+| Cross-module injection  | `egg-core`       | -        |
+| Module structure        | `egg-core`       | -        |
+| Object lifecycle        | `egg-core`       | -        |
+| Unit Testing            | `egg-unittest`   | -        |
+| Mock / Test helpers     | `egg-unittest`   | -        |
 
 ## 冲突解决规则
 
@@ -147,15 +201,22 @@ allowed-tools: Read
 
 ## 快速参考表
 
-| 用户意图             | 关键词                          | 使用技能               |
-| -------------------- | ------------------------------- | ---------------------- |
-| Module architecture  | module、workspace、organization | `egg-core` skill       |
-| Object lifecycle     | singleton、context、lifecycle   | `egg-core` skill       |
-| Dependency injection | inject、@Inject、dependency     | `egg-core` skill       |
-| Access control       | private、public、cross-module   | `egg-core` skill       |
-| HTTP endpoints       | HTTP、API、REST                 | `egg-controller` skill |
-| LLM/AI integration   | MCP、tool、prompt               | `egg-controller` skill |
-| Scheduling           | schedule、cron、timer           | `egg-controller` skill |
+| 用户意图             | 关键词                                  | 使用技能               |
+| -------------------- | --------------------------------------- | ---------------------- |
+| Module architecture  | module、workspace、organization         | `egg-core` skill       |
+| Object lifecycle     | singleton、context、lifecycle           | `egg-core` skill       |
+| Dependency injection | inject、@Inject、dependency             | `egg-core` skill       |
+| Access control       | private、public、cross-module           | `egg-core` skill       |
+| Background tasks     | background task、异步任务、后台任务     | `egg-core` skill       |
+| Event-driven         | eventbus、事件总线、@Event、emit        | `egg-core` skill       |
+| AOP 切面编程         | aop、切面、advice、pointcut、crosscut   | `egg-core` skill       |
+| HTTP endpoints       | HTTP、API、REST                         | `egg-controller` skill |
+| LLM/AI integration   | MCP、tool、prompt                       | `egg-controller` skill |
+| Scheduling           | schedule、cron、timer                   | `egg-controller` skill |
+| Param validation     | validate、校验、ajv、typebox、schema    | `egg-controller` skill |
+| Middleware 中间件    | middleware、中间件、拦截器、@Middleware | `egg-controller` skill |
+| Unit testing         | test、mock、unittest、单测              | `egg-unittest` skill   |
+| Mock dependencies    | mock、mm、mockCsrf、mockHttpclient      | `egg-unittest` skill   |
 
 ---
 
@@ -206,6 +267,18 @@ allowed-tools: Read
 2. 简要解释 @Inject 如何工作（核心概念摘要）
 3. 注意："包含限定符的详细 @Inject 使用，请使用 `egg-core` skill"
 
+### 示例 5：测试相关
+
+**用户**："帮我写个 UserController 的单元测试"
+
+**分析**：问题关于编写测试代码
+**决策**：使用 `egg-unittest` skill
+
+**用户**："POST 请求测试报 403 错误"
+
+**分析**：测试中遇到 CSRF 问题
+**决策**：使用 `egg-unittest` skill
+
 ## 路由最佳实践
 
 1. **优先考虑显式控制器提及**：如果用户命名特定控制器（HTTP），即使涉及核心概念也使用控制器技能
@@ -226,5 +299,6 @@ allowed-tools: Read
 
 - 为框架内部概念路由到 `egg-core` skill
 - 为协议特定实现路由到 `egg-controller` skill
+- 为测试相关问题路由到 `egg-unittest` skill
 - 当意图模糊时提供决策指导
 - 当存在有用的上下文时交叉引用技能

package/egg-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: egg-controller
-description: Use when creating API endpoints, implementing protocol handlers, or exposing interfaces for specific clients. Covers HTTP, MCP and Schedule controllers for EGG framework applications.
+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
 ---
 
@@ -18,6 +18,14 @@ allowed-tools: Read
 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`
 ```
 
 ---
@@ -42,15 +50,33 @@ allowed-tools: Read
 - **模式**：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 默认扫描冲突                            |
+| 现象                   | 原因                                     | 解决方案                                                           |
+| ---------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
+| 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                      |
 
 ---
 
@@ -71,5 +97,9 @@ allowed-tools: Read
 - `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

package/egg-controller/references/ajv-validate.md

@@ -0,0 +1,146 @@
+# Ajv 参数校验指南
+
+## 常见错误
+
+| 错误写法                         | 正确写法                          | 说明                                           |
+| -------------------------------- | --------------------------------- | ---------------------------------------------- |
+| `import { Type } from 'typebox'` | `import { Type } from 'egg/ajv'`  | 必须从 `egg/ajv` 导入，内部已封装 typebox      |
+| `import { Ajv } from 'ajv'`      | `import { Ajv } from 'egg/ajv'`   | Ajv 实例通过 `egg/ajv` 导出                    |
+| `new Ajv()` 手动创建实例         | `@Inject() ajv: Ajv` 注入全局单例 | 框架已配置好 formats 和 keywords，不要自行创建 |
+| 在 Service 中做参数校验          | 在 Controller 中做参数校验        | 入参校验应在 Controller 层完成                 |
+
+---
+
+## 核心概念
+
+Egg 通过 `@eggjs/typebox-validate` 插件集成 Ajv（JSON Schema 校验库）和 TypeBox（TypeScript-first 的 JSON Schema 构建器）。**定义一次 Schema，同时获得参数校验和 TypeScript 类型推导。**
+
+### 导入路径
+
+```typescript
+// 所有 Ajv/TypeBox 相关导入统一从 egg/ajv
+import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';
+```
+
+---
+
+## 使用方式
+
+通过 `@Inject()` 注入全局 Ajv 单例，在 Controller 方法中调用 `ajv.validate()` 进行校验。
+
+### 完整示例
+
+```typescript
+// app/userModule/UserController.ts
+import {
+  HTTPController,
+  HTTPMethod,
+  HTTPMethodEnum,
+  HTTPBody,
+  Inject,
+} from 'egg';
+import { Ajv, Type, Static, TransformEnum } from 'egg/ajv';
+
+// 1. 定义 Schema
+const CreateUserSchema = Type.Object({
+  name: Type.String({
+    transform: [TransformEnum.trim],
+    minLength: 1,
+    maxLength: 50,
+  }),
+  email: Type.String({ format: 'email' }),
+  age: Type.Optional(Type.Integer({ minimum: 0, maximum: 150 })),
+});
+
+// 2. 从 Schema 推导类型
+type CreateUserParams = Static<typeof CreateUserSchema>;
+
+// 3. 在 Controller 中注入 Ajv 并校验
+@HTTPController()
+export class UserController {
+  @Inject()
+  private readonly ajv: Ajv;
+
+  @HTTPMethod({
+    method: HTTPMethodEnum.POST,
+    path: '/api/users',
+  })
+  async create(@HTTPBody() body: CreateUserParams) {
+    // 校验失败自动抛出 AjvInvalidParamError
+    this.ajv.validate(CreateUserSchema, body);
+
+    // 校验通过，body 已经有完整类型提示
+    return { name: body.name, email: body.email };
+  }
+}
+```
+
+---
+
+## Schema 定义
+
+### 常用类型
+
+```typescript
+import { Type } from 'egg/ajv';
+
+Type.String()                                      // string
+Type.Number()                                      // number
+Type.Integer()                                     // 整数
+Type.Boolean()                                     // boolean
+Type.Optional(Type.String())                       // string | undefined
+Type.Array(Type.String())                          // string[]
+Type.Object({ name: Type.String() })               // { name: string }
+Type.Union([Type.String(), Type.Number()])          // string | number
+Type.Literal('admin')                              // 'admin'
+```
+
+完整的 TypeBox JSON Schema 类型定义参考：https://github.com/sinclairzx81/typebox#json-types
+
+### 内置 format 校验
+
+框架通过 `ajv-formats` 预注册了以下格式：
+
+| format      | 说明       | 示例                                   |
+| ----------- | ---------- | -------------------------------------- |
+| `email`     | 邮箱       | `user@example.com`                     |
+| `uri`       | URI        | `https://example.com`                  |
+| `uuid`      | UUID       | `550e8400-e29b-41d4-a716-446655440000` |
+| `date`      | 日期       | `2024-01-01`                           |
+| `date-time` | 日期时间   | `2024-01-01T00:00:00Z`                 |
+| `time`      | 时间       | `12:00:00`                             |
+| `ipv4`      | IPv4       | `192.168.1.1`                          |
+| `ipv6`      | IPv6       | `::1`                                  |
+| `hostname`  | 主机名     | `example.com`                          |
+| `regex`     | 正则表达式 | `^\\d+$`                               |
+
+```typescript
+Type.String({ format: 'email' })
+Type.String({ format: 'uuid' })
+Type.String({ format: 'date-time' })
+```
+
+### transform 预处理
+
+通过 `ajv-keywords` 的 `transform` 关键字，在校验前对字符串做预处理：
+
+```typescript
+import { TransformEnum } from 'egg/ajv';
+
+Type.String({
+  transform: [TransformEnum.trim],               // 去除首尾空格
+})
+
+Type.String({
+  transform: [TransformEnum.trim, TransformEnum.toLowerCase],  // 去空格 + 转小写
+})
+```
+
+---
+
+## 最佳实践
+
+- **Schema 与 Controller 同文件** — Schema 定义放在使用它的 Controller 文件中，保持就近原则
+- **校验在 Controller 层** — 不要在 Service 层做入参校验，Service 信任上层传入的数据
+- **善用 Optional** — 非必填字段用 `Type.Optional()` 包装，避免前端遗漏字段导致校验失败
+- **善用 transform** — 对用户输入做 trim 预处理，减少脏数据

package/egg-controller/references/middleware.md

@@ -0,0 +1,133 @@
+# Middleware 中间件指南
+
+## 常见错误
+
+| 错误写法                                   | 正确写法                           | 说明                                            |
+| ------------------------------------------ | ---------------------------------- | ----------------------------------------------- |
+| `import { Middleware } from '@eggjs/tegg'` | `import { Middleware } from 'egg'` | Middleware 从 `egg` 导入                        |
+| `import { Advice } from 'egg'`             | `import { Advice } from 'egg/aop'` | AOP 装饰器从 `egg/aop` 导入                     |
+| `@Middleware(funcMw, AdviceClass)`         | 分开写两个 `@Middleware`           | 同一个 `@Middleware()` 中不能混用函数式和 AOP   |
+| AOP Advice 中用实例属性存请求级状态        | 使用 `ctx.set()`/`ctx.get()`       | Advice 默认 Singleton，实例属性会被并发请求共享 |
+| 把中间件文件放在 `app/middleware/`         | 放在模块目录下                     | 函数式中间件放在模块中，通过 import 引用        |
+
+---
+
+## 两种中间件模式
+
+Egg 的 `@Middleware` 装饰器支持两种中间件写法，根据传入参数类型自动识别：
+
+- **AOP 写法（推荐）**：使用 `@Advice` 类，支持 `@Inject` 注入 Proto 依赖，拥有丰富的生命周期钩子
+- **函数式写法（旧版兼容）**：标准 Koa 中间件函数，需要从 `ctx` 对象上手动获取依赖
+
+新项目应优先使用 AOP 写法。函数式写法主要用于兼容旧的 egg 中间件或非常简单的场景。
+
+---
+
+## 实现中间件
+
+### AOP 写法（推荐）
+
+使用 `@Advice()` 装饰器定义类，实现 `IAdvice` 的 `around` 方法，写法与 Koa 中间件一致（`next` 调用目标方法）。Advice 本身是 Proto，支持 `@Inject` 注入依赖。`around` 中可以修改入参（`ctx.args`）和返回值：
+
+```typescript
+// app/modules/foo/advice/LogAdvice.ts
+import { AccessLevel, Inject, Logger } from 'egg';
+import { Advice, IAdvice, AdviceContext } from 'egg/aop';
+
+// 跨模块使用时需设置 accessLevel: AccessLevel.PUBLIC
+@Advice({ accessLevel: AccessLevel.PUBLIC })
+export class LogAdvice implements IAdvice {
+  @Inject()
+  logger: Logger;
+
+  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
+    // 修改入参：ctx.args 对应控制器方法的参数列表
+    // ctx.args[0] = sanitize(ctx.args[0]);
+
+    const start = Date.now();
+    const result = await next();
+    this.logger.info('%s cost %dms', ctx.method, Date.now() - start);
+
+    // 修改返回值：直接返回新的值即可
+    return { success: true, data: result };
+  }
+}
+```
+
+### 函数式写法（旧版兼容）
+
+标准 Koa 中间件函数，签名为 `(ctx: Context, next: Next) => Promise<void>`。旧版 egg 写法，无法使用 `@Inject`，需要从 `ctx` 对象上手动获取依赖：
+
+```typescript
+// app/modules/foo/middleware/count.ts
+import type { Context, Next } from 'egg';
+
+export async function countMw(ctx: Context, next: Next): Promise<void> {
+  const start = Date.now();
+  await next();
+  ctx.set('X-Response-Time', `${Date.now() - start}ms`);
+}
+```
+
+---
+
+## 应用中间件
+
+通过 `@Middleware()` 装饰器将中间件应用到控制器，支持类级别和方法级别：
+
+```typescript
+// app/modules/foo/FooController.ts
+import { HTTPController, HTTPMethod, HTTPMethodEnum, Middleware } from 'egg';
+import { LogAdvice } from '../common/advice/LogAdvice.ts';
+import { countMw } from './middleware/count.ts';
+
+@HTTPController({ path: '/api' })
+@Middleware(LogAdvice)  // 类级别：所有方法都会执行
+export class FooController {
+  @HTTPMethod({ method: HTTPMethodEnum.GET, path: '/profile' })
+  @Middleware(countMw)  // 方法级别：仅此方法执行
+  async getProfile() {
+    return { name: 'test' };
+  }
+}
+```
+
+---
+
+## 执行顺序
+
+遵循洋葱模型，类级别先执行，方法级别后执行：
+
+```typescript
+@Middleware(globalMw)
+export class FooController {
+  // 进：globalMw → methodMw → hello()
+  // 出：hello() → methodMw → globalMw
+  @Middleware(methodMw)
+  async hello() {}
+
+  // 多个 @Middleware 从下往上执行（靠近方法的先注册）
+  // 进：globalMw → mw3 → mw2 → mw1 → multiple()
+  // 出：multiple() → mw1 → mw2 → mw3 → globalMw
+  @Middleware(mw1)
+  @Middleware(mw2)
+  @Middleware(mw3)
+  async multiple() {}
+}
+```
+
+**若混用函数式和 AOP 中间件，所有函数式中间件（无论类级别还是方法级别）会先于所有 AOP 中间件执行。** 即函数式和 AOP 分属两个独立的执行阶段，函数式阶段在前，AOP 阶段在后：
+
+```typescript
+@Middleware(countMw)       // 函数式 - 类级别
+@Middleware(LogAdvice)     // AOP - 类级别
+export class FooController {
+  @Middleware(timeMw)      // 函数式 - 方法级别
+  @Middleware(AuthAdvice)  // AOP - 方法级别
+  async hello() {}
+}
+
+// 实际执行顺序：
+// countMw → timeMw → LogAdvice → AuthAdvice → hello()
+// （先所有函数式，再所有 AOP；各阶段内类级别先于方法级别）
+```