@linyjs/plugin-docs 0.1.3 → 0.1.4

package/README.md

@@ -82,6 +82,7 @@ docs/
 │   └── ui-slots-interface.md
 ├── best-practices/       # 最佳实践
 │   ├── naming-conventions.md
+│   ├── service-definition.md  # ServiceDef 代码风格规范
 │   ├── error-handling.md
 │   ├── performance.md
 │   └── security.md
@@ -107,7 +108,7 @@ examples/
 
 linyjs 提供了以下核心模块，插件可以通过依赖注入方式调用这些基础服务：
 
-### @linyjs/mongodb
+### @linyjs/mdb
 **MongoDB 数据库服务**
 - 提供数据持久化存储
 - 支持 CRUD 操作和复杂查询
@@ -125,15 +126,9 @@ linyjs 提供了以下核心模块，插件可以通过依赖注入方式调用
 - 细粒度的权限定义
 - 详情：[权限管理指南](./docs/guides/permissions.md)
 
-## 🔗 相关链接
-
-- [linyjs 框架](https://github.com/linyjs/linyjs)
-- [CLI 工具文档](https://github.com/linyjs/linyjs/tree/main/packages/cli)
-- [报告文档问题](https://github.com/linyjs/linyjs/issues)
-
 ## 📖 核心模块指南
 
-- 💾 [数据持久化](./docs/guides/data-persistence.md) - 使用 @linyjs/mongodb
+- 💾 [数据持久化](./docs/guides/data-persistence.md) - 使用 @linyjs/mdb
 - 🔐 [用户认证](./docs/guides/authentication.md) - 使用 @linyjs/auth
 - 🛡️ [权限管理](./docs/guides/permissions.md) - 使用 @linyjs/permission
 

package/docs/api-reference/index.md

@@ -335,7 +335,7 @@ registry.register({
 linyjs 框架提供了以下基础模块，插件开发者可以通过依赖注入方式使用：
 
 ### 数据库模块
-- **@linyjs/mongodb** - MongoDB 数据库服务
+- **@linyjs/mdb** - MongoDB 数据库服务
 - 提供数据库连接、CRUD 操作、索引管理等功能
 - 详见：[数据持久化指南](../guides/data-persistence.md)
 

package/docs/best-practices/error-handling.md

@@ -459,4 +459,4 @@ function getUserFriendlyError(error: string): string {
 
 ---
 
-**上一篇**: [命名规范](./naming-conventions.md) | **下一篇**: [性能优化](./performance.md)
+**上一篇**: [ServiceDef 代码风格规范](./service-definition.md) | **下一篇**: [性能优化](./performance.md)

package/docs/best-practices/naming-conventions.md

@@ -487,9 +487,10 @@ git commit -m "Update the documentation for the slot feature"  # 太长
 ## 相关文档
 
 - ⚠️ [错误处理](./error-handling.md)
+- 📐 [ServiceDef 代码风格规范](./service-definition.md)
 - ⚡ [性能优化](./performance.md)
 - 🔒 [安全性](./security.md)
 
 ---
 
-**上一篇**: [数据持久化](../guides/data-persistence.md) | **下一篇**: [错误处理](./error-handling.md)
+**上一篇**: [数据持久化](../guides/data-persistence.md) | **下一篇**: [ServiceDef 代码风格规范](./service-definition.md)

package/docs/best-practices/performance.md

@@ -150,10 +150,10 @@ function ResponsiveImage() {
 ```typescript
 // ✅ 推荐：使用索引和投影
 class OptimizedArticleService {
-  constructor(private mongodb: IMongoDBService) {}
+  constructor(private mongodbService: IMongoDBService) {}
 
   async getArticles() {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
 
     // 使用索引字段查询
@@ -175,7 +175,7 @@ class OptimizedArticleService {
 
   // 添加索引
   async createIndexes() {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
 
     await collection.createIndex({ status: 1, createdAt: -1 });
@@ -259,7 +259,7 @@ class AsyncProcessingService {
 
   private async getBatchData(offset: number, limit: number) {
     // 获取数据批次
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     return db.collection('items')
       .find()
       .skip(offset)

package/docs/best-practices/service-definition.md

@@ -0,0 +1,332 @@
+# ServiceDef 代码风格规范
+
+本指南介绍 linyjs 插件开发中 `ServiceDef` 的两条核心代码风格规范，确保代码组织一致、可读、易维护。
+
+## 为什么需要规范?
+
+- 📖 **提高可读性** — 服务定义与实现放在一起，一目了然
+- 🔍 **便于查找** — 看到类就能找到它的 ServiceDef，反之亦然
+- 🛠️ **减少错误** — 独立声明减少缩进层级，避免括号匹配错误
+- 🤝 **团队协作** — 统一风格，降低 review 沟通成本
+
+---
+
+## 规则一：ServiceDef 必须声明为独立变量
+
+### 规则说明
+
+`ServiceDef` 必须先声明为独立变量，然后在 `serviceDefs` 数组中通过变量名引用。**禁止**将 `ServiceDef` 对象字面量直接内联在 `serviceDefs` 数组中。
+
+### ✅ 正确写法
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+const helloControllerDef: IServiceDef = {
+  serviceTag: 'helloController',
+  serviceImpl: HelloController,
+  meta: { usageType: 'controller' }
+};
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [helloControllerDef]
+};
+```
+
+### ❌ 错误写法
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+class HelloController {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+export const helloServerModule: IModule = {
+  name: 'helloServer',
+  serviceDefs: [
+    {
+      serviceTag: 'helloController',
+      serviceImpl: HelloController,
+      meta: { usageType: 'controller' }
+    }
+  ]
+};
+```
+
+### 原因
+
+| 对比项 | 独立变量声明 | 内联在数组中 |
+|--------|------------|------------|
+| 缩进层级 | 浅（2层） | 深（4层+） |
+| 可读性 | 高，变量名即语义 | 低，大段对象字面量淹没模块声明 |
+| 复用性 | 可被多个模块引用 | 无法复用 |
+| 维护性 | 修改时不影响模块声明 | 修改时需在数组中定位 |
+
+---
+
+## 规则二：ServiceDef 声明必须与实现类放在同一个文件中
+
+### 规则说明
+
+`ServiceDef` 声明必须紧挨着它的 `serviceImpl` 实现类，放在同一个文件中。**禁止**将 `ServiceDef` 和实现类分离到不同文件，然后在模块入口文件中重新声明。
+
+### ✅ 正确写法
+
+**`src/server/services/article-controller.ts`**
+
+```typescript
+import type { IControllerService, IControllerServiceDef } from '@linyjs/server-module-interface';
+
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+
+export const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'controller' }
+};
+```
+
+**`src/server/server-module.ts`**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { articleControllerDef } from './services/article-controller.js';
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['mdb'],
+  serviceDefs: [articleControllerDef]
+};
+```
+
+### ❌ 错误写法
+
+**`src/server/services/article-controller.ts`** — 只有类，没有 ServiceDef
+
+```typescript
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [/* ... */];
+  }
+}
+```
+
+**`src/server/server-module.ts`** — ServiceDef 与类分离
+
+```typescript
+import { ArticleController } from './services/article-controller.js';
+
+const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['mdb.mongoDBService'],
+  meta: { usageType: 'controller' }
+};
+
+export const articleServerModule: IModule = {
+  name: 'articleServer',
+  moduleDependencies: ['mdb'],
+  serviceDefs: [articleControllerDef]
+};
+```
+
+### 原因
+
+| 对比项 | 同文件放置 | 分离到不同文件 |
+|--------|----------|-------------|
+| 内聚性 | 高，定义与实现在一起 | 低，需跨文件查找 |
+| 修改成本 | 低，改一处即可 | 高，可能漏改 |
+| 文件职责 | 清晰，每个文件自包含 | 模糊，入口文件混杂声明 |
+
+---
+
+## 完整示例
+
+以下是一个完整的服务端模块示例，遵循两条规范：
+
+### 项目结构
+
+```
+src/server/
+├── controllers/
+│   └── article-controller.ts   # ArticleController 类 + articleControllerDef
+├── middleware/
+│   └── auth-middleware.ts       # AuthMiddleware 类 + authMiddlewareDef
+├── services/
+│   └── article-service.ts       # ArticleService 类 + articleServiceDef
+└── server-module.ts             # 模块入口，只做导入和组装
+```
+
+### 控制器文件
+
+**`src/server/controllers/article-controller.ts`**
+
+```typescript
+import type { IControllerService, IControllerServiceDef } from '@linyjs/server-module-interface';
+
+export class ArticleController implements IControllerService {
+  getRoutes() {
+    return [
+      {
+        method: 'GET' as const,
+        path: '/api/articles',
+        middlewares: [],
+        responseType: 'json' as const,
+        handler: async () => {
+          return { articles: [] };
+        }
+      }
+    ];
+  }
+}
+
+export const articleControllerDef: IControllerServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  dependencies: ['articleService'],
+  meta: { usageType: 'controller' }
+};
+```
+
+### 中间件文件
+
+**`src/server/middleware/auth-middleware.ts`**
+
+```typescript
+import type { IMiddlewareService, IMiddlewareServiceDef } from '@linyjs/server-module-interface';
+
+export class AuthMiddleware implements IMiddlewareService {
+  getMiddlewares() {
+    return [{
+      middlewareId: 'auth',
+      handler: async (params, ctx, next) => {
+        // 认证逻辑...
+        await next();
+      }
+    }];
+  }
+}
+
+export const authMiddlewareDef: IMiddlewareServiceDef = {
+  serviceTag: 'authMiddleware',
+  serviceImpl: AuthMiddleware,
+  meta: { usageType: 'middleware' }
+};
+```
+
+### 模块入口文件
+
+**`src/server/server-module.ts`**
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+import { articleControllerDef } from './controllers/article-controller.js';
+import { authMiddlewareDef } from './middleware/auth-middleware.js';
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  serviceDefs: [articleControllerDef, authMiddlewareDef]
+};
+```
+
+> 模块入口文件只负责**导入和组装**，不包含任何 ServiceDef 声明或服务实现类。
+
+---
+
+## 客户端模块同样适用
+
+以上两条规范同样适用于客户端模块：
+
+### ✅ 正确写法
+
+**`src/client/index.tsx`**
+
+```typescript
+import type { IModule, IRouteDef } from '@linyjs/client-module-interface';
+import React from 'react';
+
+function HelloPage() {
+  return <div>Hello!</div>;
+}
+
+class HelloRouteService implements IRouteService {
+  basePath = '/hello';
+
+  getRoutes() {
+    return [{
+      path: '/',
+      component: HelloPage,
+      key: 'hello-page',
+      meta: { title: 'Hello' }
+    }];
+  }
+}
+
+const helloRouteDef: IRouteDef = {
+  serviceTag: 'helloRoute',
+  serviceImpl: HelloRouteService,
+  meta: { usageType: 'route' }
+};
+
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [helloRouteDef]
+};
+```
+
+### ❌ 错误写法
+
+```typescript
+// ServiceDef 内联在数组中，且使用了匿名类
+export const helloClientModule: IModule = {
+  name: 'helloClient',
+  serviceDefs: [{
+    serviceTag: 'helloRoute',
+    serviceImpl: class {
+      basePath = '/hello';
+      getRoutes() { /* ... */ }
+    },
+    meta: { usageType: 'route' }
+  }]
+};
+```
+
+> 客户端模块中如果文件较小（如 Hello World 级别），可以将类、ServiceDef 和模块声明放在同一个文件中。但仍然禁止内联在 `serviceDefs` 数组中，也禁止使用匿名类作为 `serviceImpl`。
+
+---
+
+## 检查清单
+
+在提交代码前，请检查以下几点：
+
+- [ ] 所有 `ServiceDef` 都声明为独立变量，未内联在 `serviceDefs` 数组中
+- [ ] 每个 `ServiceDef` 声明都紧挨着对应的实现类，在同一个文件中
+- [ ] `serviceImpl` 使用具名类，不使用匿名类或内联箭头函数
+- [ ] 模块入口文件（`server-module.ts` / `client-module.ts`）只做导入和组装，不包含 ServiceDef 声明
+- [ ] 导入类型时包含 `IServiceDef`（或其子类型如 `IControllerServiceDef`），为声明提供类型标注
+
+## 相关文档
+
+- 📖 [服务端模块开发](../guides/server-module.md)
+- 📖 [客户端模块开发](../guides/client-module.md)
+- 📖 [命名规范](./naming-conventions.md)
+- ⚠️ [错误处理](./error-handling.md)
+
+---
+
+**上一篇**: [命名规范](./naming-conventions.md) | **下一篇**: [错误处理](./error-handling.md)

package/docs/faq.md

@@ -110,7 +110,6 @@ export const serviceB = {
 **A:** 可以通过以下方式:
 1. **覆盖路由**: 注册相同路径的路由(后加载的优先)
 2. **扩展 Slot**: 向现有 Slot 添加新组件
-3. **装饰器模式**: 包装其他插件的服务
 
 ---
 

package/docs/getting-started/first-plugin.md

@@ -188,18 +188,18 @@ export class ArticleController implements IControllerService {
 创建 `src/server/index.ts`:
 
 ```typescript
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
 import { ArticleController } from './controllers/ArticleController';
 
+const articleControllerDef: IServiceDef = {
+  serviceTag: 'articleController',
+  serviceImpl: ArticleController,
+  meta: { usageType: 'controller' }
+};
+
 export const blogServerModule: IModule = {
   name: 'blogServer',
-  serviceDefs: [
-    {
-      serviceTag: 'articleController',
-      serviceImpl: ArticleController,
-      meta: { usageType: 'controller' }
-    }
-  ]
+  serviceDefs: [articleControllerDef]
 };
 ```
 
@@ -308,15 +308,15 @@ class BlogRouteService {
   }
 }
 
+const blogRouteDef: IServiceDef = {
+  serviceTag: 'blogRoute',
+  serviceImpl: BlogRouteService,
+  meta: { usageType: 'route' }
+};
+
 export const blogClientModule: IModule = {
   name: 'blogClient',
-  serviceDefs: [
-    {
-      serviceTag: 'blogRoute',
-      serviceImpl: BlogRouteService,
-      meta: { usageType: 'route' }
-    }
-  ]
+  serviceDefs: [blogRouteDef]
 };
 ```
 

package/docs/getting-started/installation.md

@@ -65,7 +65,7 @@ npm install @linyjs/plugin-docs
 
 ```bash
 # MongoDB 服务(数据持久化)
-npm install @linyjs/mongodb
+npm install @linyjs/mdb
 
 # 权限管理
 npm install @linyjs/permission

package/docs/getting-started/quick-start.md

@@ -100,7 +100,7 @@ hello-plugin/
 如果你需要自定义或创建新的服务端代码，编辑 `src/server/index.ts`:
 
 ```typescript
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
 
 class HelloController {
   getRoutes() {
@@ -116,13 +116,15 @@ class HelloController {
   }
 }
 
+const helloControllerDef: IServiceDef = {
+  serviceTag: 'helloController',
+  serviceImpl: HelloController,
+  meta: { usageType: 'controller' }
+};
+
 export const helloServerModule: IModule = {
   name: 'helloServer',
-  serviceDefs: [{
-    serviceTag: 'helloController',
-    serviceImpl: HelloController,
-    meta: { usageType: 'controller' }
-  }]
+  serviceDefs: [helloControllerDef]
 };
 ```
 
@@ -133,7 +135,7 @@ export const helloServerModule: IModule = {
 如果你需要自定义或创建新的客户端代码，编辑 `src/client/index.tsx`:
 
 ```typescript
-import type { IModule } from '@linyjs/client-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/client-module-interface';
 import React from 'react';
 
 function HelloPage() {
@@ -145,23 +147,27 @@ function HelloPage() {
   );
 }
 
+class HelloRouteService {
+  basePath = '/hello';
+  getRoutes() {
+    return [{
+      path: '/',
+      component: HelloPage,
+      key: 'hello-page',
+      meta: { title: 'Hello' }
+    }];
+  }
+}
+
+const helloRouteDef: IServiceDef = {
+  serviceTag: 'helloRoute',
+  serviceImpl: HelloRouteService,
+  meta: { usageType: 'route' }
+};
+
 export const helloClientModule: IModule = {
   name: 'helloClient',
-  serviceDefs: [{
-    serviceTag: 'helloRoute',
-    serviceImpl: class {
-      basePath = '/hello';
-      getRoutes() {
-        return [{
-          path: '/',
-          component: HelloPage,
-          key: 'hello-page',
-          meta: { title: 'Hello' }
-        }];
-      }
-    },
-    meta: { usageType: 'route' }
-  }]
+  serviceDefs: [helloRouteDef]
 };
 ```
 

package/docs/guides/authentication.md

@@ -16,20 +16,24 @@ linyjs 提供完整的用户认证系统，支持:
 ### 在服务端模块中注入依赖
 
 ```typescript
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
 import { login, register, verifyToken } from '@linyjs/auth';
 
+class AuthController {
+  // ... 控制器实现
+}
+
+const authControllerDef: IServiceDef = {
+  serviceTag: 'authController',
+  serviceImpl: AuthController,
+  dependencies: [],
+  meta: { usageType: 'controller' }
+};
+
 export const myServerModule: IModule = {
   name: 'myServer',
-  moduleDependencies: ['auth'],  // 依赖认证模块
-  serviceDefs: [
-    {
-      serviceTag: 'authController',
-      serviceImpl: AuthController,
-      dependencies: [],  // 依赖注入将在类构造函数中使用
-      meta: { usageType: 'controller' }
-    }
-  ]
+  moduleDependencies: ['auth'],
+  serviceDefs: [authControllerDef]
 };
 ```
 
@@ -276,22 +280,26 @@ function LoginForm() {
   );
 }
 
+class LoginFormService {
+  getComponents() {
+    return {
+      LoginForm: {
+        component: LoginForm,
+        meta: { usageType: 'normal_component' }
+      }
+    };
+  }
+}
+
+const loginFormDef: IServiceDef = {
+  serviceTag: 'loginForm',
+  serviceImpl: LoginFormService,
+  meta: { usageType: 'normal_service' }
+};
+
 export const authClientModule: IModule = {
   name: 'authClient',
-  serviceDefs: [{
-    serviceTag: 'loginForm',
-    serviceImpl: function() {
-      getComponents() {
-        return {
-          LoginForm: {
-            component: LoginForm,
-            meta: { usageType: 'normal_component' }
-          }
-        };
-      }
-    },
-    meta: { usageType: 'normal_service' }
-  }]
+  serviceDefs: [loginFormDef]
 };
 ```
 

package/docs/guides/client-module.md

@@ -545,6 +545,12 @@ function MyPage() {
 
 ## 最佳实践
 
+### 0. 遵循 ServiceDef 代码风格规范
+
+> 📐 **重要**: 请阅读 [ServiceDef 代码风格规范](../best-practices/service-definition.md)，了解两条核心规则：
+> 1. ServiceDef 必须声明为独立变量，禁止内联在 `serviceDefs` 数组中
+> 2. ServiceDef 声明必须与实现类放在同一个文件中
+
 ### 1. 组件拆分
 
 ```