@linyjs/plugin-docs 0.1.0

package/docs/guides/data-persistence.md

@@ -0,0 +1,536 @@
+# 数据持久化
+
+本指南介绍如何在 linyjs 插件中使用 MongoDB 进行数据持久化。
+
+## 概述
+
+linyjs 提供 MongoDB 服务,支持:
+
+- 💾 CRUD 操作(创建、读取、更新、删除)
+- 🔍 复杂查询和聚合
+- 📊 索引优化
+- 🔗 数据关联
+
+## 配置 MongoDB 服务
+
+### 在服务端模块中注入依赖
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['mongodb'],  // 依赖 MongoDB 模块
+  serviceDefs: [
+    {
+      serviceTag: 'articleService',
+      serviceImpl: ArticleService,
+      dependencies: ['mongodb.mongodb'],  // 注入 MongoDB 服务
+      meta: { usageType: 'normal_service' }
+    }
+  ]
+};
+```
+
+## 基本 CRUD 操作
+
+### 创建(Create)
+
+```typescript
+import type { IMongoDBService } from '@linyjs/mongodb';
+
+class ArticleService {
+  constructor(private mongodb: IMongoDBService) {}
+  
+  async createArticle(data: any) {
+    const db = this.mongodb.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
+async getArticleById(id: string) {
+  const db = this.mongodb.getDb();
+  const collection = db.collection('articles');
+  
+  const article = await collection.findOne({ 
+    _id: new ObjectId(id) 
+  });
+  
+  if (!article) {
+    throw new Error('Article not found');
+  }
+  
+  return article;
+}
+```
+
+#### 获取列表(支持分页)
+
+```typescript
+async getArticles(page = 1, limit = 10) {
+  const db = this.mongodb.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.mongodb.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.mongodb.getDb();
+  const collection = db.collection('articles');
+  
+  const result = await collection.updateOne(
+    { _id: new 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.mongodb.getDb();
+  const collection = db.collection('articles');
+  
+  await collection.updateOne(
+    { _id: new ObjectId(id) },
+    { 
+      $set: { 
+        title,
+        updatedAt: new Date()
+      }
+    }
+  );
+}
+```
+
+### 删除(Delete)
+
+```typescript
+async deleteArticle(id: string) {
+  const db = this.mongodb.getDb();
+  const collection = db.collection('articles');
+  
+  const result = await collection.deleteOne({ 
+    _id: new 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.mongodb.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.mongodb.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.mongodb.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.mongodb.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.mongodb.getDb();
+  const collection = db.collection('articles');
+  
+  // 自动使用 authorId 索引
+  return await collection.find({ authorId }).toArray();
+}
+```
+
+## 事务处理
+
+### 使用事务
+
+```typescript
+async transferArticleAuthor(articleId: string, newAuthorId: string) {
+  const db = this.mongodb.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 ObjectId(newAuthorId) },
+      { session }
+    );
+    
+    if (!user) {
+      throw new Error('User not found');
+    }
+    
+    // 更新文章作者
+    await articlesCollection.updateOne(
+      { _id: new 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.mongodb.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.mongodb.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.mongodb.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)