@linyjs/plugin-docs 0.0.13

package/docs/guides/server-module.md

@@ -0,0 +1,377 @@
+# 服务端模块开发
+
+本指南详细介绍如何开发 linyjs 插件的服务端模块。
+
+## 概述
+
+服务端模块负责:
+
+- 🌐 定义 API 路由和控制器
+- 🔧 处理业务逻辑
+- 💾 数据持久化(与数据库交互)
+- 🔒 权限验证和安全控制
+- ⏰ 定时任务
+
+## 模块结构
+
+一个完整的服务端模块包含:
+
+```typescript
+import type { IModule } from '@linyjs/server-module-interface';
+
+export const myServerModule: IModule = {
+  name: 'myServer',
+  moduleDependencies: ['logger'],  // 依赖的其他模块
+  serviceDefs: [
+    controllerDef,      // 控制器(API路由)
+    middlewareDef,      // 中间件
+    cronDef,            // 定时任务
+    serviceDef          // 普通服务
+  ]
+};
+```
+
+## 控制器(Controller)
+
+控制器用于定义 HTTP API 端点。
+
+### 基本示例
+
+```typescript
+import type { IControllerService } from '@linyjs/server-module-interface';
+
+class MyController implements IControllerService {
+  getRoutes() {
+    return [
+      {
+        method: 'GET',
+        path: '/api/items',
+        middlewares: [],
+        responseType: 'json',
+        handler: async (params, ctx) => {
+          return { items: [] };
+        }
+      }
+    ];
+  }
+}
+
+export const controllerDef = {
+  serviceTag: 'myController',
+  serviceImpl: MyController,
+  meta: { usageType: 'controller' }
+};
+```
+
+### HTTP 方法
+
+支持所有标准 HTTP 方法:
+
+```typescript
+method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'
+```
+
+### 路由参数
+
+```typescript
+// 路径参数: /api/items/:id
+{
+  path: '/api/items/:id',
+  handler: async (params) => {
+    const id = params.id;  // 从 URL 获取
+  }
+}
+
+// 查询参数: /api/items?page=1&limit=10
+{
+  path: '/api/items',
+  handler: async (params) => {
+    const page = params.query?.page;
+    const limit = params.query?.limit;
+  }
+}
+
+// 请求体: POST /api/items with JSON body
+{
+  method: 'POST',
+  path: '/api/items',
+  handler: async (params) => {
+    const { name, description } = params.body;
+  }
+}
+```
+
+### 响应类型
+
+框架支持三种响应类型:
+
+#### 1. JSON 响应(默认)
+
+```typescript
+{
+  responseType: 'json',
+  handler: async () => {
+    return { message: 'Hello' };  // 自动序列化为 JSON
+  }
+}
+```
+
+#### 2. 文件下载
+
+```typescript
+{
+  responseType: 'file',
+  handler: async () => {
+    return {
+      filePath: '/path/to/file.pdf',
+      filename: 'document.pdf',
+      contentType: 'application/pdf'
+    };
+  }
+}
+```
+
+#### 3. 视频流
+
+```typescript
+{
+  responseType: 'video_stream',
+  handler: async (params) => {
+    const stream = fs.createReadStream(`/videos/${params.id}.mp4`);
+    return stream;  // 支持 range 请求
+  }
+}
+```
+
+### 中间件
+
+中间件用于请求预处理(如认证、日志):
+
+```typescript
+{
+  path: '/api/protected',
+  middlewares: ['auth'],  // 使用名为 'auth' 的中间件
+  handler: async (params, ctx) => {
+    // ctx.user 由中间件设置
+    const user = ctx.user;
+  }
+}
+```
+
+## 中间件(Middleware)
+
+中间件在请求到达控制器之前执行。
+
+### 创建中间件
+
+```typescript
+import type { IMiddlewareService } from '@linyjs/server-module-interface';
+
+class AuthMiddleware implements IMiddlewareService {
+  getMiddlewares() {
+    return [{
+      middlewareId: 'auth',
+      handler: async (params, ctx, next) => {
+        const token = params.headers.authorization?.replace('Bearer ', '');
+        
+        if (!token) {
+          throw new Error('Unauthorized');
+        }
+        
+        // 验证 token...
+        ctx.user = decodedUser;
+        
+        await next();  // 继续处理请求
+      }
+    }];
+  }
+}
+
+export const middlewareDef = {
+  serviceTag: 'authMiddleware',
+  serviceImpl: AuthMiddleware,
+  meta: { usageType: 'middleware' }
+};
+```
+
+## 定时任务(Cron)
+
+定时任务按预定时间间隔执行。
+
+### 创建定时任务
+
+```typescript
+import type { ICronService } from '@linyjs/server-module-interface';
+
+class CleanupCron implements ICronService {
+  getCronJobs() {
+    return [{
+      name: 'cleanup-old-data',
+      schedule: '0 0 * * *',  // 每天午夜执行
+      run: async () => {
+        console.log('Cleaning up old data...');
+        // 清理逻辑...
+      }
+    }];
+  }
+}
+
+export const cronDef = {
+  serviceTag: 'cleanupCron',
+  serviceImpl: CleanupCron,
+  meta: { usageType: 'cron' }
+};
+```
+
+### Cron 表达式格式
+
+```
+┌───────────── 分钟 (0 - 59)
+│ ┌───────────── 小时 (0 - 23)
+│ │ ┌───────────── 日期 (1 - 31)
+│ │ │ ┌───────────── 月份 (1 - 12)
+│ │ │ │ ┌───────────── 星期几 (0 - 7, 0 和 7 都是周日)
+│ │ │ │ │
+* * * * *
+```
+
+常用示例:
+
+- `*/5 * * * *` - 每 5 分钟
+- `0 */2 * * *` - 每 2 小时
+- `0 0 * * 0` - 每周日午夜
+- `0 0 1 * *` - 每月 1 号午夜
+
+## 依赖注入
+
+服务之间可以通过依赖注入互相引用。
+
+### 声明依赖
+
+```typescript
+export const myServiceDef = {
+  serviceTag: 'myService',
+  serviceImpl: MyService,
+  dependencies: ['otherService'],  // 依赖其他服务
+  meta: { usageType: 'normal_service' }
+};
+```
+
+### 使用依赖
+
+```typescript
+class MyService {
+  constructor(private otherService: any) {}
+  
+  async doSomething() {
+    // 使用依赖的服务
+    const result = await this.otherService.someMethod();
+    return result;
+  }
+}
+```
+
+## 错误处理
+
+### 返回错误响应
+
+```typescript
+handler: async (params, ctx) => {
+  try {
+    // 业务逻辑
+    const data = await fetchData();
+    return { success: true, data };
+  } catch (error) {
+    return {
+      status: 500,
+      data: { error: error.message }
+    };
+  }
+}
+```
+
+### 抛出异常
+
+```typescript
+handler: async (params, ctx) => {
+  if (!params.body.name) {
+    throw new Error('Name is required');  // 自动返回 400
+  }
+}
+```
+
+## 最佳实践
+
+### 0. 遵循 ServiceDef 代码风格规范
+
+> 📐 **重要**: 请阅读 [ServiceDef 代码风格规范](../best-practices/service-definition.md)，了解两条核心规则：
+> 1. ServiceDef 必须声明为独立变量，禁止内联在 `serviceDefs` 数组中
+> 2. ServiceDef 声明必须与实现类放在同一个文件中
+
+### 1. 分离关注点
+
+```
+src/server/
+├── controllers/     # API 路由定义
+├── services/        # 业务逻辑
+├── models/          # 数据模型
+└── middlewares/     # 中间件
+```
+
+### 2. 使用 TypeScript 类型
+
+```typescript
+interface CreateItemRequest {
+  name: string;
+  description?: string;
+}
+
+handler: async (params: { body: CreateItemRequest }) => {
+  const { name, description } = params.body;
+}
+```
+
+### 3. 输入验证
+
+```typescript
+handler: async (params) => {
+  const { email } = params.body;
+  
+  if (!isValidEmail(email)) {
+    return {
+      status: 400,
+      data: { error: 'Invalid email format' }
+    };
+  }
+}
+```
+
+### 4. 日志记录
+
+```typescript
+class MyController {
+  constructor(private logger: any) {}
+  
+  handler: async (params) => {
+    this.logger.info('Processing request...');
+    // ...
+  }
+}
+```
+
+## 完整示例
+
+查看完整示例:
+
+- 📁 [Hello World 示例](../../examples/hello-world/src/server/index.ts)
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/src/server/index.ts)
+
+## 下一步
+
+- 💻 阅读 [客户端模块开发](./client-module.md)
+- 💾 阅读 [数据持久化](./data-persistence.md)
+- 🔒 阅读 [权限管理](./permissions.md)
+
+---
+
+**上一篇**: [第一个插件教程](../getting-started/first-plugin.md) | **下一篇**: [客户端模块开发](./client-module.md)