@eggjs/skills 0.0.0 → 4.1.2-beta.11

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`。

package/egg-core/references/inject.md

@@ -0,0 +1,258 @@
+# Inject 开发指南
+
+## 基本用法
+
+使用 `@Inject()` 注入其他 Proto 对象或 Egg 内置对象：
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+@SingletonProto()
+export class OrderService {
+  @Inject()
+  userService: UserService; // 按类型自动匹配
+
+  @Inject({ name: 'customName' })
+  config: any; // 按名称匹配
+
+  @Inject('shorthand')
+  other: any; // 字符串简写，等同于 { name: 'shorthand' }
+}
+```
+
+## 名称解析规则
+
+框架按以下优先级确定注入目标：
+
+1. **显式指定 name** — `@Inject({ name: 'xxx' })` 或 `@Inject('xxx')`
+2. **类型元数据自动关联** — 当属性类型是使用了 `@SingletonProto()` 或 `@ContextProto()` 装饰器的 class 时，框架自动从类型元数据匹配对应的 Proto 对象。此时属性名可以任意取值，不影响注入结果
+3. **属性名兜底** — 当类型为 `interface`、`any`、`unknown` 等无法获取运行时元信息的类型时，使用属性名作为注入名称
+
+```typescript
+@SingletonProto()
+export class MyService {
+  @Inject()
+  fooService: FooService; // 优先级 2：从 FooService 类型自动关联
+
+  @Inject()
+  whatever: FooService; // 优先级 2：同样生效，属性名不影响匹配
+
+  @Inject({ name: 'bar' })
+  baz: FooService; // 优先级 1：显式 name → "bar"
+
+  @Inject()
+  something: any; // 优先级 3：类型无元数据，回退到属性名 → "something"
+}
+```
+
+## 可选注入
+
+默认情况下，注入目标不存在会在启动时报错。使用 `optional` 可以跳过不存在的依赖：
+
+```typescript
+import { SingletonProto, Inject, InjectOptional } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  @Inject({ optional: true })
+  maybeService?: SomeService; // 不存在时为 undefined
+
+  @InjectOptional()
+  anotherOptional?: OtherService; // 简写方式，效果相同
+}
+```
+
+## 构造函数注入
+
+除了属性注入，也支持构造函数参数注入：
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  constructor(
+    @Inject() readonly fooService: FooService,
+    @Inject({ optional: true }) readonly barService?: BarService,
+  ) {}
+}
+```
+
+**注意：构造函数注入和属性注入不能混用。** 一个 class 只能选择其中一种方式，否则框架会报错。
+
+## 注入 Egg 内置对象
+
+框架会自动遍历 `Application` 和 `Context` 对象的所有属性，均可通过 `@Inject()` 注入。
+
+#### 注入配置
+
+```typescript
+import { Inject, SingletonProto, EggAppConfig } from 'egg';
+
+@SingletonProto()
+class Foo {
+  @Inject()
+  config: EggAppConfig;
+
+  bar(): void {
+    console.log('current env is %s', this.config.env);
+  }
+}
+```
+
+#### 注入 Logger
+
+专为 logger 做了优化，可以直接注入 custom logger：
+
+```typescript
+import { Inject, SingletonProto, Logger } from 'egg';
+
+@SingletonProto()
+class FooService {
+  @Inject()
+  logger: Logger; // 注入 ${appname}-web.log
+
+  @Inject()
+  coreLogger: Logger; // 注入 egg-web.log
+
+  @Inject()
+  fooLogger: Logger; // 注入 customLogger 中配置的 fooLogger
+}
+```
+
+#### 注入 Service
+
+> 强烈建议把 Egg Service 的代码通过 Proto 重新封装再注入。对于已有的 Service，可以通过以下方式引入：
+
+```typescript
+import { Service, Inject, SingletonProto } from 'egg';
+
+@SingletonProto()
+class FooService {
+  @Inject()
+  service: Service; // 注入整个 ctx.service
+
+  get xxxService() {
+    return this.service.xxxService;
+  }
+}
+```
+
+#### 注入 HttpClient
+
+```typescript
+import { Inject, SingletonProto, HttpClient } from 'egg';
+
+@SingletonProto()
+class Foo {
+  @Inject()
+  httpClient: HttpClient;
+
+  async bar(): Promise<void> {
+    await this.httpClient.request('https://example.com');
+  }
+}
+```
+
+## 注入模块配置
+
+在模块根目录创建 `module.yml`，通过 `moduleConfig` 名称注入，框架自动注入当前模块的配置：
+
+```yaml
+# module.yml
+apiEndpoint: https://api.example.com
+retryCount: 3
+```
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+interface ModuleConfig {
+  apiEndpoint: string;
+  retryCount: number;
+}
+
+@SingletonProto()
+export class ApiService {
+  @Inject()
+  moduleConfig: ModuleConfig;
+
+  async call(): Promise<void> {
+    // this.moduleConfig.apiEndpoint → "https://api.example.com"
+  }
+}
+```
+
+如需注入其他模块的配置，使用 `@ConfigSourceQualifier` 指定模块名：
+
+```typescript
+import { SingletonProto, Inject, ConfigSourceQualifier } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  @Inject()
+  @ConfigSourceQualifier('otherModule')
+  moduleConfig: OtherModuleConfig; // 注入 otherModule 的配置
+}
+```
+
+## Qualifier 限定符
+
+当同名对象存在多个实现时，使用限定符消歧义：
+
+### @InitTypeQualifier
+
+指定注入 Singleton 还是 Context 实例：
+
+```typescript
+import { SingletonProto, Inject, InitTypeQualifier, ObjectInitType } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  @Inject()
+  @InitTypeQualifier(ObjectInitType.CONTEXT)
+  barService: BarService; // 强制注入 ContextProto 版本
+}
+```
+
+> 大多数情况下不需要手动指定，框架会根据类型元数据自动推导。
+
+### @EggQualifier
+
+当 `app` 和 `ctx` 上存在同名属性时，框架默认优先匹配 `ctx`。使用 `@EggQualifier` 显式指定来源：
+
+```typescript
+import { SingletonProto, Inject, EggQualifier, EggType } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  @Inject()
+  @EggQualifier(EggType.APP)
+  someProp: any; // 强制从 app 注入
+
+  @Inject()
+  @EggQualifier(EggType.CONTEXT)
+  someProp2: any; // 强制从 ctx 注入
+}
+```
+
+### @ModuleQualifier
+
+指定从哪个模块注入：
+
+```typescript
+import { SingletonProto, Inject, ModuleQualifier } from 'egg';
+
+@SingletonProto()
+export class MyService {
+  @Inject()
+  @ModuleQualifier('userModule')
+  userService: UserService; // 明确从 userModule 注入
+}
+```
+
+## 重要约束
+
+- **不能有循环依赖**：Proto 之间或模块之间都不能形成循环引用
+- **不能有同名对象**：同一模块内不能存在相同名称和相同初始化类型的 Proto
+- **按需注入**：不要直接注入 `app` 或 `ctx`，按需注入具体的属性（如 `logger`、`config`）

