@linyjs/plugin-docs 0.0.13 → 0.0.15

package/docs/guides/dependency-injection.md

@@ -0,0 +1,574 @@
+# 依赖注入机制
+
+本指南详细说明 linyjs 框架的依赖注入（DI）机制，包括服务定义、依赖声明、构造函数约定以及跨模块引用规则。
+
+> ⚠️ **最关键的规则**：服务类的构造函数**必须使用解构赋值**接收依赖。框架传入的是一个 `{ serviceTag: instance }` 对象，而非单个服务实例。详见 [构造函数约定](#构造函数约定)。
+
+## 概述
+
+linyjs 采用**构造函数注入**模式。框架在实例化服务时：
+
+1. 读取 `IServiceDef.dependencies` 数组
+2. 按依赖引用格式解析出对应的服务实例
+3. 组装为一个 `{ [serviceTag]: instance }` 对象
+4. 将该对象作为**唯一参数**传入服务类的构造函数
+
+```
+┌─────────────────────────────────────────────────────┐
+│  IServiceDef                                        │
+│  ┌───────────────────────────────────────────┐      │
+│  │ serviceTag: 'articleController'           │      │
+│  │ serviceImpl: ArticleController            │      │
+│  │ dependencies: ['mdb.mongoDBService']      │      │
+│  │ meta: { usageType: 'controller' }         │      │
+│  └───────────────────────────────────────────┘      │
+│                         │                           │
+│         ┌───────────────┼───────────────┐           │
+│         ▼               ▼               ▼           │
+│  框架解析依赖    查找服务实例    组装 depsRecord     │
+│                                                   │
+│         depsRecord = {                             │
+│           mongoDBService: <MongoDBService 实例>    │
+│         }                                          │
+│                         │                           │
+│                         ▼                           │
+│     new ArticleController(depsRecord)              │
+│     // 构造函数内部解构取值                          │
+└─────────────────────────────────────────────────────┘
+```
+
+## 核心概念
+
+### IServiceDef — 服务定义
+
+每个服务通过 `IServiceDef` 对象声明：
+
+```typescript
+import type { IServiceDef } from '@linyjs/server-module-interface';
+
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',           // 服务唯一标识（模块内唯一）
+  serviceImpl: MyService,            // 服务实现（class 或 factory function）
+  dependencies: ['otherService'],    // 依赖的其他服务（可选）
+  meta: { usageType: 'normal_service' }  // 元数据
+};
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `serviceTag` | `string` | ✅ | 服务的唯一标识，模块内唯一 |
+| `serviceImpl` | `class \| function` | ✅ | 服务实现，可以是类（constructor）或工厂函数 |
+| `dependencies` | `string[]` | ❌ | 依赖的服务引用列表，支持模块内和跨模块格式 |
+| `meta` | `Record<string, any>` | ❌ | 元数据，`usageType` 字段决定服务用途 |
+
+### IModule — 模块定义
+
+一个模块包含多个 `IServiceDef`：
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+export const myServerModule: IModule = {
+  name: 'myServer',                  // 模块名称（全局唯一）
+  moduleDependencies: ['mdb'],       // 依赖的其他模块（可选）
+  serviceDefs: [                     // 服务定义列表
+    serviceDef,
+    controllerDef,
+    // ...
+  ]
+};
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | ✅ | 模块名称，全局唯一，跨模块依赖引用时使用 |
+| `moduleDependencies` | `string[]` | ❌ | 依赖的模块名称列表 |
+| `serviceDefs` | `IServiceDef[]` | ✅ | 服务定义列表，顺序决定了实例化的先后 |
+
+### meta.usageType — 服务用途
+
+`meta.usageType` 决定了框架如何处理实例化后的服务：
+
+| usageType | 说明 | 框架行为 |
+|-----------|------|----------|
+| `'controller'` | 控制器 | 自动调用 `getRoutes()` 注册路由 |
+| `'middleware'` | 中间件 | 自动调用 `getMiddlewares()` 注册中间件 |
+| `'cron'` | 定时任务 | 自动调用 `getCronJobs()` 注册定时任务 |
+| `'normal_service'` | 普通服务 | 注册到服务池，供其他模块通过依赖注入使用 |
+
+> 💡 `normal_service` 类型的服务不会自动注册路由等，但它会被注册到 `moduleName.serviceTag` 下，供其他模块依赖。
+
+## 依赖声明
+
+### 依赖引用格式
+
+`dependencies` 数组中的每个字符串代表一个服务引用，支持两种格式：
+
+| 格式 | 示例 | 说明 | 查找范围 |
+|------|------|------|----------|
+| 模块内引用 | `'myService'` | 不含 `.` | 当前模块的已实例化服务 |
+| 跨模块引用 | `'mdb.mongoDBService'` | 含 `.`，格式为 `moduleName.serviceTag` | 指定模块的已实例化服务 |
+
+### 模块内引用
+
+在同一模块内，服务按 `serviceDefs` 数组顺序依次实例化。后声明的服务可以依赖先声明的服务：
+
+```typescript
+// ✅ 正确：articleService 先声明，articleController 后声明
+const myModule: IModule = {
+  name: 'myServer',
+  serviceDefs: [
+    {
+      serviceTag: 'articleService',
+      serviceImpl: ArticleService,
+      dependencies: ['mdb.mongoDBService'],  // 跨模块引用
+      meta: { usageType: 'normal_service' }
+    },
+    {
+      serviceTag: 'articleController',
+      serviceImpl: ArticleController,
+      dependencies: ['articleService'],  // 模块内引用
+      meta: { usageType: 'controller' }
+    }
+  ]
+};
+```
+
+> ⚠️ **顺序很重要**：被依赖的服务必须先在 `serviceDefs` 中声明，否则框架在实例化时找不到依赖会抛出错误。
+
+### 跨模块引用
+
+使用 `'moduleName.serviceTag'` 格式可以引用其他模块中的服务。要求：
+
+1. 目标模块必须在当前模块之前加载（通过 `moduleDependencies` 声明）
+2. 目标模块中的服务必须已经实例化
+
+```typescript
+// 引用 mdb 模块的 mongoDBService
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['mdb.mongoDBService'],  // 跨模块引用
+  meta: { usageType: 'normal_service' }
+};
+
+const myModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['mdb'],  // 声明模块级依赖
+  serviceDefs: [myServiceDef]
+};
+```
+
+### 常见跨模块引用
+
+linyjs 框架内置模块提供以下可注入服务：
+
+| 依赖引用 | 接口类型 | 来源模块 | 说明 |
+|----------|----------|----------|------|
+| `'mdb.mongoDBService'` | `IMongoDBService` | mdb | MongoDB 数据库服务 |
+| `'authServer.userService'` | `IUserService` | auth | 用户管理服务 |
+| `'authServer.initService'` | - | auth | 系统初始化服务 |
+| `'permissionServer.permissionService'` | `IPermissionService` | permission | 权限检查服务 |
+
+> 💡 使用 `@linyjs/shared-module-interface` 包可以获取这些接口的 TypeScript 类型定义，详见 [shared-module-interface 指南](./shared-module-interface.md)。
+
+## 构造函数约定
+
+### ⚠️ 必须使用解构赋值
+
+框架将所有依赖组装为一个对象传入构造函数。构造函数**必须解构**该对象才能获取各个服务实例。
+
+```typescript
+// ✅ 正确：解构赋值
+class MyController {
+  private mongoDBService: IMongoDBService;
+
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;  // mongoDBService 是服务实例
+  }
+}
+```
+
+```typescript
+// ❌ 错误：不解构，直接赋值
+class MyController {
+  constructor(deps: any) {
+    this.mongoDBService = deps;  // deps 是 { mongoDBService: <实例> }，不是实例本身
+    // this.mongoDBService.getCollection → ❌ undefined is not a function
+  }
+}
+```
+
+### 多个依赖的解构
+
+当服务有多个依赖时，在解构中列出所有依赖：
+
+```typescript
+class MyController {
+  constructor(
+    private mongoDBService: IMongoDBService,
+    private userService: IUserService,
+    private permissionService: IPermissionService
+  ) {}
+}
+
+// 对应的 ServiceDef
+const myControllerDef: IServiceDef = {
+  serviceTag: 'myController',
+  serviceImpl: MyController,
+  dependencies: [
+    'mdb.mongoDBService',
+    'authServer.userService',
+    'permissionServer.permissionService'
+  ],
+  meta: { usageType: 'controller' }
+};
+```
+
+> ⚠️ 上面的写法使用了 TypeScript 参数属性（`private mongoDBService`），但框架传入的是**一个对象**而非多个参数。正确的写法应该是：
+
+```typescript
+// ✅ 正确：接收单个对象参数并解构
+class MyController {
+  private mongoDBService: IMongoDBService;
+  private userService: IUserService;
+  private permissionService: IPermissionService;
+
+  constructor(deps: {
+    mongoDBService: IMongoDBService;
+    userService: IUserService;
+    permissionService: IPermissionService;
+  }) {
+    this.mongoDBService = deps.mongoDBService;
+    this.userService = deps.userService;
+    this.permissionService = deps.permissionService;
+  }
+}
+```
+
+或使用解构简写：
+
+```typescript
+// ✅ 正确：解构简写
+class MyController {
+  private mongoDBService: IMongoDBService;
+  private userService: IUserService;
+  private permissionService: IPermissionService;
+
+  constructor({ mongoDBService, userService, permissionService }: {
+    mongoDBService: IMongoDBService;
+    userService: IUserService;
+    permissionService: IPermissionService;
+  }) {
+    this.mongoDBService = mongoDBService;
+    this.userService = userService;
+    this.permissionService = permissionService;
+  }
+}
+```
+
+### 工厂函数
+
+`serviceImpl` 也可以是工厂函数（非 class）。工厂函数同样接收 `depsRecord` 对象：
+
+```typescript
+// 工厂函数方式
+const myServiceDef: IServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: ({ mongoDBService }: { mongoDBService: IMongoDBService }) => {
+    // 返回服务对象
+    return {
+      async doSomething() {
+        const collection = mongoDBService.getCollection('items');
+        return await collection.find({}).toArray();
+      }
+    };
+  },
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'normal_service' }
+};
+```
+
+> 💡 框架通过检测 `prototype.constructor` 和 `class` 关键字来判断是 class 还是工厂函数。class 使用 `new` 调用，工厂函数直接调用。
+
+## 实例化流程
+
+框架加载模块时，按以下顺序处理：
+
+```
+1. 遍历 serverModules
+   │
+   ├── 2. 对每个模块，遍历 serviceDefs（按数组顺序）
+   │      │
+   │      ├── 3. 对每个 serviceDef，调用 instantiateService()
+   │      │      │
+   │      │      ├── 解析 dependencies 数组
+   │      │      │   ├── 模块内引用 → 从 loadedModule.services 查找
+   │      │      │   └── 跨模块引用 → 从 loadedModules 目标模块查找
+   │      │      │
+   │      │      ├── 组装 depsRecord = { serviceTag: instance, ... }
+   │      │      │
+   │      │      └── new serviceImpl(depsRecord) 或 serviceImpl(depsRecord)
+   │      │
+   │      ├── 4. 将实例存入 loadedModule.services.set(serviceTag, instance)
+   │      │
+   │      └── 5. 按 meta.usageType 分发
+   │          ├── controller → 注册路由
+   │          ├── middleware → 注册中间件
+   │          ├── cron → 注册定时任务
+   │          └── normal_service → 注册到服务池
+   │
+   └── 6. 所有 serviceDefs 处理完毕
+       │
+       └── 7. 遍历所有服务实例，调用 initialize()（如果存在）
+```
+
+### 关键规则
+
+1. **顺序依赖**：`serviceDefs` 数组中的顺序决定实例化顺序。被依赖的服务必须先声明。
+2. **模块加载顺序**：跨模块依赖要求被依赖的模块先加载。通过 `moduleDependencies` 声明。
+3. **单例模式**：每个 serviceDef 只实例化一次，在整个应用生命周期中是单例。
+4. **初始化钩子**：如果服务实例有 `initialize()` 方法，框架会在所有服务实例化后自动调用。
+
+## 完整示例
+
+以下是一个完整的模块示例，展示模块内依赖和跨模块依赖的正确用法：
+
+```typescript
+import type { IModule, IServiceDef, IControllerService } from '@linyjs/server-module-interface';
+import type { IMongoDBService, IUserService } from '@linyjs/shared-module-interface';
+
+// ==================== 服务层 ====================
+
+class TodoService {
+  private mongoDBService: IMongoDBService;
+
+  // ✅ 解构赋值接收依赖
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  async listTodos() {
+    const collection = this.mongoDBService.getCollection('todos');
+    return await collection.find({}).toArray();
+  }
+
+  async createTodo(data: { title: string; userId: string }) {
+    const collection = this.mongoDBService.getCollection('todos');
+    const now = new Date();
+    const result = await collection.insertOne({
+      ...data,
+      completed: false,
+      createdAt: now,
+      updatedAt: now,
+    });
+    return { ...data, _id: result.insertedId, completed: false, createdAt: now, updatedAt: now };
+  }
+}
+
+// ==================== 控制器层 ====================
+
+class TodoController implements IControllerService {
+  private todoService: TodoService;
+  private userService: IUserService;
+
+  // ✅ 多依赖解构
+  constructor(deps: { todoService: TodoService; userService: IUserService }) {
+    this.todoService = deps.todoService;
+    this.userService = deps.userService;
+  }
+
+  getRoutes() {
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/todos',
+        middlewares: ['auth'],
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
+          const todos = await this.todoService.listTodos();
+          return { success: true, data: todos };
+        }
+      },
+      {
+        method: 'POST' as const,
+        path: '/api/todos',
+        middlewares: ['auth'],
+        responseType: 'json' as const,
+        handler: async (params: Record<string, any>, ctx: any) => {
+          const user = ctx.user;
+          const todo = await this.todoService.createTodo({
+            title: params.title,
+            userId: user._id.toString(),
+          });
+          return { success: true, data: todo };
+        }
+      }
+    ];
+  }
+}
+
+// ==================== ServiceDef 声明 ====================
+
+// 注意顺序：TodoService 先声明（被 TodoController 依赖）
+const todoServiceDef: IServiceDef = {
+  serviceTag: 'todoService',
+  serviceImpl: TodoService,
+  dependencies: ['mdb.mongoDBService'],  // 跨模块依赖
+  meta: { usageType: 'normal_service' }
+};
+
+const todoControllerDef: IServiceDef = {
+  serviceTag: 'todoController',
+  serviceImpl: TodoController,
+  dependencies: [
+    'todoService',              // 模块内依赖
+    'authServer.userService'    // 跨模块依赖
+  ],
+  meta: { usageType: 'controller' }
+};
+
+// ==================== 模块导出 ====================
+
+export const todoServerModule: IModule = {
+  name: 'todoServer',
+  moduleDependencies: ['mdb', 'authServer'],  // 声明模块级依赖
+  serviceDefs: [todoServiceDef, todoControllerDef]  // 顺序：先 service 后 controller
+};
+```
+
+## initialize 生命周期钩子
+
+如果服务类实现了 `initialize()` 方法，框架会在模块所有服务实例化完毕后自动调用。适合做初始化逻辑：
+
+```typescript
+class InitService {
+  private mongoDBService: IMongoDBService;
+
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  // 框架会自动调用此方法
+  async initialize() {
+    console.log('[MyModule] Initializing...');
+
+    // 创建索引
+    const collection = this.mongoDBService.getCollection('items');
+    await collection.createIndex({ name: 1 }, { unique: true });
+
+    // 初始化默认数据
+    const count = await collection.countDocuments();
+    if (count === 0) {
+      await collection.insertOne({ name: 'default', createdAt: new Date() });
+    }
+
+    console.log('[MyModule] Initialization complete');
+  }
+}
+
+const initServiceDef: IServiceDef = {
+  serviceTag: 'initService',
+  serviceImpl: InitService,
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'normal_service' }
+};
+```
+
+## 常见错误
+
+### 1. 构造函数未解构依赖
+
+```typescript
+// ❌ 错误
+class MyController {
+  constructor(deps: any) {
+    this.service = deps;  // deps 是 { service: <实例> }
+  }
+}
+// 运行时报错：this.service.someMethod is not a function
+
+// ✅ 正确
+class MyController {
+  constructor({ service }: { service: SomeService }) {
+    this.service = service;  // service 是实例本身
+  }
+}
+```
+
+### 2. 依赖顺序错误
+
+```typescript
+// ❌ 错误：controller 依赖 service，但 controller 先声明
+const myModule: IModule = {
+  name: 'myServer',
+  serviceDefs: [
+    { serviceTag: 'myController', serviceImpl: MyController, dependencies: ['myService'], meta: { usageType: 'controller' } },
+    { serviceTag: 'myService', serviceImpl: MyService, meta: { usageType: 'normal_service' } }
+    // ↑ 报错：Service not found in current module: myService
+  ]
+};
+
+// ✅ 正确：service 先声明
+const myModule: IModule = {
+  name: 'myServer',
+  serviceDefs: [
+    { serviceTag: 'myService', serviceImpl: MyService, meta: { usageType: 'normal_service' } },
+    { serviceTag: 'myController', serviceImpl: MyController, dependencies: ['myService'], meta: { usageType: 'controller' } }
+  ]
+};
+```
+
+### 3. 跨模块依赖未声明 moduleDependencies
+
+```typescript
+// ❌ 错误：依赖了 mdb 模块但未声明
+const myModule: IModule = {
+  name: 'myServer',
+  // 缺少 moduleDependencies: ['mdb']
+  serviceDefs: [
+    { serviceTag: 'myService', serviceImpl: MyService, dependencies: ['mdb.mongoDBService'], meta: { usageType: 'normal_service' } }
+    // ↑ 可能报错：Module not found: mdb
+  ]
+};
+
+// ✅ 正确
+const myModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['mdb'],  // 显式声明模块依赖
+  serviceDefs: [/* ... */]
+};
+```
+
+### 4. 使用 TypeScript 参数属性（constructor(private x)）
+
+TypeScript 的参数属性语法 `constructor(private x: Type)` 会被编译为多个构造函数参数，与框架的单对象参数约定不兼容：
+
+```typescript
+// ❌ 错误：TypeScript 参数属性在编译后会生成 this.x = arguments[0]
+// 框架传入的是一个对象 { x: instance }，会被整体赋给 this.x
+class MyController {
+  constructor(private mongoDBService: IMongoDBService) {}
+  // 编译后：this.mongoDBService = { mongoDBService: <实例> }（整个对象）
+}
+
+// ✅ 正确：显式声明属性并解构
+class MyController {
+  private mongoDBService: IMongoDBService;
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+}
+```
+
+## 相关文档
+
+- 📖 [服务端模块开发](./server-module.md) — 控制器、中间件、定时任务
+- 📦 [shared-module-interface 指南](./shared-module-interface.md) — 类型定义包使用说明
+- 💾 [数据持久化](./data-persistence.md) — MongoDB 服务使用
+- 🔒 [权限管理](./permissions.md) — 权限服务使用
+- 🔧 [API 参考](../api-reference/index.md) — 接口类型定义
+
+---
+
+**上一篇**: [服务端模块开发](./server-module.md) | **下一篇**: [shared-module-interface 指南](./shared-module-interface.md)

package/docs/guides/permissions.md

@@ -65,7 +65,7 @@ class ArticleController {
           }
           
           // 业务逻辑...
-          const article = await createArticle(params.body);
+          const article = await createArticle(params);
           return { success: true, data: article };
         }
       }