@eggjs/skills 0.0.0 → 4.1.2-beta.5

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

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/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@eggjs/skills",
-  "version": "0.0.0",
+  "version": "4.1.2-beta.5",
   "description": "agent skills for egg",
+  "keywords": [
+    "egg",
+    "skill"
+  ],
+  "homepage": "https://github.com/eggjs/egg/tree/next/packages/skills",
+  "bugs": {
+    "url": "https://github.com/eggjs/egg/issues"
+  },
   "license": "MIT",
   "author": "eggjs",
   "repository": {
@@ -9,7 +17,13 @@
     "url": "git+https://github.com/eggjs/egg.git",
     "directory": "packages/skills"
   },
+  "files": [
+    "**/*.md"
+  ],
   "publishConfig": {
     "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18.0"
   }
 }