@eggjs/skills 0.0.0 → 4.1.2-beta.10

package/egg-core/references/proto.md

@@ -0,0 +1,181 @@
+# Proto 开发指南
+
+## SingletonProto vs ContextProto
+
+|          | SingletonProto     | ContextProto       |
+| -------- | ------------------ | ------------------ |
+| 创建时机 | 应用启动时立即创建 | 请求到达时按需创建 |
+| 实例数量 | 整个应用 1 个      | 每个请求 1 个      |
+| 销毁时机 | 应用关闭           | 请求结束           |
+
+**决策逻辑：默认使用 `@SingletonProto()`**，性能更好。只有当需要在多个服务间共享请求级隔离状态时，才使用 `@ContextProto()`。
+
+```typescript
+import { SingletonProto, ContextProto } from 'egg';
+
+// ✅ 默认选择：无状态服务用 SingletonProto
+@SingletonProto()
+export class UserService {
+  async findUser(id: string): Promise<User> {
+    // 无需请求级状态，适合 Singleton
+  }
+}
+
+// 仅在需要请求级隔离时使用 ContextProto
+@ContextProto()
+export class RequestContext {
+  traceId: string;
+  userId: string;
+  // 每个请求独立的状态
+}
+```
+
+## 装饰器参数
+
+`@SingletonProto()` 和 `@ContextProto()` 接受相同的可选参数：
+
+| 参数          | 类型        | 默认值         | 说明                                 |
+| ------------- | ----------- | -------------- | ------------------------------------ |
+| name          | string      | 类名首字母小写 | 实例名称                             |
+| accessLevel   | AccessLevel | PRIVATE        | 跨模块可见性                         |
+| protoImplType | string      | 'DEFAULT'      | 实现类型标记（高级用法，一般不需要） |
+
+名称推导规则：类名首字母自动转小写，如 `MyService` → `myService`。
+
+```typescript
+import { SingletonProto, AccessLevel } from 'egg';
+
+// 使用默认参数：name 为 "helloService"，accessLevel 为 PRIVATE
+@SingletonProto()
+export class HelloService {}
+
+// 自定义参数
+@SingletonProto({
+  name: 'customName',
+  accessLevel: AccessLevel.PUBLIC,
+})
+export class HelloService {}
+```
+
+## 注入规则
+
+**SingletonProto 可以注入 ContextProto**，框架会自动处理生命周期差异。
+
+实现机制：框架不会直接注入 ContextProto 实例，而是通过 lazy getter/Proxy，在每次访问时从当前请求上下文动态解析，确保每个请求拿到各自的实例。
+
+```typescript
+import { SingletonProto, ContextProto, Inject } from 'egg';
+
+@ContextProto()
+export class RequestContext {
+  userId: string;
+}
+
+@SingletonProto()
+export class AppService {
+  @Inject()
+  requestContext: RequestContext; // ✅ 每次访问自动解析当前请求的实例
+}
+```
+
+ContextProto 也可以注入 SingletonProto：
+
+```typescript
+@ContextProto()
+export class RequestHandler {
+  @Inject()
+  appService: AppService; // ✅ 直接注入
+}
+```
+
+## AccessLevel 跨模块访问
+
+- `AccessLevel.PRIVATE`（默认）：仅同模块内可注入
+- `AccessLevel.PUBLIC`：跨模块可注入
+
+模块边界由 `package.json` 中的 `eggModule.name` 决定。
+
+```typescript
+// userModule 中
+@SingletonProto({ accessLevel: AccessLevel.PUBLIC })
+export class UserService {}
+
+// orderModule 中
+@SingletonProto()
+export class OrderService {
+  @Inject()
+  userService: UserService; // ✅ UserService 是 PUBLIC，跨模块可注入
+}
+```
+
+```typescript
+// userModule 中
+@SingletonProto() // 默认 PRIVATE
+export class UserHelper {}
+
+// orderModule 中
+@SingletonProto()
+export class OrderService {
+  @Inject()
+  userHelper: UserHelper; // ❌ 报错：UserHelper 是 PRIVATE，不能跨模块注入
+}
+```
+
+## 生命周期
+
+Proto 对象支持以下生命周期钩子，按执行顺序排列：
+
+| 阶段 | 装饰器                      | 说明                             |
+| ---- | --------------------------- | -------------------------------- |
+| 1    | constructor                 | 构造函数                         |
+| 2    | `@LifecyclePostConstruct()` | 构造完成后                       |
+| 3    | `@LifecyclePreInject()`     | 注入前                           |
+| 4    | —                           | 依赖注入                         |
+| 5    | `@LifecyclePostInject()`    | 注入完成后                       |
+| 6    | `@LifecycleInit()`          | 异步初始化（对象就绪前最后一步） |
+| 7    | —                           | **对象就绪，可被使用**           |
+| 8    | `@LifecyclePreDestroy()`    | 销毁前                           |
+| 9    | `@LifecycleDestroy()`       | 销毁，用于清理资源               |
+
+常用的是 `@LifecycleInit()` 和 `@LifecycleDestroy()`。
+
+**示例 1：SingletonProto 异步初始化和资源清理**
+
+```typescript
+import { SingletonProto, LifecycleInit, LifecycleDestroy } from 'egg';
+
+@SingletonProto()
+export class DatabaseService {
+  private connection: Connection;
+
+  @LifecycleInit()
+  async init(): Promise<void> {
+    this.connection = await createConnection();
+  }
+
+  @LifecycleDestroy()
+  async destroy(): Promise<void> {
+    await this.connection.close();
+  }
+}
+```
+
+**示例 2：ContextProto 在注入完成后初始化状态**
+
+```typescript
+import { ContextProto, Inject, LifecyclePostInject } from 'egg';
+
+@ContextProto()
+export class RequestTracer {
+  @Inject()
+  traceService: TraceService;
+
+  traceId: string;
+
+  @LifecyclePostInject()
+  async postInject(): Promise<void> {
+    // 依赖注入完成后，利用注入的服务初始化状态
+    this.traceId = await this.traceService.generateTraceId();
+  }
+}
+```