package/egg-core/references/module.md

@@ -0,0 +1,202 @@
+# module 开发指南
+
+## 创建 module
+
+在 `app` 目录中，创建 module 目录，并在该目录中添加 `package.json`。
+
+```json
+{
+  "name": "moduleName",
+  "eggModule": {
+    "name": "moduleName"
+  }
+}
+```
+
+**重要提示**：
+
+- 模块名称不能包含 `-` 或其他特殊字符；使用驼峰命名规则。
+- module 的 `package.json` 文件中，仅包含 `name` 以及 `eggModule.name` 字段，不应该有其他额外内容。
+
+## module 发现机制
+
+框架支持两种模式：自动扫描（默认）和手动声明。两者互斥，当 `config/module.json` 存在时，自动扫描完全禁用。
+
+### 模式一：自动扫描（默认）
+
+当 `config/module.json` **不存在**时，框架通过以下两种方式发现模块：
+
+**1. 目录扫描**
+
+从项目根目录开始扫描，查找含有 `eggModule.name` 的 `package.json`。
+
+- 默认扫描深度：10 层
+- 自动排除：隐藏目录（`.` 开头）、`node_modules/`、`coverage/`
+
+可通过应用配置调整扫描深度和排除路径：
+
+```typescript
+// config/config.default.ts
+export default {
+  tegg: {
+    readModuleOptions: {
+      deep: 5, // 默认 10
+      extraFilePattern: ['!**/dist'], // 额外排除 dist 目录
+    },
+  },
+};
+```
+
+`extraFilePattern` 使用 [globby](https://github.com/sindresorhus/globby) 语法，以 `!` 开头表示排除。
+
+```
+app/
+├── fooModule/          ✅ 被扫描到
+│   └── package.json    { "eggModule": { "name": "fooModule" } }
+├── barModule/          ✅ 被扫描到
+│   └── package.json    { "eggModule": { "name": "barModule" } }
+├── .hidden/            ❌ 隐藏目录，自动排除
+│   └── package.json
+└── common/             ❌ 无 package.json，不会加载
+    └── utils.ts
+```
+
+**2. npm 包扫描**
+
+框架会遍历项目 `package.json` 中 `dependencies` 的每个包（不含 `devDependencies`），检查其 `package.json` 是否含有 `eggModule.name`，如果有则自动作为模块加载。
+
+### 模式二：手动声明
+
+创建 `config/module.json` 后，自动扫描**完全禁用**，仅加载文件中声明的模块：
+
+```json
+[
+  { "path": "../app/module-a" }, // 相对于 config 目录的路径
+  { "package": "@eggjs/common-module" } // npm 包名
+]
+```
+
+## module 配置
+
+在模块根目录创建 `module.yml` 存放模块专属配置：
+
+```
+app/
+└── userModule/
+    ├── package.json
+    ├── module.yml          # 基础配置
+    ├── module.unittest.yml # 环境特定配置（可选）
+    └── UserService.ts
+```
+
+### 配置文件格式
+
+支持 YAML 和 JSON 两种格式，优先加载 YAML：
+
+```yaml
+# module.yml
+features:
+  dynamic:
+    foo: bar
+```
+
+### 环境配置合并
+
+框架会按 `module.yml` → `module.{env}.yml` 的顺序深度合并：
+
+```yaml
+# module.yml
+features:
+  dynamic:
+    foo: bar
+
+# module.unittest.yml
+features:
+  dynamic:
+    testMode: true
+```
+
+unittest 环境下合并结果：
+
+```json
+{
+  "features": {
+    "dynamic": {
+      "foo": "bar",
+      "testMode": true
+    }
+  }
+}
+```
+
+### 注入配置
+
+通过 `@Inject()` 注入 `moduleConfig`，框架自动注入当前模块的配置：
+
+```typescript
+import { SingletonProto, Inject } from 'egg';
+
+interface ModuleConfig {
+  features: {
+    dynamic: {
+      foo: string;
+    };
+  };
+}
+
+@SingletonProto()
+export class UserService {
+  @Inject()
+  moduleConfig: ModuleConfig;
+
+  async getFeatureFlag(): Promise<string> {
+    return this.moduleConfig.features.dynamic.foo; // 'bar'
+  }
+}
+```
+
+## module 目录组织
+
+### 新应用
+
+直接在 `app/` 目录下平铺 module。可按功能划分，也可按业务划分：
+
+**按功能划分：**
+
+```
+app/
+├── authModule/
+│   └── package.json
+├── logModule/
+│   └── package.json
+└── storageModule/
+    └── package.json
+```
+
+**按业务划分：**
+
+```
+app/
+├── userModule/
+│   └── package.json
+├── orderModule/
+│   └── package.json
+└── paymentModule/
+    └── package.json
+```
+
+### 存量应用（包含老的 egg 写法）
+
+保留原有 `app/controller`、`app/service` 等目录不动，将新增的 module 统一放在 `app/module/` 下：
+
+```
+app/
+├── controller/           # 老的 egg 代码，保持不变
+├── service/
+├── module/               # 新增 module 统一放这里
+│   ├── userModule/
+│   │   └── package.json
+│   └── orderModule/
+│       └── package.json
+└── router.ts
+```