@linyjs/plugin-docs 0.1.3 → 0.1.4

package/docs/guides/data-persistence.md

@@ -16,34 +16,89 @@ linyjs 提供 MongoDB 服务,支持:
 ### 在服务端模块中注入依赖
 
 ```typescript
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+import type { IMongoDBService } from '@linyjs/mdb';
+
+class ArticleService {
+  constructor({ mongoDBService }: { mongoDBService: IMongoDBService }) {
+    this.mongoDBService = mongoDBService;
+  }
+
+  // ... 服务方法
+}
+
+const articleServiceDef: IServiceDef = {
+  serviceTag: 'articleService',
+  serviceImpl: ArticleService,
+  dependencies: ['mdb.mongoDBService'],  // 注入 MongoDB 服务
+  meta: { usageType: 'normal_service' }
+};
 
 export const myServerModule: IModule = {
   name: 'myServer',
-  moduleDependencies: ['mongodb'],  // 依赖 MongoDB 模块
-  serviceDefs: [
-    {
-      serviceTag: 'articleService',
-      serviceImpl: ArticleService,
-      dependencies: ['mongodb.mongodb'],  // 注入 MongoDB 服务
-      meta: { usageType: 'normal_service' }
-    }
-  ]
+  moduleDependencies: ['mdb'],  // 依赖 MongoDB 模块
+  serviceDefs: [articleServiceDef]
 };
 ```
 
+## 使用 ObjectId
+
+在 MongoDB 中，文档的主键 `_id` 默认是 `ObjectId` 类型。在查询、更新、删除等操作中经常需要用 `ObjectId` 构造器将字符串 ID 转换为 `ObjectId` 实例。
+
+### 为什么不从 mongodb 包直接导入？
+
+linyjs 插件通常作为独立的 npm 包或 git 仓库开发，如果每个插件都直接依赖 `mongodb` npm 包，会带来以下问题：
+
+- 📦 **包体积增大** — 插件单独安装一份 mongodb 驱动
+- ⚠️ **版本冲突** — 插件与框架使用的 mongodb 版本不一致
+- 🔧 **配置冗余** — 每个插件都需要在 `package.json` 中声明 mongodb 依赖
+
+### 方式一：通过 IMongoDBService 使用
+
+`@linyjs/mdb` 在 `IMongoDBService` 接口上暴露了 `ObjectId` 构造器，插件可以通过注入的 `mongoDBService` 直接使用：
+
+```typescript
+import type { IMongoDBService } from '@linyjs/mdb';
+
+class ArticleService {
+  constructor(private mongoDBService: IMongoDBService) {}
+
+  async getArticleById(id: string) {
+    const collection = this.mongoDBService.getCollection('articles');
+    // ✅ 通过 mongoDBService.ObjectId 使用，无需额外依赖
+    const article = await collection.findOne({
+      _id: new this.mongoDBService.ObjectId(id)
+    });
+    return article;
+  }
+}
+```
+
+### 方式二：从 @linyjs/mdb 直接导入
+
+如果需要在服务类外部使用 `ObjectId`（如类型声明、工具函数等），也可以直接从 `@linyjs/mdb` 导入：
+
+```typescript
+import { ObjectId } from '@linyjs/mdb';
+
+// 在路由 handler 或工具函数中使用
+const articleId = new ObjectId('507f1f77bcf86cd799439011');
+```
+
+> 💡 **推荐**：在服务类内部使用方式一（`this.mongoDBService.ObjectId`），避免额外的 import；在服务类外部使用方式二（`import { ObjectId } from '@linyjs/mdb'`）。两种方式都无需在插件中安装 `mongodb` 包。
+
 ## 基本 CRUD 操作
 
 ### 创建(Create)
 
 ```typescript
-import type { IMongoDBService } from '@linyjs/mongodb';
+import type { IMongoDBService } from '@linyjs/mdb';
 
 class ArticleService {
-  constructor(private mongodb: IMongoDBService) {}
+  constructor(private mongodbService: IMongoDBService) {}
   
   async createArticle(data: any) {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
     
     const result = await collection.insertOne({
@@ -65,19 +120,25 @@ class ArticleService {
 #### 获取单个文档
 
 ```typescript
