@eggjs/skills 0.0.0 → 4.1.2-beta.10

package/egg-core/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: egg-core
+description: 本技能用于处理 EGG 基础核心概念，包括模块架构、@SingletonProto、@ContextProto、@Inject 装饰器、动态注入、BackgroundTaskHelper 后台任务、EventBus 事件总线和 AOP 切面编程。用于理解 EGG 的基础构建块、依赖注入、对象生命周期管理、运行时多实现动态选择、请求返回后的异步任务处理、事件驱动架构和横切关注点。
+allowed-tools: Read
+---
+
+# egg 核心概念
+
+## 代码组织与依赖注入
+
+### Step 1: 代码写在 module 中
+
+#### 什么是模块？
+
+模块是 EGG 中基础的代码组织单元。只有模块内的代码会被框架扫描和加载。模块之间相互独立，但可以通过 `@Inject` 装饰器访问其他模块的对象。
+
+#### 定义 module
+
+在目录中添加包含 `eggModule.name` 字段的 `package.json` 文件来声明该目录为模块：
+
+```json
+{
+  "name": "foo",
+  "eggModule": {
+    "name": "foo"
+  }
+}
+```
+
+**重要提示**：模块名称不能包含 `-` 或其他特殊字符；使用驼峰命名规则。
+
+#### 正确示例
+
+```
+app/
+└── userModule/           ✅ 驼峰命名
+    ├── package.json
+    │   └── { "eggModule": { "name": "userModule" } }
+    └── service.ts        ✅ 会被框架加载
+```
+
+#### 错误示例
+
+```
+app/
+├── user-module/          ❌ 名称包含 `-`
+│   └── package.json
+│       └── { "eggModule": { "name": "user-module" } }
+│
+└── common/               ❌ 缺少 package.json（不是 module）
+    └── utils.ts          ❌ 不会被框架加载
+```
+
+#### 模块配置
+
+在模块根目录创建 `module.yml` 用于模块特定配置：
+
+```yaml
+foo: bar
+```
+
+通过 `@Inject()` 注入配置，使用 `moduleConfig`：
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+interface ModuleConfig {
+  foo: string;
+}
+
+@SingletonProto()
+export class ConfigService {
+  @Inject()
+  private readonly moduleConfig: ModuleConfig;
+
+  async hello(): Promise<string> {
+    return `hello ${this.moduleConfig.foo}`;
+  }
+}
+```
+
+#### 模块组织最佳实践
+
+- 新应用：按功能在 `app/` 目录中组织
+- 存量应用：保留老的 egg 代码在 `app/controller`/`app/service`，将新增的 module 代码放在 `app/module/`
+- 可以在 `dependencies` 中导入 npm 包作为额外模块
+
+### 导入路径
+
+所有装饰器和类型统一从 `egg` 导入，不要从 `@eggjs/tegg` 导入：
+
+```typescript
+// ✅ 正确
+import { SingletonProto, ContextProto, Inject, AccessLevel } from 'egg';
+
+// ❌ 错误 — 不要从 @eggjs/tegg 导入
+import { SingletonProto } from '@eggjs/tegg';
+```
+
+---
+
+### Step 2: 用 Proto 实现 Service
+
+#### SingletonProto
+
+应用启动时立即创建，整个应用生命周期内只有一个实例，性能更好，应该作为默认选择。
+
+```typescript
+import { SingletonProto } from 'egg';
+
+@SingletonProto()
+export class HelloService {
+  async hello(): Promise<string> {
+    return 'hello';
+  }
+}
+```
+
+#### ContextProto
+
+请求到达时按需创建，每个请求一个实例，请求结束自动销毁。仅在需要隔离不同请求的上下文信息时使用。
+
+```typescript
+import { ContextProto } from 'egg';
+
+@ContextProto()
+export class RequestContext {
+  userId: string;
+}
+```
+
+**重要提示**：大多数服务应该使用 `SingletonProto` 以获得更好的性能。只有当请求上下文必须在服务之间共享以确保请求之间隔离时，才使用 `ContextProto`。
+
+#### AccessLevel
+
+proto 对象默认 accessLevel 为 `AccessLevel.PRIVATE`，仅在当前 module 内使用。可以设置为 `AccessLevel.PUBLIC`，进行跨模块访问。
+
+```typescript
+import { AccessLevel, ContextProto, SingletonProto } from 'egg';
+
+@SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+export class SharedService {}
+
+@ContextProto({ accessLevel: AccessLevel.PUBLIC })
+export class SharedContextService {}
+```
+
+### Step 3: 通过 Inject 使用 Service
+
+#### 基本用法
+
+使用 `@Inject()` 注入其他 Proto 或 Egg 对象：
+
+```typescript
+import { Inject, Logger, SingletonProto } from 'egg';
+import { FooService } from './FooService.ts';
+
+@SingletonProto()
+export class HelloService {
+  @Inject()
+  fooService: FooService; // 注入另一个 Proto
+
+  @Inject()
+  logger: Logger; // 注入 Egg 对象
+
+  async hello(): Promise<string> {
+    this.logger.info(`[HelloService] ${this.fooService.hello()}`);
+  }
+}
+```
+
+#### 动态注入
+
+当同一个抽象有多种实现，需要在运行时动态选择时，通过 `EggObjectFactory` 按类型获取实现，无需 if/else。详见 `references/dynamic-inject.md`。
+
+#### 重要约束
+
+- **不能有循环依赖**：Proto 或模块之间都不能有循环依赖
+- **不能有同名对象**：一个模块不能有相同名称和初始化类型的 Proto
+- **按需注入**：不要直接注入 `app` 或 `ctx`，按需注入特定对象
+
+### 快速决策指南
+
+| 场景                             | 使用方式                                               |
+| -------------------------------- | ------------------------------------------------------ |
+| 无状态服务                       | `@SingletonProto()`                                    |
+| 跨服务共享的请求级状态           | `@ContextProto()`                                      |
+| 需要跨模块访问                   | `@SingletonProto({ accessLevel: AccessLevel.PUBLIC })` |
+| 注入依赖                         | `@Inject()`                                            |
+| 使用自定义名称注入               | `@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`。
+
+## 常见问题排查
+
+| 现象                   | 原因                                       | 解决方案                                     |
+| ---------------------- | ------------------------------------------ | -------------------------------------------- |
+| 模块没被加载           | `eggModule.name` 包含 `-` 等特殊字符       | 改为驼峰命名                                 |
+| `EggPrototypeNotFound` | 跨模块注入但 accessLevel 为 PRIVATE        | 改为 `AccessLevel.PUBLIC`                    |
+| 注入对象不对           | 类型为 `interface`/`any`，回退到属性名匹配 | 改用 class 类型或 `@Inject({ name: 'xxx' })` |
+| 混用注入方式报错       | 属性注入和构造函数注入不能混用             | 统一使用一种方式                             |
+| 可选依赖启动报错       | 缺少 optional 标记                         | `@Inject({ optional: true })`                |
+
+## 参考资料
+
+- 详细的 module 文档，请参阅：`references/module.md`
+- 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,223 @@
+# 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/dynamic-inject.md

@@ -0,0 +1,90 @@
+# 动态注入开发指南
+
+## 何时使用
+
+- **用动态注入**：同一抽象有多种实现，运行时按参数选择（如多种支付方式、多种存储后端）
+- **用普通 `@Inject()`**：依赖只有一个实现，编译时就能确定
+
+## Step 1: 定义抽象类和类型枚举
+
+```typescript
+// AbstractHello.ts
+export abstract class AbstractHello {
+  abstract hello(): string;
+}
+
+// HelloType.ts
+export enum HelloType {
+  FOO = 'FOO',
+  BAR = 'BAR',
+}
+```
+
+如果类型是无限扩展的，没有固定枚举，可以用 `Record<string, string>` 代替：
+
+```typescript
+type AnyEnum = Record<string, string>;
+```
+
+## Step 2: 创建自定义装饰器
+
+```typescript
+// decorator/Hello.ts
+import { ImplDecorator, QualifierImplDecoratorUtil } from 'egg';
+import { HelloType } from '../HelloType.ts';
+import { AbstractHello } from '../AbstractHello.ts';
+
+export const HELLO_ATTRIBUTE = Symbol('HELLO_ATTRIBUTE');
+
+export const Hello: ImplDecorator<AbstractHello, typeof HelloType> = QualifierImplDecoratorUtil.generatorDecorator(
+  AbstractHello,
+  HELLO_ATTRIBUTE,
+);
+```
+
+**注意事项：**
+
+- **ATTRIBUTE（Symbol）不要重复**，重复会导致实现被覆盖
+- **抽象类不要指定错**，否则可能导致实现被覆盖
+
+## Step 3: 实现抽象类
+
+每个实现加上 `@SingletonProto()`（或 `@ContextProto()`）和自定义装饰器：
+
+```typescript
+// impl/FooHello.ts
+import { SingletonProto } from 'egg';
+import { Hello } from '../decorator/Hello.ts';
+import { HelloType } from '../HelloType.ts';
+import { AbstractHello } from '../AbstractHello.ts';
+
+@SingletonProto()
+@Hello(HelloType.FOO)
+export class FooHello extends AbstractHello {
+  hello(): string {
+    return 'hello, foo';
+  }
+}
+```
+
+## Step 4: 动态获取实现
+
+通过 `EggObjectFactory` 在运行时按类型获取对应实现：
+
+```typescript
+// HelloService.ts
+import { EggObjectFactory, SingletonProto, Inject } from 'egg';
+import { HelloType } from './HelloType.ts';
+import { AbstractHello } from './AbstractHello.ts';
+
+@SingletonProto()
+export class HelloService {
+  @Inject()
+  private eggObjectFactory: EggObjectFactory;
+
+  async hello(type: HelloType): Promise<string> {
+    const helloImpl = await this.eggObjectFactory.getEggObject(AbstractHello, type);
+    return helloImpl.hello();
+  }
+}
+```