@eggjs/skills 4.1.2-beta.4 → 4.1.2-beta.6

package/egg-core/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: egg-core
-description: 本技能用于处理 EGG 基础核心概念，包括模块架构、@SingletonProto、@ContextProto、@Inject 装饰器和动态注入。用于理解 EGG 的基础构建块、依赖注入、对象生命周期管理和运行时多实现动态选择。
+description: 本技能用于处理 EGG 基础核心概念，包括模块架构、@SingletonProto、@ContextProto、@Inject 装饰器、动态注入、BackgroundTaskHelper 后台任务、EventBus 事件总线和 AOP 切面编程。用于理解 EGG 的基础构建块、依赖注入、对象生命周期管理、运行时多实现动态选择、请求返回后的异步任务处理、事件驱动架构和横切关注点。
 allowed-tools: Read
 ---
 
 # egg 核心概念
 
-## Step 1: 代码写在 module 中
+## 代码组织与依赖注入
 
-### 什么是模块？
+### Step 1: 代码写在 module 中
+
+#### 什么是模块？
 
 模块是 EGG 中基础的代码组织单元。只有模块内的代码会被框架扫描和加载。模块之间相互独立，但可以通过 `@Inject` 装饰器访问其他模块的对象。
 
-### 定义 module
+#### 定义 module
 
 在目录中添加包含 `eggModule.name` 字段的 `package.json` 文件来声明该目录为模块：
 