package/egg-unittest/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: egg-unittest
+description: 本技能用于编写 EGG 应用的单元测试。覆盖 HTTP 接口测试、Service/DI 对象测试、Mock 数据模拟、BackgroundTask 和 EventBus 测试。使用 @eggjs/mock、app.httpRequest()、app.getEggObject()、mm() 等 API。
+allowed-tools: Read
+---
+
+# EGG 单元测试
+
+---
+
+## 原理
+
+`egg-bin test` 使用 Vitest 运行测试，自动完成以下工作：
+
+- 以当前项目目录为 baseDir，创建并启动一个 MockApplication 实例（即 `app`）
+- 注入 `@eggjs/mock/setup_vitest` 管理 app 生命周期（`beforeAll` 启动 app、`afterEach` 恢复 mock、`afterAll` 关闭 app）
+- 注入 Vitest 全局变量（`describe`、`it`、`beforeAll` 等），无需手动 import
+  测试代码中通过 `import { app, mm } from '@eggjs/mock/bootstrap'` 获取已启动的 app 实例和 mock 工具，直接使用即可。
+
+---
+
+## 配置检查
+
+确保项目中有以下配置：
+
+**package.json：**
+
+```json
+{
+  "scripts": {
+    "test": "egg-bin test"
+  },
+  "devDependencies": {
+    "@eggjs/bin": "^8",
+    "@eggjs/mock": "^8"
+  }
+}
+```
+
+**测试文件约定：**
+
+- 测试目录：`test/`
+- 文件命名：`*.test.ts`
+
+**自定义 setup 文件（可选）：**
+
+如果存在 `test/.setup.ts`，egg-bin 会自动将其加入 vitest setupFiles，在 `@eggjs/mock/setup_vitest` 之前执行（即 app 启动之前）。可用于设置环境变量等全局初始化：
+
+```typescript
+// test/.setup.ts
+beforeAll(() => {
+  process.env.SOME_CONFIG = 'test-value';
+});
+```
+
+---
+
+## 简单示例
+
+### HTTP 接口测试
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('test/controller/home.test.ts', () => {
+  it('should GET /', () => {
+    return app.httpRequest().get('/').expect(200).expect('hello world');
+  });
+});
+```
+
+### Service 测试
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { UserService } from '../app/modules/user/UserService.ts';
+
+describe('test/service/user.test.ts', () => {
+  it('should get user', async () => {
+    const userService = await app.getEggObject(UserService);
+    const user = await userService.getById('1');
+    assert(user);
+    assert.equal(user.name, 'test');
+  });
+});
+```
+
+---
+
+## 测试场景决策树
+
+```
+要测什么？
+
+1. HTTP 接口（GET/POST/PUT/DELETE）？
+   → 参考 references/http-test.md
+
+2. Service / DI 对象的方法？
+   → 参考 references/service-test.md
+
+3. 需要 mock 外部依赖？（HTTP 调用、Service 方法、Session、CSRF）
+   → 参考 references/mock.md
+
+4. BackgroundTaskHelper（后台异步任务）？
+   → 参考 references/background-task-test.md
+
+5. EventBus（事件驱动）？
+   → 参考 references/eventbus-test.md
+```
+
+---
+
+## 快速参考
+
+| API                                                  | 说明                                    |
+| ---------------------------------------------------- | --------------------------------------- |
+| `import { app, mm } from '@eggjs/mock/bootstrap'`    | 标准测试入口                            |
+| `app.httpRequest().get('/path').expect(200)`         | HTTP 接口测试                           |
+| `app.getEggObject(Class)`                            | 获取 SingletonProto / ContextProto 实例 |
+| `app.mockModuleContextScope(async (ctx) => { ... })` | ContextProto 测试作用域                 |
+| `mm(Class.prototype, 'method', fn)`                  | Mock Proto 方法                         |
+| `app.mockCsrf()`                                     | 跳过 CSRF 校验（POST 测试必备）         |
+| `app.mockHttpclient(url, data)`                      | Mock 外部 HTTP 调用                     |
+| `app.getEventWaiter()`                               | 获取 EventBus 事件等待器                |
+
+---
+
+## 常见错误
+
+| 错误写法                           | 正确写法                                      | 说明                        |
+| ---------------------------------- | --------------------------------------------- | --------------------------- |
+| `import { app } from 'egg'`        | `import { app } from '@eggjs/mock/bootstrap'` | 测试使用 mock 包            |
+| `before()` / `after()`             | `beforeAll()` / `afterAll()`                  | Vitest 钩子，不是 Mocha     |
+| POST 测试报 403                    | 加 `app.mockCsrf()`                           | 安全插件默认开启 CSRF       |
+| 手动写 `afterEach(mm.restore)`     | 不需要                                        | egg-bin 自动注入 mock 恢复  |
+| 代码写在 describe 内、hooks 外     | 放入 `beforeAll` / `beforeEach`               | describe 体在加载阶段就执行 |
+| `await app.ready()` 配合 bootstrap | 不需要                                        | bootstrap 自动处理生命周期  |
+
+---
+
+## 参考资料
+
+- `references/http-test.md` — HTTP 接口测试
+- `references/service-test.md` — Service/DI 对象测试
+- `references/mock.md` — Mock 模式
+- `references/background-task-test.md` — BackgroundTaskHelper 测试
+- `references/eventbus-test.md` — EventBus 测试