-async getArticleById(id: string) {
-  const db = this.mongodb.getDb();
-  const collection = db.collection('articles');
-  
-  const article = await collection.findOne({ 
-    _id: new ObjectId(id) 
-  });
+import type { IMongoDBService } from '@linyjs/mdb';
+
+class ArticleService {
+  constructor(private mongoDBService: IMongoDBService) {}
   
-  if (!article) {
-    throw new Error('Article not found');
+  async getArticleById(id: string) {
+    const db = this.mongoDBService.getDb();
+    const collection = db.collection('articles');
+    
+    const article = await collection.findOne({ 
+      _id: new this.mongoDBService.ObjectId(id) 
+    });
+    
+    if (!article) {
+      throw new Error('Article not found');
+    }
+    
+    return article;
   }
-  
-  return article;
 }
 ```
 
@@ -85,7 +146,7 @@ async getArticleById(id: string) {
 
 ```typescript
 async getArticles(page = 1, limit = 10) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   const skip = (page - 1) * limit;
@@ -114,7 +175,7 @@ async getArticles(page = 1, limit = 10) {
 
 ```typescript
 async getArticlesByAuthor(authorId: string) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   const articles = await collection.find({ 
@@ -131,11 +192,11 @@ async getArticlesByAuthor(authorId: string) {
 
 ```typescript
 async updateArticle(id: string, data: any) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   const result = await collection.updateOne(
-    { _id: new ObjectId(id) },
+    { _id: new this.mongoDBService.ObjectId(id) },
     { 
       $set: {
         ...data,
@@ -156,11 +217,11 @@ async updateArticle(id: string, data: any) {
 
 ```typescript
 async updateArticleTitle(id: string, title: string) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   await collection.updateOne(
-    { _id: new ObjectId(id) },
+    { _id: new this.mongoDBService.ObjectId(id) },
     { 
       $set: { 
         title,
@@ -175,11 +236,11 @@ async updateArticleTitle(id: string, title: string) {
 
 ```typescript
 async deleteArticle(id: string) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   const result = await collection.deleteOne({ 
-    _id: new ObjectId(id) 
+    _id: new this.mongoDBService.ObjectId(id) 
   });
   
   if (result.deletedCount === 0) {
@@ -196,7 +257,7 @@ async deleteArticle(id: string) {
 
 ```typescript
 async searchArticles(query: string, options: any) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   // 构建查询条件
@@ -238,7 +299,7 @@ async searchArticles(query: string, options: any) {
 
 ```typescript
 async getArticleStats() {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   const stats = await collection.aggregate([
@@ -269,7 +330,7 @@ async getArticleStats() {
 
 ```typescript
 async getArticlesWithAuthors() {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const articlesCollection = db.collection('articles');
   const usersCollection = db.collection('users');
   
@@ -309,7 +370,7 @@ async getArticlesWithAuthors() {
 
 ```typescript
 async createIndexes() {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   // 单字段索引
@@ -334,7 +395,7 @@ async createIndexes() {
 ```typescript
 // MongoDB 会自动使用合适的索引
 async getArticlesByAuthor(authorId: string) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   // 自动使用 authorId 索引
@@ -348,7 +409,7 @@ async getArticlesByAuthor(authorId: string) {
 
 ```typescript
 async transferArticleAuthor(articleId: string, newAuthorId: string) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const session = db.startSession();
   
   try {
@@ -359,7 +420,7 @@ async transferArticleAuthor(articleId: string, newAuthorId: string) {
     
     // 检查新作者是否存在
     const user = await usersCollection.findOne(
-      { _id: new ObjectId(newAuthorId) },
+      { _id: new this.mongoDBService.ObjectId(newAuthorId) },
       { session }
     );
     
@@ -369,7 +430,7 @@ async transferArticleAuthor(articleId: string, newAuthorId: string) {
     
     // 更新文章作者
     await articlesCollection.updateOne(
-      { _id: new ObjectId(articleId) },
+      { _id: new this.mongoDBService.ObjectId(articleId) },
       { $set: { authorId: newAuthorId } },
       { session }
     );
@@ -409,7 +470,7 @@ async createArticle(data: any) {
     throw new Error('Content too long');
   }
   
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   return await collection.insertOne({
@@ -430,7 +491,7 @@ async createArticle(data: any) {
 ```typescript
 async safeOperation() {
   try {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
     
     const result = await collection.insertOne({ /* ... */ });
@@ -482,7 +543,7 @@ async getArticlesWithAuthors() {
 
 ```typescript
 async getArticlesPaginated(page: number, limit: number) {
-  const db = this.mongodb.getDb();
+  const db = this.mongodbService.getDb();
   const collection = db.collection('articles');
   
   // 使用游标分页(更高效)

package/docs/guides/server-module.md

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

package/docs/migration/v0-to-v1.md

@@ -173,12 +173,12 @@ checkPermission({
 
 #### 旧版本
 ```typescript
-import { MongoConnector } from '@linyjs/mongodb';
+import { MongoConnector } from '@linyjs/mdb';
 ```
 
 #### 新版本
 ```typescript
-import { MongoService } from '@linyjs/mongodb';
+import { MongoService } from '@linyjs/mdb';
 ```
 
 ## 🖥️ 前端迁移

package/examples/analytics-plugin/src/client/index.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { IModule } from '@linyjs/client-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/client-module-interface';
 
 const API_BASE = '/api/analytics';
 
@@ -356,49 +356,53 @@ function AnalyticsTracker({ eventName, userId, children }: {
   );
 }
 
+class AnalyticsRouteService {
+  basePath = '/analytics';
+
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: AnalyticsDashboard,
+        key: 'analytics-dashboard',
+        meta: {
+          title: '分析仪表盘 - linyjs分析插件',
+          description: '查看应用使用统计和用户行为分析'
+        }
+      }
+    ];
+  }
+}
+
+class AnalyticsComponentService {
+  getComponents() {
+    return {
+      AnalyticsDashboard,
+      AnalyticsTracker,
+      StatsCard,
+      SimpleChart
+    };
+  }
+}
+
+const analyticsRouteDef: IServiceDef = {
+  serviceTag: 'analyticsRoute',
+  serviceImpl: AnalyticsRouteService,
+  meta: { usageType: 'route' }
+};
+
+const analyticsComponentDef: IServiceDef = {
+  serviceTag: 'analyticsComponent',
+  serviceImpl: AnalyticsComponentService,
+  meta: { usageType: 'component' }
+};
+
 /**
  * 客户端模块
  */
 export const analyticsClientModule: IModule = {
   name: 'analyticsClient',
-  serviceDefs: [
-    {
-      serviceTag: 'analyticsRoute',
-      serviceImpl: class AnalyticsRouteService {
-        basePath = '/analytics';
-
-        getRoutes() {
-          return [
-            {
-              path: '/',
-              component: AnalyticsDashboard,
-              key: 'analytics-dashboard',
-              meta: {
-                title: '分析仪表盘 - linyjs分析插件',
-                description: '查看应用使用统计和用户行为分析'
-              }
-            }
-          ];
-        }
-      },
-      meta: { usageType: 'route' }
-    },
-
-    {
-      serviceTag: 'analyticsComponent',
-      serviceImpl: class AnalyticsComponentService {
-        getComponents() {
-          return {
-            AnalyticsDashboard,
-            AnalyticsTracker,
-            StatsCard,
-            SimpleChart
-          };
-        }
-      },
-      meta: { usageType: 'component' }
-    }
-  ]
+  serviceDefs: [analyticsRouteDef, analyticsComponentDef]
 };
 
 // 导出组件

package/examples/analytics-plugin/src/server/index.ts

@@ -1,4 +1,4 @@
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
 
 /**
  * 分析数据服务 - 收集和聚合应用使用数据
@@ -315,29 +315,30 @@ class AnalyticsCronService {
   }
 }
 
+const analyticsControllerDef: IServiceDef = {
+  serviceTag: 'analyticsController',
+  serviceImpl: AnalyticsController,
+  meta: { usageType: 'controller' }
+};
+
+const analyticsCronDef: IServiceDef = {
+  serviceTag: 'analyticsCron',
+  serviceImpl: AnalyticsCronService,
+  meta: {
+    usageType: 'service',
+    lifecycle: {
+      init: 'onModuleInit',
+      destroy: 'onModuleDestroy'
+    }
+  }
+};
+
 /**
  * 服务端模块
  */
 export const analyticsServerModule: IModule = {
   name: 'analyticsServer',
-  serviceDefs: [
-    {
-      serviceTag: 'analyticsController',
-      serviceImpl: AnalyticsController,
-      meta: { usageType: 'controller' }
-    },
-    {
-      serviceTag: 'analyticsCron',
-      serviceImpl: AnalyticsCronService,
-      meta: {
-        usageType: 'service',
-        lifecycle: {
-          init: 'onModuleInit',
-          destroy: 'onModuleDestroy'
-        }
-      }
-    }
-  ]
+  serviceDefs: [analyticsControllerDef, analyticsCronDef]
 };
 
 // 导出服务类供其他插件使用

package/examples/blog-plugin/README.md

@@ -153,7 +153,7 @@ Authorization: Bearer <token>
 // src/server/index.ts
 export const blogServerModule: IModule = {
   name: 'blogServer',
-  moduleDependencies: ['mongodb', 'auth'],
+  moduleDependencies: ['mdb', 'auth'],
   serviceDefs: [
     articleControllerDef,
     articleServiceDef
@@ -188,12 +188,12 @@ export const blogClientModule: IModule = {
 // src/server/services/article-service.ts
 class ArticleService {
   constructor(
-    private mongodb: IMongoDBService,
+    private mongodbService: IMongoDBService,
     private auth: IAuthService
   ) {}
 
   async createArticle(data: CreateArticleDto, userId: string) {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
 
     const article = {
@@ -211,7 +211,7 @@ class ArticleService {
   }
 
   async getArticles(filters: ArticleFilters = {}) {
-    const db = this.mongodb.getDb();
+    const db = this.mongodbService.getDb();
     const collection = db.collection('articles');
 
     const query: any = {};

package/examples/blog-plugin/package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "@linyjs/server-module-interface": "^0.0.1",
     "@linyjs/client-module-interface": "^0.0.1",
-    "@linyjs/mongodb": "^0.0.1",
+    "@linyjs/mdb": "^0.0.1",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/examples/blog-plugin/src/client/index.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { IModule } from '@linyjs/client-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/client-module-interface';
 
 const API_BASE = '/api/articles';
 
@@ -350,50 +350,54 @@ function formatContent(content: string): string {
     .replace(/`(.*?)`/g, '<code>$1</code>');
 }
 
+class BlogRouteService {
+  basePath = '/blog';
+
+  getRoutes() {
+    return [
+      {
+        path: '/',
+        component: BlogHome,
+        key: 'blog-home',
+        meta: {
+          title: '博客首页 - linyjs示例',
+          description: '一个简单的博客示例，展示linyjs插件开发'
+        }
+      }
+    ];
+  }
+}
+
+class BlogComponentService {
+  // 注册全局组件
+  getComponents() {
+    return {
+      BlogHome,
+      ArticleList,
+      ArticleDetail,
+      ArticleForm
+    };
+  }
+}
+
+const blogRouteDef: IServiceDef = {
+  serviceTag: 'blogRoute',
+  serviceImpl: BlogRouteService,
+  meta: { usageType: 'route' }
+};
+
+const blogComponentDef: IServiceDef = {
+  serviceTag: 'blogComponent',
+  serviceImpl: BlogComponentService,
+  meta: { usageType: 'component' }
+};
+
 /**
  * 客户端模块定义
  */
 export const blogClientModule: IModule = {
   name: 'blogClient',
-  serviceDefs: [
-    {
-      serviceTag: 'blogRoute',
-      serviceImpl: class BlogRouteService {
-        basePath = '/blog';
-
-        getRoutes() {
-          return [
-            {
-              path: '/',
-              component: BlogHome,
-              key: 'blog-home',
-              meta: {
-                title: '博客首页 - linyjs示例',
-                description: '一个简单的博客示例，展示linyjs插件开发'
-              }
-            }
-          ];
-        }
-      },
-      meta: { usageType: 'route' }
-    },
-
-    {
-      serviceTag: 'blogComponent',
-      serviceImpl: class BlogComponentService {
-        // 注册全局组件
-        getComponents() {
-          return {
-            BlogHome,
-            ArticleList,
-            ArticleDetail,
-            ArticleForm
-          };
-        }
-      },
-      meta: { usageType: 'component' }
-    }
-  ]
+  serviceDefs: [blogRouteDef, blogComponentDef]
 };
 
 // 导出组件方便其他模块使用

package/examples/blog-plugin/src/server/index.ts

@@ -1,4 +1,4 @@
-import type { IModule } from '@linyjs/server-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
 
 /**
  * 文章服务 - 处理文章的业务逻辑
@@ -225,16 +225,16 @@ class 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]
 };

package/examples/hello-world/src/client/index.tsx

@@ -1,4 +1,4 @@
-import type { IModule } from '@linyjs/client-module-interface';
+import type { IModule, IServiceDef } from '@linyjs/client-module-interface';
 import React from 'react';
 
 /**
@@ -95,16 +95,16 @@ class HelloRouteService {
   }
 }
 
+const helloRouteDef: IServiceDef = {
+  serviceTag: 'helloRoute',
+  serviceImpl: HelloRouteService,
+  meta: { usageType: 'route' }
+};
+
 /**
  * 客户端模块定义
  */
 export const helloClientModule: IModule = {
   name: 'helloClient',
-  serviceDefs: [
-    {
-      serviceTag: 'helloRoute',
-      serviceImpl: HelloRouteService,
-      meta: { usageType: 'route' }
-    }
-  ]
+  serviceDefs: [helloRouteDef]
 };