@@ -83,9 +85,23 @@ export class ConfigService {
 - 存量应用：保留老的 egg 代码在 `app/controller`/`app/service`，将新增的 module 代码放在 `app/module/`
 - 可以在 `dependencies` 中导入 npm 包作为额外模块
 
-## Step 2: 用 Proto 实现 Service
+### 导入路径
+
+所有装饰器和类型统一从 `egg` 导入，不要从 `@eggjs/tegg` 导入：
+
+```typescript
+// ✅ 正确
+import { SingletonProto, ContextProto, Inject, AccessLevel } from 'egg';
 
-### SingletonProto
+// ❌ 错误 — 不要从 @eggjs/tegg 导入
+import { SingletonProto } from '@eggjs/tegg';
+```
+
+---
+
+### Step 2: 用 Proto 实现 Service
+
+#### SingletonProto
 
 应用启动时立即创建，整个应用生命周期内只有一个实例，性能更好，应该作为默认选择。
 
@@ -100,7 +116,7 @@ export class HelloService {
 }
 ```
 
-### ContextProto
+#### ContextProto
 
 请求到达时按需创建，每个请求一个实例，请求结束自动销毁。仅在需要隔离不同请求的上下文信息时使用。
 
@@ -115,7 +131,7 @@ export class RequestContext {
 
 **重要提示**：大多数服务应该使用 `SingletonProto` 以获得更好的性能。只有当请求上下文必须在服务之间共享以确保请求之间隔离时，才使用 `ContextProto`。
 
-### AccessLevel
+#### AccessLevel
 
 proto 对象默认 accessLevel 为 `AccessLevel.PRIVATE`，仅在当前 module 内使用。可以设置为 `AccessLevel.PUBLIC`，进行跨模块访问。
 
@@ -129,9 +145,9 @@ export class SharedService {}
 export class SharedContextService {}
 ```
 
-## Step 3: 通过 Inject 使用 Service
+### Step 3: 通过 Inject 使用 Service
 
-### 基本用法
+#### 基本用法
 
 使用 `@Inject()` 注入其他 Proto 或 Egg 对象：
 
@@ -153,19 +169,19 @@ export class HelloService {
 }
 ```
 
-### 动态注入
+#### 动态注入
 
 当同一个抽象有多种实现，需要在运行时动态选择时，通过 `EggObjectFactory` 按类型获取实现，无需 if/else。详见 `references/dynamic-inject.md`。
 
-### 重要约束
+#### 重要约束
 
 - **不能有循环依赖**：Proto 或模块之间都不能有循环依赖
 - **不能有同名对象**：一个模块不能有相同名称和初始化类型的 Proto
 - **按需注入**：不要直接注入 `app` 或 `ctx`，按需注入特定对象
 
-## 快速决策指南
+### 快速决策指南
 
-| 场景                             | 使用装饰器                                             |
+| 场景                             | 使用方式                                               |
 | -------------------------------- | ------------------------------------------------------ |
 | 无状态服务                       | `@SingletonProto()`                                    |
 | 跨服务共享的请求级状态           | `@ContextProto()`                                      |
@@ -174,6 +190,41 @@ export class HelloService {
 | 使用自定义名称注入               | `@Inject({ name: 'customName' })`                      |
 | 同一抽象多种实现，运行时动态选择 | `QualifierImplDecoratorUtil` + `EggObjectFactory`      |
 
+## 异步任务
+
+| 特性       | BackgroundTaskHelper          | EventBus                                  |
+| ---------- | ----------------------------- | ----------------------------------------- |
+| **耦合**   | 高 — 异步逻辑写在触发者代码中 | 低 — handler 独立，新增处理者不修改触发者 |
+| **上下文** | 共享触发者的请求上下文        | handler 运行在独立的新上下文中            |
+| **扩展**   | 需要修改触发者代码            | 新增 `@Event` handler 类即可              |
+
+```
+需要在请求之外执行任务？
+│
+├─ 请求返回后执行，依赖当前请求上下文
+│  └─ → BackgroundTaskHelper（references/background-task.md）
+│
+├─ 请求返回后执行，不依赖当前请求上下文，需要解耦
+│  └─ → EventBus（references/eventbus.md）
+│
+└─ 定时或周期执行
+   └─ → Schedule（参考 egg-controller skill）
+```
+
+## AOP 切面编程
+
+AOP 用于将日志、鉴权、缓存、事务等横切关注点从业务代码中分离。AOP 装饰器从 `egg/aop` 导入（不是 `egg`）。
+
+```
+需要在方法执行前后添加通用逻辑？
+│
+├─ 针对特定方法 → @Pointcut（在目标方法上声明）
+│
+└─ 批量切入多个类/方法 → @Crosscut（在 Advice 类上声明匹配规则）
+```
+
+详细用法（Advice 生命周期、AdviceContext、Pointcut/Crosscut 选型、参数透传、执行顺序）请参阅 `references/aop.md`。
+
 ## 常见问题排查
 
 | 现象                   | 原因                                       | 解决方案                                     |
@@ -190,3 +241,8 @@ export class HelloService {
 - Inject 装饰器使用，请参阅：`references/inject.md`
 - SingletonProto 和 ContextProto 详情，请参阅：`references/proto.md`
 - 动态注入（Qualifier 动态注入），请参阅：`references/dynamic-inject.md`
+- 请求后异步任务（BackgroundTaskHelper），请参阅：`references/background-task.md`
+- 事件总线（EventBus），请参阅：`references/eventbus.md`
+- AOP 切面编程（Advice、Pointcut、Crosscut），请参阅：`references/aop.md`
+
+单元测试（`egg-unittest` skill）：Service 测试、BackgroundTask 测试、EventBus 测试

package/egg-core/references/aop.md

@@ -0,0 +1,219 @@
+# AOP 切面编程指南
+
+## 常见错误
+
+| 错误写法                                   | 正确写法                              | 说明                                                                                   |
+| ------------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------- |
+| `import { Advice } from 'egg'`             | `import { Advice } from 'egg/aop'`    | AOP 装饰器从 `egg/aop` 导入，不是 `egg`                                                |
+| `import { Advice } from '@eggjs/tegg/aop'` | `import { Advice } from 'egg/aop'`    | 统一从 `egg/aop` 导入                                                                  |
+| Advice 类没有加 `@Advice()` 装饰器         | 必须同时有 `@Advice()`                | `@Pointcut` 和 `@Crosscut` 都要求目标是 Advice 类                                      |
+| `@Crosscut` 直接切 Egg 内置对象            | 只能切 tegg Proto 对象                | Egg 中的对象（如 app、ctx）无法被 Crosscut                                             |
+| Advice 中用实例属性存状态                  | 使用 `ctx.set()`/`ctx.get()` 共享状态 | Advice 默认是 Singleton，实例属性会被并发请求共享，必须用 AdviceContext 传递调用级状态 |
+
+---
+
+## 核心概念
+
+### Advice（切面逻辑）
+
+Advice 是 AOP 的核心，定义了在目标方法执行前后要做什么。Advice 本身也是一种 Proto，默认 initType 为 Singleton（全局单例），可以使用 `@Inject` 注入依赖。如需每请求一个实例，显式指定 `@Advice({ initType: ObjectInitType.CONTEXT })`。
+
+```typescript
+import { Advice, IAdvice, AdviceContext } from 'egg/aop';
+import { Inject, Logger } from 'egg';
+
+@Advice()
+export class LogAdvice implements IAdvice {
+  @Inject()
+  private logger: Logger;
+
+  async beforeCall(ctx: AdviceContext): Promise<void> {
+    ctx.set('startTime', Date.now());
+  }
+
+  async afterReturn(ctx: AdviceContext, result: any): Promise<void> {
+    // 方法成功返回后执行
+  }
+
+  async afterThrow(ctx: AdviceContext, error: Error): Promise<void> {
+    // 方法抛出异常后执行
+  }
+
+  async afterFinally(ctx: AdviceContext): Promise<void> {
+    const duration = Date.now() - ctx.get('startTime');
+    this.logger.info('%s cost %dms', String(ctx.method), duration);
+  }
+
+  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
+    // 类似 koa 中间件，可以包裹方法执行
+    return await next();
+  }
+}
+```
+
+**执行顺序：**
+
+```typescript
+await beforeCall(ctx);
+try {
+  const result = await around(ctx, next);  // next 执行目标方法
+  await afterReturn(ctx, result);
+  return result;
+} catch (e) {
+  await afterThrow(ctx, e);
+  throw e;
+} finally {
+  await afterFinally(ctx);
+}
+```
+
+**关键点：**
+
+- 所有 hook 方法都是可选的，按需实现
+- 只有 `around` 可以修改返回值
+- `beforeCall` 中可以通过修改 `ctx.args` 改变方法入参
+- 多个 Advice 之间通过 `ctx.set(key, value)` / `ctx.get(key)` 共享状态
+
+### AdviceContext
+
+```typescript
+interface AdviceContext<T = object, K = any> {
+  that: T;              // 被切的对象实例
+  method: PropertyKey;  // 被切的方法名
+  args: any[];          // 方法参数（可修改）
+  adviceParams?: K;     // 装饰器透传的参数
+  get(key: PropertyKey): any;       // 获取共享状态
+  set(key: PropertyKey, value: any): this;  // 设置共享状态
+}
+```
+
+---
+
+## Pointcut vs Crosscut
+
+### Pointcut — 精确切入
+
+在特定类的特定方法上声明 Advice，适合精确控制：
+
+```typescript
+import { SingletonProto } from 'egg';
+import { Pointcut } from 'egg/aop';
+
+@SingletonProto()
+export class OrderService {
+  @Pointcut(LogAdvice)
+  async createOrder(data: any) {
+    // 业务逻辑
+  }
+
+  // 可以传参给 Advice
+  @Pointcut(TransactionAdvice, { adviceParams: { propagation: 'REQUIRED' } })
+  async updateOrder(id: string, data: any) {
+    // 业务逻辑
+  }
+}
+```
+
+### Crosscut — 批量切入
+
+在 Advice 类上声明切入规则，适合横切多个类/方法：
+
+```typescript
+import { Crosscut, Advice, IAdvice, PointcutType } from 'egg/aop';
+
+// 模式 1：指定类和方法
+@Crosscut({
+  type: PointcutType.CLASS,
+  clazz: OrderService,
+  methodName: 'createOrder',
+})
+@Advice()
+export class AuditAdvice implements IAdvice {
+  async afterReturn(ctx: AdviceContext): Promise<void> {
+    // 审计日志
+  }
+}
+
+// 模式 2：正则匹配
+@Crosscut({
+  type: PointcutType.NAME,
+  className: /.*Service$/i,
+  methodName: /^(create|update|delete)/,
+})
+@Advice()
+export class OperationLogAdvice implements IAdvice {
+  async around(ctx: AdviceContext, next: () => Promise<any>): Promise<any> {
+    // 记录所有 Service 的写操作
+    return await next();
+  }
+}
+
+// 模式 3：自定义回调
+@Crosscut({
+  type: PointcutType.CUSTOM,
+  callback: (clazz, method) => {
+    return clazz.name.endsWith('Repository') && method !== 'constructor';
+  },
+})
+@Advice()
+export class DbMetricsAdvice implements IAdvice {}
+```
+
+### 执行顺序
+
+- `@Crosscut` 默认 order: `100`
+- `@Pointcut` 默认 order: `1000`
+- order 越小越先执行
+- 同一方法上多个 Advice 按 order 升序排列
+
+通过 `order` 参数自定义顺序：
+
+```typescript
+// Pointcut：第二个参数中设置 order
+@Pointcut(LogAdvice, { order: 50 })
+async createOrder(data: any) {}
+
+// Crosscut：第二个参数中设置 order
+@Crosscut(
+  { type: PointcutType.NAME, className: /.*Service$/i, methodName: /.+/ },
+  { order: 200 },
+)
+@Advice()
+export class MetricsAdvice implements IAdvice {}
+```
+
+---
+
+## 参数透传
+
+同一个 Advice 在不同方法上可能需要不同的行为，通过 `adviceParams` 传参：
+
+```typescript
+@Advice()
+export class CacheAdvice implements IAdvice {
+  async around(ctx: AdviceContext<any, { ttl: number }>, next: () => Promise<any>): Promise<any> {
+    const ttl = ctx.adviceParams?.ttl ?? 60;
+    // 根据 ttl 实现缓存逻辑
+    return await next();
+  }
+}
+
+@SingletonProto()
+export class UserService {
+  @Pointcut(CacheAdvice, { adviceParams: { ttl: 3600 } })
+  async getUser(id: string) { /* ... */ }
+
+  @Pointcut(CacheAdvice, { adviceParams: { ttl: 60 } })
+  async getUserList() { /* ... */ }
+}
+```
+
+---
+
+## 典型场景
+
+| 场景                        | 推荐方式                 | 说明              |
+| --------------------------- | ------------------------ | ----------------- |
+| 特定方法加日志/缓存         | `@Pointcut(Advice)`      | 精确控制          |
+| 所有 Service 的写操作加审计 | `@Crosscut(NAME)` + 正则 | 批量匹配          |
+| 事务包裹                    | `@Pointcut(TxAdvice)`    | around 中管理事务 |

package/egg-core/references/background-task.md

@@ -0,0 +1,121 @@
+# BackgroundTask 异步任务指南
+
+## 常见错误
+
+| 错误写法                                                    | 正确写法                                        | 说明                                                      |
+| ----------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
+| `setTimeout(() => { ... }, 0)`                              | `backgroundTaskHelper.run(async () => { ... })` | setTimeout 执行时上下文已释放，会导致访问已销毁对象的错误 |
+| `setImmediate(() => { ... })`                               | `backgroundTaskHelper.run(async () => { ... })` | 同上，框架不会等待 setImmediate 的回调                    |
+| `process.nextTick(() => { ... })`                           | `backgroundTaskHelper.run(async () => { ... })` | 同上                                                      |
+| 在 Service 中 `await` 后台任务                              | 直接调用 `run()` 不 await                       | `run()` 是"发射后不管"，不返回 Promise                    |
+| `import { BackgroundTaskHelper } from '@eggjs/tegg/helper'` | `import { BackgroundTaskHelper } from 'egg'`    | 统一从 `egg` 导入，不要从 `@eggjs/tegg` 子路径导入        |
+
+---
+
+## 使用方式
+
+### 基本用法
+
+通过 `@Inject()` 注入 `BackgroundTaskHelper`，调用 `run()` 方法。`run()` 接受一个异步函数，任务会立即开始执行但不阻塞当前流程。框架在请求结束（Context preDestroy）时会等待所有后台任务完成（最多等待 timeout），然后再释放上下文。
+
+```typescript
+import { BackgroundTaskHelper, Inject, SingletonProto, AccessLevel } from 'egg';
+
+@SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+export class MetricsService {
+  @Inject()
+  private backgroundTaskHelper: BackgroundTaskHelper;
+
+  async reportAfterResponse(data: Record<string, unknown>) {
+    // run() 是非阻塞的，任务立即开始执行但不会被 await
+    this.backgroundTaskHelper.run(async () => {
+      // 框架会保持上下文存活直到任务完成或超时
+      await this.sendMetrics(data);
+    });
+  }
+
+  private async sendMetrics(data: Record<string, unknown>) {
+    // 实际上报逻辑
+  }
+}
+```
+
+---
+
+## 超时配置
+
+框架默认等待 5 秒，超时后放弃等待并释放上下文。
+
+### 按请求调整超时
+
+```typescript
+this.backgroundTaskHelper.timeout = 10000; // 10 秒
+this.backgroundTaskHelper.run(async () => {
+  await heavyWork();
+});
+```
+
+注意：timeout 是 context 级别的设置，同一请求中多次设置以最后一次为准。
+
+### 全局配置
+
+```typescript
+// config/config.default.ts
+export default {
+  backgroundTask: {
+    timeout: 10000, // 全局默认 10 秒
+  },
+};
+```
+
+### 无限等待
+
+```typescript
+// 不推荐在生产环境使用，除非确定任务一定会完成
+this.backgroundTaskHelper.timeout = Infinity;
+```
+
+---
+
+## 错误处理
+
+BackgroundTaskHelper 内部会捕获所有错误并记录日志，**不会**抛出异常或影响其他后台任务。
+
+```typescript
+this.backgroundTaskHelper.run(async () => {
+  // 即使这里抛出异常，也不会影响其他后台任务或框架
+  throw new Error('something went wrong');
+  // 错误会被记录为: [BackgroundTaskHelper] background throw error:something went wrong
+});
+
+// 如果需要自定义错误处理
+this.backgroundTaskHelper.run(async () => {
+  try {
+    await unreliableOperation();
+  } catch (e) {
+    // 自定义错误处理：重试、告警等
+    await this.alertService.notify(e);
+  }
+});
+```
+
+---
+
+## 原理
+
+请求处理完成后，框架会立即释放上下文（防止内存泄漏）。如果用 `setTimeout` 等方式在上下文释放后访问注入的服务，会因为上下文已销毁而出错。
+
+BackgroundTaskHelper 的作用是：
+
+1. `run()` 被调用时，任务立即开始执行（不是延后到响应发送后）
+2. 任务不会被 await，因此不阻塞当前请求的返回
+3. 请求结束时（Context preDestroy），框架等待所有后台任务完成（最多等待 timeout）
+4. 等待结束后才释放上下文
+
+这就是为什么必须用 `backgroundTaskHelper.run()` 而不是 `setTimeout` — 后者绕过了框架的上下文生命周期管理，执行时上下文可能已被释放。
+
+---
+
+## 单元测试
+
+BackgroundTaskHelper 的测试方法参考 `egg-unittest` skill 的 `references/background-task-test.md`。

package/egg-core/references/eventbus.md

@@ -0,0 +1,138 @@
+# EventBus 事件总线指南
+
+## 常见错误
+
+| 错误写法                                         | 正确写法                                    | 说明                                             |
+| ------------------------------------------------ | ------------------------------------------- | ------------------------------------------------ |
+| `import { EventBus } from '@eggjs/tegg'`         | `import { EventBus } from 'egg'`            | 统一从 `egg` 导入                                |
+| `import { Event } from '@eggjs/tegg'`            | `import { Event } from 'egg'`               | 装饰器也从 `egg` 导入                            |
+| 在 handler 的 `handle` 方法中直接访问请求上下文  | 使用 `@EventContext()` 注入 `IEventContext` | handler 运行在独立的上下文中，不是触发者的上下文 |
+| `@Event('hello')` 但没有声明 Events 接口         | 先在 `declare module 'egg'` 中声明事件类型  | 不声明会导致类型检查报错                         |
+| handler 的 `handle` 方法签名与 Events 声明不一致 | 确保参数类型与 Events 中定义一致            | TypeScript 会检查签名是否匹配                    |
+
+---
+
+## 使用步骤
+
+### 1. 声明事件类型
+
+在模块中创建类型声明文件，定义事件名称和参数签名：
+
+```typescript
+// app/myModule/event.ts
+import 'egg';
+
+declare module 'egg' {
+  interface Events {
+    orderCreated: (orderId: string, userId: string) => void;
+    paymentCompleted: (orderId: string, amount: number) => void;
+  }
+}
+```
+
+**注意：** 文件开头必须有 `import 'egg'`，否则 `declare module` 会覆盖而非合并模块声明。
+
+### 2. 触发事件
+
+通过 `@Inject()` 注入 `EventBus` 或 `ContextEventBus`，调用 `emit()` 触发事件：
+
+```typescript
+import { SingletonProto, Inject, EventBus, AccessLevel } from 'egg';
+
+@SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+export class OrderService {
+  @Inject()
+  private eventBus: EventBus;
+
+  async createOrder(userId: string, items: Item[]): Promise<string> {
+    const orderId = await this.saveOrder(userId, items);
+    // 触发事件，不阻塞当前流程
+    this.eventBus.emit('orderCreated', orderId, userId);
+    return orderId;
+  }
+}
+```
+
+`emit()` 的参数类型由 Events 接口约束，TypeScript 会自动提示和校验。
+
+### 3. 消费事件
+
+用 `@Event()` 装饰器标记 handler 类。handler 必须实现 `handle` 方法，参数签名与 Events 声明一致：
+
+```typescript
+import { Event, Inject } from 'egg';
+import type { EggLogger } from 'egg';
+
+@Event('orderCreated')
+export class OrderNotificationHandler {
+  @Inject()
+  private logger: EggLogger;
+
+  async handle(orderId: string, userId: string): Promise<void> {
+    this.logger.info('[OrderNotification] order %s created by user %s', orderId, userId);
+    // 发送通知等业务逻辑
+  }
+}
+```
+
+**handler 的关键特性：**
+
+- handler 运行在独立的上下文中，不是触发者的上下文
+- 同一事件可以有多个 handler，它们并行执行
+- handler 文件放在模块目录中，框架自动扫描和注册
+
+### 4. 消费多个事件
+
+一个 handler 可以处理多个事件，通过 `@EventContext()` 获取事件上下文来区分：
+
+```typescript
+import { Event, EventContext, type IEventContext } from 'egg';
+
+@Event('orderCreated')
+@Event('paymentCompleted')
+export class AuditLogHandler {
+  async handle(@EventContext() ctx: IEventContext, ...args: unknown[]): Promise<void> {
+    console.log('event:', ctx.eventName, 'args:', args);
+  }
+}
+```
+
+`@EventContext()` 只能修饰 `handle` 方法的第一个参数。不需要区分事件时可以省略。
+
+---
+
+## Cork/Uncork 事件缓冲
+
+当需要在一个操作中触发多个事件，但希望它们在操作全部完成后才被处理时，使用 cork/uncork：
+
+```typescript
+import { ContextProto, Inject, type ContextEventBus } from 'egg';
+
+@ContextProto()
+export class BatchService {
+  @Inject()
+  private eventBus: ContextEventBus;  // 注意：cork/uncork 需要 ContextEventBus
+
+  async processBatch(items: string[]): Promise<void> {
+    this.eventBus.cork();     // 开始缓冲，事件不会立即派发
+
+    for (const item of items) {
+      this.eventBus.emit('orderCreated', item, 'batch-user');
+    }
+
+    this.eventBus.uncork();   // 释放缓冲，所有事件一次性派发
+  }
+}
+```
+
+**Cork/Uncork 行为：**
+
+- 支持嵌套调用 — 内层 uncork 不会释放事件，只有最外层 uncork 才会
+- `ContextEventBus` 的 cork/uncork 自动管理 corkId，无需手动指定
+- cork 期间 emit 的事件会被暂存，uncork 后按顺序派发
+
+---
+
+## 单元测试
+
+EventBus 的测试方法参考 `egg-unittest` skill 的 `references/eventbus-test.md`。