package/egg-unittest/references/background-task-test.md

@@ -0,0 +1,53 @@
+# BackgroundTaskHelper 测试
+
+## 常见错误
+
+| 错误写法                                           | 正确写法                                                                              | 说明                                                 |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| 不等待就断言                                       | 用 `mockModuleContextScope`（自动等待）或 `app.backgroundTasksFinished()`（手动等待） | 后台任务异步执行，必须等待完成后再断言               |
+| 在 `mockModuleContextScope` 回调内断言后台任务结果 | 在 `mockModuleContextScope` 返回后断言                                                | 回调内任务尚未完成，返回后才会等待完成               |
+| 用 `TimerUtil.sleep` 等待                          | 用 `app.backgroundTasksFinished()`                                                    | sleep 时间不确定，`backgroundTasksFinished` 精确等待 |
+
+---
+
+## 使用 mockModuleContextScope
+
+`mockModuleContextScope` 退出时会自动等待所有后台任务完成（内部触发 `doPreDestroy`），scope 退出后直接断言即可：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { CountService } from '../app/modules/count/CountService.ts';
+
+it('should complete background task', async () => {
+  await app.mockModuleContextScope(async (ctx) => {
+    const countService = await ctx.getEggObject(CountService);
+    // countService 内部通过 backgroundTaskHelper.run() 触发后台任务
+    await countService.doSomething();
+  });
+
+  // scope 退出后，后台任务已完成，直接断言
+  const countService = await app.getEggObject(CountService);
+  assert.equal(countService.count, 1);
+});
+```
+
+## 使用 backgroundTasksFinished
+
+不通过 `mockModuleContextScope` 触发的场景（如 HTTP 接口测试），scope 退出的自动等待机制不适用，需要手动调用 `app.backgroundTasksFinished()` 等待所有后台任务完成后，再做断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+import { CountService } from '../app/modules/count/CountService.ts';
+
+it('should complete background task', async () => {
+  await app.httpRequest().get('/api/trigger-task').expect(200);
+
+  // 等待后台任务完成
+  await app.backgroundTasksFinished();
+
+  const countService = await app.getEggObject(CountService);
+  assert.equal(countService.count, 1);
+});
+```

