@linyjs/plugin-docs 0.0.13

package/docs/guides/data-persistence.md

@@ -0,0 +1,640 @@
+# 数据持久化
+
+本指南介绍如何在 linyjs 插件中使用 MongoDB 进行数据持久化。
+
+## 概述
+
+linyjs 提供 MongoDB 服务,支持:
+
+- 💾 CRUD 操作(创建、读取、更新、删除)
+- 🔍 复杂查询和聚合
+- 📊 索引优化
+- 🔗 数据关联
+
+## 配置 MongoDB 服务
+
+### 在服务端模块中注入依赖
+
+```typescript
+import type { IModule, IServiceDef } from '@linyjs/server-module-interface';
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+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: ['mdb'],  // 依赖 MongoDB 模块
+  serviceDefs: [articleServiceDef]
+};
+```
+
+## 使用 @linyjs/shared-module-interface 获取类型提示
+
+linyjs 插件通常作为独立的 npm 包或 git 仓库开发。通过依赖注入机制，插件可以获取 `IMongoDBService` 等服务实例，但 TypeScript 需要类型声明才能提供完整的类型提示。
+
+### 安装
+
+在插件的 `package.json` 中添加 `@linyjs/shared-module-interface` 作为开发依赖：
+
+```json
+{
+  "devDependencies": {
+    "@linyjs/shared-module-interface": "^0.0.1"
+  }
+}
+```
+
+此包是**纯类型包**，包含了所有公共模块（mdb、auth、permission）的服务接口和类型定义，并重新导出了 `mongodb` 包的全部类型（`ObjectId`、`Db`、`Collection`、`Document`、`Filter` 等），使插件无需单独安装 `mongodb`、`@linyjs/mdb`、`@linyjs/auth`、`@linyjs/permission` 等包。
+
+> ⚠️ **纯类型包**：此包只导出 TypeScript 类型（`export type`），不包含任何运行时代码。无法通过 `import { ObjectId }` 导入运行时值，运行时请通过依赖注入获取的 `mongoDBService.ObjectId` 使用。
+
+### 可用类型一览
+
+| 类型 | 说明 | 来源模块 |
+|------|------|----------|
+| `IMongoDBService` | MongoDB 服务接口 | @linyjs/mdb |
+| `ObjectId`, `Db`, `Collection`, `Document`, `Filter` ... | mongodb 全部类型 | mongodb |
+| `IUserService` | 用户管理服务接口 | @linyjs/auth |
+| `IAuthUser`, `ISafeUser`, `IAuthResult`, `IJwtPayload` | 认证相关类型 | @linyjs/auth |
+| `IPermissionService` | 权限服务接口 | @linyjs/permission |
+| `IPermissionPolicy`, `IPermissionCheckResult`, `Role` | 权限相关类型 | @linyjs/permission |
+
+## 使用 ObjectId
+
+在 MongoDB 中，文档的主键 `_id` 默认是 `ObjectId` 类型。在查询、更新、删除等操作中经常需要用 `ObjectId` 构造器将字符串 ID 转换为 `ObjectId` 实例。
+
+### 为什么不从 mongodb 包直接导入？
+
+如果每个插件都直接依赖 `mongodb` npm 包，会带来以下问题：
+
+- 📦 **包体积增大** — 插件单独安装一份 mongodb 驱动
+- ⚠️ **版本冲突** — 插件与框架使用的 mongodb 版本不一致
+- 🔧 **配置冗余** — 每个插件都需要在 `package.json` 中声明 mongodb 依赖
+
+### 通过 IMongoDBService 使用
+
+`@linyjs/shared-module-interface` 是纯类型包，不导出运行时值。`ObjectId` 构造器通过 `IMongoDBService` 接口的 `ObjectId` 属性暴露，插件通过注入的 `mongoDBService` 在运行时获取：
+
+```typescript
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+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;
+  }
+}
+```
+
+如果需要在服务类外部（如工具函数）创建 `ObjectId`，可以通过一个辅助函数转发：
+
+```typescript
+// db.ts - 在模块内部保存 mongoDBService 引用
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+let mongoDBService: IMongoDBService | null = null;
+
+export function setMongoDBService(service: IMongoDBService) {
+  mongoDBService = service;
+}
+
+/** 通过注入的 MongoDB 服务创建 ObjectId */
+export function createObjectId(id: string) {
+  if (!mongoDBService) throw new Error('MongoDB service not initialized');
+  return new mongoDBService.ObjectId(id);
+}
+
+// 在 service.ts 中使用
+import { createObjectId } from './db.js';
+const objectId = createObjectId(userId);
+```
+
+> 💡 **类型使用**：如果仅需在类型注解中使用 `ObjectId`（如 `_id?: ObjectId`），可以用 `import type { ObjectId } from '@linyjs/shared-module-interface'`，这是纯类型导入，编译后会被完全擦除。
+
+## 基本 CRUD 操作
+
+### 创建(Create)
+
+```typescript
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+class ArticleService {
+  constructor(private mongodbService: IMongoDBService) {}
+  
+  async createArticle(data: any) {
+    const db = this.mongodbService.getDb();
+    const collection = db.collection('articles');
+    
+    const result = await collection.insertOne({
+      ...data,
+      createdAt: new Date(),
+      updatedAt: new Date()
+    });
+    
+    return {
+      id: result.insertedId,
+      ...data
+    };
+  }
+}
+```
+
+### 读取(Read)
+
+#### 获取单个文档
+
+```typescript
+import type { IMongoDBService } from '@linyjs/shared-module-interface';
+
+class ArticleService {
+  constructor(private mongoDBService: IMongoDBService) {}
+  
+  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;
+  }
+}
+```
+
+#### 获取列表(支持分页)
+
+```typescript
+async getArticles(page = 1, limit = 10) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  const skip = (page - 1) * limit;
+  
+  // 获取总数
+  const total = await collection.countDocuments();
+  
+  // 获取数据
+  const articles = await collection.find()
+    .skip(skip)
+    .limit(limit)
+    .sort({ createdAt: -1 })
+    .toArray();
+  
+  return {
+    data: articles,
+    total,
+    page,
+    limit,
+    totalPages: Math.ceil(total / limit)
+  };
+}
+```
+
+#### 条件查询
+
+```typescript
+async getArticlesByAuthor(authorId: string) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  const articles = await collection.find({ 
+    authorId 
+  }).toArray();
+  
+  return articles;
+}
+```
+
+### 更新(Update)
+
+#### 完整更新
+
+```typescript
+async updateArticle(id: string, data: any) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  const result = await collection.updateOne(
+    { _id: new this.mongoDBService.ObjectId(id) },
+    { 
+      $set: {
+        ...data,
+        updatedAt: new Date()
+      }
+    }
+  );
+  
+  if (result.matchedCount === 0) {
+    throw new Error('Article not found');
+  }
+  
+  return { success: true };
+}
+```
+
+#### 部分更新
+
+```typescript
+async updateArticleTitle(id: string, title: string) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  await collection.updateOne(
+    { _id: new this.mongoDBService.ObjectId(id) },
+    { 
+      $set: { 
+        title,
+        updatedAt: new Date()
+      }
+    }
+  );
+}
+```
+
+### 删除(Delete)
+
+```typescript
+async deleteArticle(id: string) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  const result = await collection.deleteOne({ 
+    _id: new this.mongoDBService.ObjectId(id) 
+  });
+  
+  if (result.deletedCount === 0) {
+    throw new Error('Article not found');
+  }
+  
+  return { success: true };
+}
+```
+
+## 高级查询
+
+### 复杂条件
+
+```typescript
+async searchArticles(query: string, options: any) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  // 构建查询条件
+  const conditions: any = {};
+  
+  if (query) {
+    conditions.$or = [
+      { title: { $regex: query, $options: 'i' } },
+      { content: { $regex: query, $options: 'i' } }
+    ];
+  }
+  
+  if (options.authorId) {
+    conditions.authorId = options.authorId;
+  }
+  
+  if (options.status) {
+    conditions.status = options.status;
+  }
+  
+  // 日期范围
+  if (options.startDate || options.endDate) {
+    conditions.createdAt = {};
+    if (options.startDate) {
+      conditions.createdAt.$gte = new Date(options.startDate);
+    }
+    if (options.endDate) {
+      conditions.createdAt.$lte = new Date(options.endDate);
+    }
+  }
+  
+  const articles = await collection.find(conditions).toArray();
+  
+  return articles;
+}
+```
+
+### 聚合管道
+
+```typescript
+async getArticleStats() {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  const stats = await collection.aggregate([
+    // 按作者分组
+    {
+      $group: {
+        _id: '$authorId',
+        articleCount: { $sum: 1 },
+        totalViews: { $sum: '$views' },
+        avgViews: { $avg: '$views' }
+      }
+    },
+    // 排序
+    {
+      $sort: { articleCount: -1 }
+    },
+    // 限制结果数
+    {
+      $limit: 10
+    }
+  ]).toArray();
+  
+  return stats;
+}
+```
+
+### 联表查询
+
+```typescript
+async getArticlesWithAuthors() {
+  const db = this.mongodbService.getDb();
+  const articlesCollection = db.collection('articles');
+  const usersCollection = db.collection('users');
+  
+  const articles = await articlesCollection.aggregate([
+    // 联查用户表
+    {
+      $lookup: {
+        from: 'users',
+        localField: 'authorId',
+        foreignField: '_id',
+        as: 'author'
+      }
+    },
+    // 展开数组
+    {
+      $unwind: '$author'
+    },
+    // 投影字段
+    {
+      $project: {
+        title: 1,
+        content: 1,
+        createdAt: 1,
+        'author.name': 1,
+        'author.email': 1
+      }
+    }
+  ]).toArray();
+  
+  return articles;
+}
+```
+
+## 索引优化
+
+### 创建索引
+
+```typescript
+async createIndexes() {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  // 单字段索引
+  await collection.createIndex({ authorId: 1 });
+  
+  // 复合索引
+  await collection.createIndex({ authorId: 1, createdAt: -1 });
+  
+  // 文本索引(用于全文搜索)
+  await collection.createIndex({ 
+    title: 'text', 
+    content: 'text' 
+  });
+  
+  // 唯一索引
+  await collection.createIndex({ slug: 1 }, { unique: true });
+}
+```
+
+### 使用索引
+
+```typescript
+// MongoDB 会自动使用合适的索引
+async getArticlesByAuthor(authorId: string) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  // 自动使用 authorId 索引
+  return await collection.find({ authorId }).toArray();
+}
+```
+
+## 事务处理
+
+### 使用事务
+
+```typescript
+async transferArticleAuthor(articleId: string, newAuthorId: string) {
+  const db = this.mongodbService.getDb();
+  const session = db.startSession();
+  
+  try {
+    session.startTransaction();
+    
+    const articlesCollection = db.collection('articles');
+    const usersCollection = db.collection('users');
+    
+    // 检查新作者是否存在
+    const user = await usersCollection.findOne(
+      { _id: new this.mongoDBService.ObjectId(newAuthorId) },
+      { session }
+    );
+    
+    if (!user) {
+      throw new Error('User not found');
+    }
+    
+    // 更新文章作者
+    await articlesCollection.updateOne(
+      { _id: new this.mongoDBService.ObjectId(articleId) },
+      { $set: { authorId: newAuthorId } },
+      { session }
+    );
+    
+    // 提交事务
+    await session.commitTransaction();
+    
+    return { success: true };
+  } catch (error) {
+    // 回滚事务
+    await session.abortTransaction();
+    throw error;
+  } finally {
+    session.endSession();
+  }
+}
+```
+
+## 数据验证
+
+### Schema 验证
+
+```typescript
+async createArticle(data: any) {
+  // 验证必填字段
+  if (!data.title || !data.content) {
+    throw new Error('Title and content are required');
+  }
+  
+  // 验证标题长度
+  if (data.title.length > 200) {
+    throw new Error('Title too long');
+  }
+  
+  // 验证内容长度
+  if (data.content.length > 50000) {
+    throw new Error('Content too long');
+  }
+  
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  return await collection.insertOne({
+    title: data.title.trim(),
+    content: data.content.trim(),
+    authorId: data.authorId,
+    status: 'draft',
+    createdAt: new Date(),
+    updatedAt: new Date()
+  });
+}
+```
+
+## 最佳实践
+
+### 1. 错误处理
+
+```typescript
+async safeOperation() {
+  try {
+    const db = this.mongodbService.getDb();
+    const collection = db.collection('articles');
+    
+    const result = await collection.insertOne({ /* ... */ });
+    return result;
+  } catch (error) {
+    console.error('Database operation failed:', error);
+    throw new Error('Failed to save article');
+  }
+}
+```
+
+### 2. 连接池管理
+
+MongoDB 驱动会自动管理连接池,无需手动处理。
+
+### 3. 避免 N+1 查询
+
+```typescript
+// ❌ 糟糕的做法 - N+1 查询
+async getArticlesWithAuthors() {
+  const articles = await collection.find().toArray();
+  
+  for (const article of articles) {
+    article.author = await usersCollection.findOne({ 
+      _id: article.authorId 
+    });
+  }
+  
+  return articles;
+}
+
+// ✅ 好的做法 - 使用聚合
+async getArticlesWithAuthors() {
+  return await collection.aggregate([
+    {
+      $lookup: {
+        from: 'users',
+        localField: 'authorId',
+        foreignField: '_id',
+        as: 'author'
+      }
+    },
+    { $unwind: '$author' }
+  ]).toArray();
+}
+```
+
+### 4. 分页优化
+
+```typescript
+async getArticlesPaginated(page: number, limit: number) {
+  const db = this.mongodbService.getDb();
+  const collection = db.collection('articles');
+  
+  // 使用游标分页(更高效)
+  const skip = (page - 1) * limit;
+  
+  return await collection.find()
+    .skip(skip)
+    .limit(limit)
+    .sort({ createdAt: -1 })
+    .toArray();
+}
+```
+
+### 5. 数据缓存
+
+```typescript
+import NodeCache from 'node-cache';
+
+const cache = new NodeCache({ stdTTL: 300 }); // 5分钟缓存
+
+async getCachedArticle(id: string) {
+  // 检查缓存
+  const cached = cache.get(id);
+  if (cached) {
+    return cached;
+  }
+  
+  // 从数据库获取
+  const article = await this.getArticleById(id);
+  
+  // 存入缓存
+  cache.set(id, article);
+  
+  return article;
+}
+```
+
+## 完整示例
+
+查看博客插件中的数据持久化实现:
+
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/src/server/services/ArticleService.ts)
+
+## 相关文档
+
+- 🔒 [权限管理](./permissions.md)
+- 🎨 [UI 扩展插槽](./ui-slots.md)
+
+---
+
+**上一篇**: [权限管理](./permissions.md) | **下一篇**: [最佳实践](../best-practices/naming-conventions.md)