package/egg-unittest/references/eventbus-test.md

@@ -0,0 +1,47 @@
+# EventBus 测试
+
+## 常见错误
+
+| 错误写法                         | 正确写法                                           | 说明                                         |
+| -------------------------------- | -------------------------------------------------- | -------------------------------------------- |
+| 先 emit 再 `eventWaiter.await()` | 先 `eventWaiter.await()` 再触发业务逻辑            | await 注册监听器，必须在事件发出前           |
+| 不等待事件处理完成就断言         | 使用 `eventWaiter.await('eventName')` 等待后再断言 | handler 异步执行，不等待则断言时可能尚未完成 |
+
+---
+
+## 基本测试模式
+
+使用 `app.getEventWaiter()` 等待事件被处理完成：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { HelloService } from '../app/modules/hello/HelloService.ts';
+import { HelloHandler } from '../app/modules/hello/HelloHandler.ts';
+
+describe('EventBus', () => {
+  it('should handle event', async () => {
+    // mock handler 捕获调用参数
+    const mockFn = async (msg: string) => {};
+    mm(HelloHandler.prototype, 'handle', mockFn);
+
+    await app.mockModuleContextScope(async (ctx) => {
+      const helloService = await ctx.getEggObject(HelloService);
+      const eventWaiter = await app.getEventWaiter();
+
+      // 1. 先注册等待（必须在 emit 之前）
+      const eventPromise = eventWaiter.await('helloEgg');
+
+      // 2. 触发业务逻辑（内部会 emit 事件）
+      helloService.hello();
+
+      // 3. 等待 handler 执行完成
+      await eventPromise;
+    });
+
+    // 4. 验证 handler 被调用及参数
+    assert.equal(mockFn.called, 1);
+    assert.deepStrictEqual(mockFn.lastCalledArguments, ['hello']);
+  });
+});
+```

package/egg-unittest/references/http-test.md

@@ -0,0 +1,145 @@
+# HTTP 接口测试
+
+## 常见错误
+
+| 错误写法                                                 | 正确写法                        | 说明                                          |
+| -------------------------------------------------------- | ------------------------------- | --------------------------------------------- |
+| POST 测试不加 `app.mockCsrf()`                           | 在 POST 前调用 `app.mockCsrf()` | 安全插件默认开启 CSRF，不 mock 会返回 403     |
+| `app.httpRequest().get('/').expect(200)` 不 return/await | 必须 `return` 或 `await`        | 否则断言不会执行，测试永远通过                |
+| `.expect({ foo: 'bar' })` 用于部分匹配                   | 使用 `result.body` 手动断言     | `.expect(body)` 是全量匹配（deepStrictEqual） |
+
+---
+
+## 基本用法
+
+通过 `app.httpRequest()` 发起 HTTP 请求，返回 SuperTest 对象：
+
+```typescript
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('UserController', () => {
+  it('should GET /api/users', () => {
+    return app.httpRequest().get('/api/users').expect(200).expect({ users: [] });
+  });
+});
+```
+
+---
+
+## POST 请求 + CSRF
+
+POST/PUT/DELETE 请求需要先调用 `app.mockCsrf()` 跳过 CSRF 校验：
+
+```typescript
+it('should POST /api/users', () => {
+  app.mockCsrf();
+  return app
+    .httpRequest()
+    .post('/api/users')
+    .send({ name: 'test', email: 'test@example.com' })
+    .expect(200)
+    .expect({ id: '1', name: 'test' });
+});
+```
+
+表单提交使用 `.type('form')`：
+
+```typescript
+it('should POST form data', () => {
+  app.mockCsrf();
+  return app.httpRequest().post('/api/login').type('form').send({ username: 'admin', password: '123' }).expect(200);
+});
+```
+
+---
+
+## 请求构造
+
+```typescript
+app
+  .httpRequest()
+  .get('/api/users')
+  .set('Authorization', 'Bearer token123') // 设置 header
+  .set('Accept', 'application/json') // 设置 Accept
+  .query({ page: 1, limit: 10 }) // 查询参数
+  .expect(200);
+```
+
+---
+
+## 响应断言
+
+使用 `.expect()` 链式断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+it('should validate response', () => {
+  return app
+    .httpRequest()
+    .get('/api/users/1')
+    .expect(200) // 只校验状态码
+    .expect({ id: '1', name: 'test' }) // 只校验 body（deepStrictEqual）
+    .expect(200, { id: '1', name: 'test' }) // 状态码 + body 合并
+    .expect('hello world') // body 字符串匹配
+    .expect(/hello/) // body 正则匹配
+    .expect('content-type', /json/) // header 匹配
+    .expect([200, 302]) // 多状态码匹配（任一即可）
+    .expect((res) => {
+      // 自定义断言函数
+      assert(res.body.id);
+    });
+});
+```
+
+使用 `result` 做更灵活的断言：
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+it('should validate response', async () => {
+  const result = await app.httpRequest().get('/api/users/1');
+
+  assert.equal(result.status, 200);
+  assert.equal(result.body.name, 'test');
+  assert(result.body.id);
+  assert.match(result.headers['content-type'], /json/);
+});
+```
+
+完整的请求构造和断言 API 可查看项目 node_modules 中 `@eggjs/supertest` 的类型定义。
+
+---
+
+## 端到端示例
+
+```typescript
+import assert from 'node:assert';
+import { app } from '@eggjs/mock/bootstrap';
+
+describe('test/controller/user.test.ts', () => {
+  describe('GET /api/users/:id', () => {
+    it('should return user', () => {
+      return app.httpRequest().get('/api/users/1').expect(200).expect({ id: '1', name: 'test' });
+    });
+
+    it('should return 404 when user not found', () => {
+      return app.httpRequest().get('/api/users/999').expect(404);
+    });
+  });
+
+  describe('POST /api/users', () => {
+    it('should create user', () => {
+      app.mockCsrf();
+      return app.httpRequest().post('/api/users').send({ name: 'new user', email: 'new@example.com' }).expect(201);
+    });
+
+    it('should return 422 with invalid params', () => {
+      app.mockCsrf();
+      return app.httpRequest().post('/api/users').send({ name: '' }).expect(422);
+    });
+  });
+});
+```

package/egg-unittest/references/mock.md

@@ -0,0 +1,108 @@
+# Mock 模式
+
+## 常见错误
+
+| 错误写法                       | 正确写法                                   | 说明                           |
+| ------------------------------ | ------------------------------------------ | ------------------------------ |
+| `mm(service, 'method', fn)`    | `mm(ServiceClass.prototype, 'method', fn)` | DI 对象需 mock 原型，不是实例  |
+| 手动写 `afterEach(mm.restore)` | 不需要                                     | egg-bin 自动注入 mock 恢复     |
+| `new Ajv()` mock 单独实例      | mock 原型方法                              | DI 容器管理的对象通过原型 mock |
+
+---
+
+## mm() — Mock Proto 方法
+
+最常用的 mock 方式，mock DI 对象的原型方法：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { UserService } from '../app/modules/user/UserService.ts';
+import { OrderService } from '../app/modules/order/OrderService.ts';
+
+describe('OrderService', () => {
+  it('should mock user service', async () => {
+    mm(UserService.prototype, 'getById', async () => {
+      return { id: '1', name: 'mocked user' };
+    });
+
+    const orderService = await app.getEggObject(OrderService);
+    const result = await orderService.createForUser('1');
+    assert.equal(result.userName, 'mocked user');
+  });
+});
+```
+
+mock 函数会自动记录调用信息，可以用来断言调用参数：
+
+```typescript
+import assert from 'node:assert';
+import { app, mm } from '@eggjs/mock/bootstrap';
+import { NotifyService } from '../app/modules/notify/NotifyService.ts';
+import { OrderService } from '../app/modules/order/OrderService.ts';
+
+it('should call notify with correct args', async () => {
+  const mockFn = async (userId: string, message: string) => {};
+  mm(NotifyService.prototype, 'send', mockFn);
+
+  const orderService = await app.getEggObject(OrderService);
+  await orderService.create({ productId: '1' });
+
+  assert.equal(mockFn.called, 1); // 调用次数
+  assert.deepStrictEqual(mockFn.lastCalledArguments, ['user-1', '订单创建成功']); // 最后一次调用参数
+  // mockFn.calledArguments — 所有调用参数的数组
+});
+```
+
+---
+
+## mm.spy() — 不替换实现，只记录调用
+
+```typescript
+it('should spy on method', async () => {
+  mm.spy(NotifyService.prototype, 'send');
+
+  const orderService = await app.getEggObject(OrderService);
+  await orderService.create({ productId: '1' });
+
+  // 原方法正常执行，同时记录了调用信息
+  const sendFn = NotifyService.prototype.send;
+  assert.equal(sendFn.called, 1);
+  assert.equal(sendFn.lastCalledArguments[0], 'user-1');
+});
+```
+
+---
+
+## app.mockHttpclient() — Mock HttpClient 请求
+
+Mock 通过 `@Inject() httpclient: HttpClient` 注入的 HttpClient 发送的请求：
+
+```typescript
+it('should mock external API', () => {
+  app.mockHttpclient('https://api.example.com/users', {
+    data: JSON.stringify({ name: 'test' }),
+  });
+
+  return app.httpRequest().get('/api/proxy/users').expect(200).expect({ name: 'test' });
+});
+```
+
+---
+
+## app.mockCsrf() — 跳过 CSRF
+
+POST/PUT/DELETE 测试时跳过 CSRF 校验：
+
+```typescript
+it('should POST without CSRF error', () => {
+  app.mockCsrf();
+  return app.httpRequest().post('/api/users').send({ name: 'test' }).expect(200);
+});
+```
+
+---
+
+## Mock 恢复
+
+egg-bin 自动注入 `@eggjs/mock/setup_vitest`，会在 `afterEach` 钩子中自动调用 `mm.restore()`，无需手动编写。