create-dp-koa 1.0.0

package/template/docs/DEVELOPMENT_GUIDE.md

@@ -0,0 +1,1097 @@
+# 开发指南
+
+本指南提供 DP-Koa Framework 的详细开发规范和最佳实践，帮助开发者快速上手并遵循统一的开发标准。
+
+## 📋 目录
+
+- [项目架构](#项目架构)
+- [开发环境设置](#开发环境设置)
+- [代码规范](#代码规范)
+- [注解系统使用](#注解系统使用)
+- [控制器开发](#控制器开发)
+- [服务层开发](#服务层开发)
+- [数据实体设计](#数据实体设计)
+- [拦截器使用](#拦截器使用)
+- [测试开发](#测试开发)
+- [调试技巧](#调试技巧)
+- [性能优化](#性能优化)
+- [最佳实践](#最佳实践)
+
+## 🏗️ 项目架构
+
+### 整体架构
+
+```
+src/
+├── app.ts                 # 应用入口
+├── controllers/           # 控制器层
+│   ├── base.controller.ts # 基础控制器
+│   └── example/          # 示例控制器
+├── service/              # 服务层
+│   ├── base.service.ts   # 基础服务
+│   └── *.service.ts      # 业务服务
+├── entity/               # 数据实体
+├── framework/            # 框架核心
+│   ├── decorator/        # 装饰器系统
+│   ├── interceptors/    # 拦截器
+│   └── utils/           # 工具函数
+├── middlewares/          # 中间件
+├── repository/          # 数据仓库
+└── utils/               # 业务工具
+```
+
+### 分层架构
+
+```
+┌─────────────────┐
+│   Controllers   │  ← HTTP 请求处理
+├─────────────────┤
+│   Services      │  ← 业务逻辑
+├─────────────────┤
+│   Repository    │  ← 数据访问
+├─────────────────┤
+│   Entities      │  ← 数据模型
+└─────────────────┘
+```
+
+## 🔧 开发环境设置
+
+### 1. IDE 配置
+
+推荐使用 **VS Code** 并安装以下插件：
+
+```json
+{
+  "recommendations": [
+    "ms-vscode.vscode-typescript-next",
+    "bradlc.vscode-tailwindcss",
+    "esbenp.prettier-vscode",
+    "ms-vscode.vscode-eslint",
+    "ms-vscode.vscode-jest"
+  ]
+}
+```
+
+### 2. VS Code 设置
+
+创建 `.vscode/settings.json`：
+
+```json
+{
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  },
+  "typescript.suggest.autoImports": true,
+  "files.exclude": {
+    "**/node_modules": true,
+    "**/dist": true,
+    "**/coverage": true
+  }
+}
+```
+
+### 3. 调试配置
+
+创建 `.vscode/launch.json`：
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "启动应用",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/src/app.ts",
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "env": {
+        "NODE_ENV": "development"
+      },
+      "console": "integratedTerminal",
+      "restart": true,
+      "protocol": "inspector"
+    },
+    {
+      "name": "运行测试",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": ["--runInBand"],
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    }
+  ]
+}
+```
+
+## 📝 代码规范
+
+### 1. TypeScript 规范
+
+#### 命名规范
+
+```typescript
+// 类名：PascalCase
+export class UserService extends BaseService {}
+
+// 接口名：PascalCase，以 I 开头
+export interface IUserRepository {}
+
+// 枚举名：PascalCase
+export enum UserStatus {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive'
+}
+
+// 变量和函数：camelCase
+const userName = 'john';
+function getUserById(id: number) {}
+
+// 常量：UPPER_SNAKE_CASE
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://api.example.com';
+
+// 文件名：kebab-case
+// user-service.ts
+// user-controller.ts
+```
+
+#### 类型定义
+
+```typescript
+// 使用接口定义对象结构
+interface UserCreateRequest {
+  name: string;
+  email: string;
+  age?: number; // 可选属性
+}
+
+// 使用类型别名
+type UserId = number;
+type UserStatus = 'active' | 'inactive' | 'pending';
+
+// 泛型约束
+interface Repository<T extends BaseEntity> {
+  findById(id: number): Promise<T | null>;
+  save(entity: T): Promise<T>;
+}
+```
+
+#### 错误处理
+
+```typescript
+// 使用 Result 模式
+export class ServiceResult<T> {
+  constructor(
+    public success: boolean,
+    public data?: T,
+    public error?: string,
+    public code?: number
+  ) {}
+}
+
+// 在服务中使用
+async getUserById(id: number): Promise<ServiceResult<User>> {
+  try {
+    const user = await this.userRepository.findById(id);
+    if (!user) {
+      return new ServiceResult(false, undefined, '用户不存在', 404);
+    }
+    return new ServiceResult(true, user);
+  } catch (error) {
+    return new ServiceResult(false, undefined, error.message, 500);
+  }
+}
+```
+
+### 2. 注释规范
+
+```typescript
+/**
+ * 用户服务类
+ * 提供用户相关的业务逻辑处理
+ * 
+ * @example
+ * ```typescript
+ * const userService = new UserService();
+ * const result = await userService.createUser(userData);
+ * ```
+ */
+export class UserService extends BaseService {
+  
+  /**
+   * 根据ID获取用户信息
+   * 
+   * @param id 用户ID
+   * @returns Promise<ServiceResult<User>> 用户信息或错误
+   * 
+   * @example
+   * ```typescript
+   * const result = await userService.getUserById(1);
+   * if (result.success) {
+   *   console.log(result.data);
+   * }
+   * ```
+   */
+  async getUserById(id: number): Promise<ServiceResult<User>> {
+    // 实现逻辑
+  }
+}
+```
+
+### 3. 导入规范
+
+```typescript
+// 1. Node.js 内置模块
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+// 2. 第三方库
+import { Injectable } from 'dp-ioc';
+import { Entity, Column } from 'typeorm';
+
+// 3. 项目内部模块（按路径排序）
+import { BaseService } from '@src/service/base.service';
+import { UserEntity } from '@src/entity/user.entity';
+import { UserRepository } from '@src/repository/user.repository';
+
+// 4. 相对路径导入
+import { UserDto } from './user.dto';
+import { UserValidator } from './user.validator';
+```
+
+## 🎯 注解系统使用
+
+### 1. 控制器注解
+
+```typescript
+import { Get, Post, Put, Delete, Body, Query, Params } from '@src/framework/decorator';
+import { Api, ApiTags, ApiResponse } from '@src/framework/decorator/swagger';
+
+@ApiTags('用户管理')
+export class UserController extends BaseController {
+  
+  /**
+   * 获取用户列表
+   */
+  @Get('/users')
+  @Api({
+    summary: '获取用户列表',
+    description: '分页获取用户列表，支持搜索和过滤'
+  })
+  @ApiResponse({
+    status: 200,
+    description: '成功返回用户列表'
+  })
+  async getUsers(
+    @Query() query: { page?: number; size?: number; search?: string }
+  ) {
+    // 实现逻辑
+  }
+
+  /**
+   * 创建用户
+   */
+  @Post('/users')
+  @Api({
+    summary: '创建用户',
+    description: '创建新用户'
+  })
+  @ApiResponse({
+    status: 201,
+    description: '用户创建成功'
+  })
+  async createUser(@Body() userData: UserCreateRequest) {
+    // 实现逻辑
+  }
+}
+```
+
+### 2. 服务注解
+
+```typescript
+import { Injectable } from 'dp-ioc';
+import { Logging, PerformanceMonitor } from '@src/annotations/decorators';
+
+@Injectable()
+export class UserService extends BaseService {
+  
+  /**
+   * 获取用户信息（带性能监控）
+   */
+  @PerformanceMonitor({ maxExecutionTime: 100 })
+  @Logging()
+  async getUserById(id: number): Promise<ServiceResult<User>> {
+    // 实现逻辑
+  }
+}
+```
+
+### 3. 权限注解
+
+```typescript
+import { Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
+
+export class AdminController extends BaseController {
+  
+  @Get('/admin/users')
+  @Permission({ requiredPermission: 'admin:read' })
+  @RateLimit({ maxRequests: 10, windowMs: 60000 })
+  async getAdminUsers() {
+    // 管理员专用接口
+  }
+}
+```
+
+## 🎮 控制器开发
+
+### 1. 基础控制器结构
+
+```typescript
+import { Get, Post, Body, Query, Params } from '@src/framework/decorator';
+import { Api, ApiTags } from '@src/framework/decorator/swagger';
+import { BaseController } from '@src/controllers/base.controller';
+import { UserService } from '@src/service/user.service';
+import { Injectable } from 'dp-ioc';
+
+@ApiTags('用户管理')
+@Injectable()
+export class UserController extends BaseController {
+  
+  constructor(private userService: UserService) {
+    super();
+  }
+
+  @Get('/users')
+  @Api({ summary: '获取用户列表' })
+  async getUsers(@Query() query: any) {
+    try {
+      const result = await this.userService.getUsers(query);
+      return this.success(result.data, '获取用户列表成功');
+    } catch (error) {
+      return this.fail(500, error.message);
+    }
+  }
+
+  @Post('/users')
+  @Api({ summary: '创建用户' })
+  async createUser(@Body() userData: any) {
+    try {
+      const result = await this.userService.createUser(userData);
+      if (result.success) {
+        return this.success(result.data, '用户创建成功');
+      } else {
+        return this.fail(result.code || 400, result.error);
+      }
+    } catch (error) {
+      return this.fail(500, error.message);
+    }
+  }
+}
+```
+
+### 2. 参数验证
+
+```typescript
+import { IsString, IsEmail, IsOptional, IsNumber } from 'class-validator';
+
+export class CreateUserDto {
+  @IsString()
+  @IsOptional()
+  name?: string;
+
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  password: string;
+
+  @IsNumber()
+  @IsOptional()
+  age?: number;
+}
+
+export class UserController extends BaseController {
+  
+  @Post('/users')
+  async createUser(@Body() userData: CreateUserDto) {
+    // userData 已经过验证
+  }
+}
+```
+
+### 3. 错误处理
+
+```typescript
+export class UserController extends BaseController {
+  
+  @Get('/users/:id')
+  async getUserById(@Params() params: { id: string }) {
+    try {
+      const id = parseInt(params.id);
+      if (isNaN(id)) {
+        return this.fail(400, '无效的用户ID');
+      }
+
+      const result = await this.userService.getUserById(id);
+      if (!result.success) {
+        return this.fail(result.code || 404, result.error);
+      }
+
+      return this.success(result.data);
+    } catch (error) {
+      this.logger.error('获取用户失败', error);
+      return this.fail(500, '服务器内部错误');
+    }
+  }
+}
+```
+
+## 🔧 服务层开发
+
+### 1. 基础服务结构
+
+```typescript
+import { Injectable } from 'dp-ioc';
+import { BaseService } from '@src/service/base.service';
+import { UserEntity } from '@src/entity/user.entity';
+import { UserRepository } from '@src/repository/user.repository';
+import { ServiceResult } from '@src/framework/types/ServiceResult';
+
+@Injectable()
+export class UserService extends BaseService {
+  private repositoryCache = new Map<string, any>();
+
+  private get userRepository(): UserRepository {
+    return this.createLazyRepository(
+      UserEntity,
+      UserRepository,
+      this.repositoryCache
+    );
+  }
+
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    try {
+      const user = await this.userRepository.findById(id);
+      if (!user) {
+        return new ServiceResult(false, undefined, '用户不存在', 404);
+      }
+      return new ServiceResult(true, user);
+    } catch (error) {
+      return new ServiceResult(false, undefined, error.message, 500);
+    }
+  }
+
+  async createUser(userData: Partial<UserEntity>): Promise<ServiceResult<UserEntity>> {
+    try {
+      // 验证数据
+      const validationResult = this.validateUserData(userData);
+      if (!validationResult.valid) {
+        return new ServiceResult(false, undefined, validationResult.error, 400);
+      }
+
+      // 检查邮箱是否已存在
+      const existingUser = await this.userRepository.findByEmail(userData.email);
+      if (existingUser) {
+        return new ServiceResult(false, undefined, '邮箱已存在', 409);
+      }
+
+      // 创建用户
+      const user = await this.userRepository.create(userData);
+      return new ServiceResult(true, user);
+    } catch (error) {
+      return new ServiceResult(false, undefined, error.message, 500);
+    }
+  }
+
+  private validateUserData(userData: Partial<UserEntity>): { valid: boolean; error?: string } {
+    if (!userData.email) {
+      return { valid: false, error: '邮箱不能为空' };
+    }
+    if (!userData.password) {
+      return { valid: false, error: '密码不能为空' };
+    }
+    return { valid: true };
+  }
+}
+```
+
+### 2. 事务处理
+
+```typescript
+import { transactionManager } from '@src/framework/utils/TransactionManager';
+
+export class UserService extends BaseService {
+  
+  async createUserWithProfile(userData: any, profileData: any): Promise<ServiceResult<any>> {
+    return await transactionManager.runTransaction(async (manager) => {
+      try {
+        // 创建用户
+        const user = await manager.save(UserEntity, userData);
+        
+        // 创建用户资料
+        const profile = await manager.save(UserProfileEntity, {
+          ...profileData,
+          userId: user.id
+        });
+
+        return new ServiceResult(true, { user, profile });
+      } catch (error) {
+        throw error; // 事务会自动回滚
+      }
+    });
+  }
+}
+```
+
+### 3. 缓存使用
+
+```typescript
+import { cacheManager } from '@src/framework/utils/CacheManager';
+
+export class UserService extends BaseService {
+  
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    // 尝试从缓存获取
+    const cacheKey = `user:${id}`;
+    const cachedUser = await cacheManager.get<UserEntity>(cacheKey);
+    
+    if (cachedUser) {
+      return new ServiceResult(true, cachedUser);
+    }
+
+    // 从数据库获取
+    const result = await this.userRepository.findById(id);
+    if (result.success && result.data) {
+      // 缓存结果
+      await cacheManager.set(cacheKey, result.data, 3600); // 1小时
+    }
+
+    return result;
+  }
+}
+```
+
+## 🗄️ 数据实体设计
+
+### 1. 基础实体
+
+```typescript
+import { Entity, Column, CreateDateColumn, UpdateDateColumn, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity()
+export class BaseEntity {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @Column({ default: true })
+  isActive: boolean;
+}
+```
+
+### 2. 业务实体
+
+```typescript
+import { Entity, Column, OneToMany, OneToOne, JoinColumn } from 'typeorm';
+import { BaseEntity } from '@src/entity/base.entity';
+
+@Entity('users')
+export class UserEntity extends BaseEntity {
+  
+  @Column({ length: 100 })
+  name: string;
+
+  @Column({ unique: true })
+  email: string;
+
+  @Column()
+  password: string;
+
+  @Column({ nullable: true })
+  avatar?: string;
+
+  @Column({ default: 'active' })
+  status: string;
+
+  // 关系定义
+  @OneToOne(() => UserProfileEntity, profile => profile.user)
+  @JoinColumn()
+  profile: UserProfileEntity;
+
+  @OneToMany(() => OrderEntity, order => order.user)
+  orders: OrderEntity[];
+}
+```
+
+### 3. 枚举使用
+
+```typescript
+export enum UserStatus {
+  ACTIVE = 'active',
+  INACTIVE = 'inactive',
+  PENDING = 'pending',
+  SUSPENDED = 'suspended'
+}
+
+export enum UserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+  MODERATOR = 'moderator'
+}
+
+@Entity('users')
+export class UserEntity extends BaseEntity {
+  
+  @Column({
+    type: 'enum',
+    enum: UserStatus,
+    default: UserStatus.ACTIVE
+  })
+  status: UserStatus;
+
+  @Column({
+    type: 'enum',
+    enum: UserRole,
+    default: UserRole.USER
+  })
+  role: UserRole;
+}
+```
+
+## 🔄 拦截器使用
+
+### 1. 服务调用拦截器
+
+```typescript
+import { ServiceCallInterceptor } from '@src/framework/interceptors';
+
+export class UserService extends BaseService {
+  
+  @ServiceCallInterceptor({
+    logCalls: true,
+    measurePerformance: true,
+    retryOnFailure: true,
+    maxRetries: 3
+  })
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    // 服务实现
+  }
+}
+```
+
+### 2. 自定义拦截器
+
+```typescript
+import { Interceptor, InterceptorContext, InterceptorResult } from '@src/framework/interceptors';
+
+export class LoggingInterceptor implements Interceptor {
+  async intercept(context: InterceptorContext, next: () => Promise<InterceptorResult>): Promise<InterceptorResult> {
+    const startTime = Date.now();
+    
+    try {
+      const result = await next();
+      const duration = Date.now() - startTime;
+      
+      console.log(`方法 ${context.methodName} 执行成功，耗时: ${duration}ms`);
+      return result;
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      console.error(`方法 ${context.methodName} 执行失败，耗时: ${duration}ms`, error);
+      throw error;
+    }
+  }
+}
+```
+
+## 🧪 测试开发
+
+### 1. 单元测试
+
+```typescript
+import { UserService } from '@src/service/user.service';
+import { UserRepository } from '@src/repository/user.repository';
+
+describe('UserService', () => {
+  let userService: UserService;
+  let mockUserRepository: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockUserRepository = {
+      findById: jest.fn(),
+      create: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn()
+    } as any;
+
+    userService = new UserService();
+    // 注入 mock repository
+  });
+
+  describe('getUserById', () => {
+    it('应该返回用户信息', async () => {
+      // Arrange
+      const userId = 1;
+      const mockUser = { id: 1, name: 'John', email: 'john@example.com' };
+      mockUserRepository.findById.mockResolvedValue(mockUser);
+
+      // Act
+      const result = await userService.getUserById(userId);
+
+      // Assert
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual(mockUser);
+      expect(mockUserRepository.findById).toHaveBeenCalledWith(userId);
+    });
+
+    it('应该处理用户不存在的情况', async () => {
+      // Arrange
+      const userId = 999;
+      mockUserRepository.findById.mockResolvedValue(null);
+
+      // Act
+      const result = await userService.getUserById(userId);
+
+      // Assert
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('用户不存在');
+      expect(result.code).toBe(404);
+    });
+  });
+});
+```
+
+### 2. 集成测试
+
+```typescript
+import request from 'supertest';
+import { app } from '@src/app';
+
+describe('User API', () => {
+  describe('GET /api/users/:id', () => {
+    it('应该返回用户信息', async () => {
+      const response = await request(app)
+        .get('/api/users/1')
+        .expect(200);
+
+      expect(response.body.success).toBe(true);
+      expect(response.body.data).toHaveProperty('id');
+      expect(response.body.data).toHaveProperty('name');
+    });
+
+    it('应该处理无效的用户ID', async () => {
+      const response = await request(app)
+        .get('/api/users/invalid')
+        .expect(400);
+
+      expect(response.body.success).toBe(false);
+      expect(response.body.error).toBe('无效的用户ID');
+    });
+  });
+});
+```
+
+### 3. 测试工具
+
+```typescript
+// test/utils/test-helpers.ts
+export class TestHelpers {
+  static async createTestUser(userData: Partial<UserEntity> = {}): Promise<UserEntity> {
+    const defaultData = {
+      name: 'Test User',
+      email: `test-${Date.now()}@example.com`,
+      password: 'password123',
+      ...userData
+    };
+
+    return await userRepository.create(defaultData);
+  }
+
+  static async cleanupTestData(): Promise<void> {
+    await userRepository.delete({ email: /test-.*@example\.com/ });
+  }
+}
+```
+
+## 🐛 调试技巧
+
+### 1. 日志调试
+
+```typescript
+import { logger } from '@src/framework/utils/logger';
+
+export class UserService extends BaseService {
+  
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    logger.debug('开始获取用户信息', { userId: id });
+    
+    try {
+      const user = await this.userRepository.findById(id);
+      
+      if (!user) {
+        logger.warn('用户不存在', { userId: id });
+        return new ServiceResult(false, undefined, '用户不存在', 404);
+      }
+
+      logger.info('用户信息获取成功', { userId: id, userName: user.name });
+      return new ServiceResult(true, user);
+    } catch (error) {
+      logger.error('获取用户信息失败', { userId: id, error: error.message });
+      return new ServiceResult(false, undefined, error.message, 500);
+    }
+  }
+}
+```
+
+### 2. 性能调试
+
+```typescript
+import { PerformanceMonitor } from '@src/annotations/decorators';
+
+export class UserService extends BaseService {
+  
+  @PerformanceMonitor({ 
+    maxExecutionTime: 1000, // 1秒
+    logSlowQueries: true 
+  })
+  async getUsersWithComplexQuery(query: any): Promise<ServiceResult<UserEntity[]>> {
+    // 复杂查询逻辑
+  }
+}
+```
+
+### 3. 断点调试
+
+```typescript
+// 在 VS Code 中设置断点
+export class UserService extends BaseService {
+  
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    debugger; // 断点
+    
+    const user = await this.userRepository.findById(id);
+    // 在这里可以检查变量值
+    
+    return new ServiceResult(true, user);
+  }
+}
+```
+
+## ⚡ 性能优化
+
+### 1. 数据库优化
+
+```typescript
+// 使用索引
+@Entity('users')
+export class UserEntity extends BaseEntity {
+  
+  @Column()
+  @Index() // 添加索引
+  email: string;
+
+  @Column()
+  @Index(['status', 'createdAt']) // 复合索引
+  status: string;
+}
+
+// 使用查询优化
+export class UserService extends BaseService {
+  
+  async getUsersWithPagination(page: number, size: number): Promise<ServiceResult<UserEntity[]>> {
+    const users = await this.userRepository
+      .createQueryBuilder('user')
+      .select(['user.id', 'user.name', 'user.email']) // 只选择需要的字段
+      .where('user.status = :status', { status: 'active' })
+      .orderBy('user.createdAt', 'DESC')
+      .skip((page - 1) * size)
+      .take(size)
+      .getMany();
+
+    return new ServiceResult(true, users);
+  }
+}
+```
+
+### 2. 缓存优化
+
+```typescript
+import { cacheManager } from '@src/framework/utils/CacheManager';
+
+export class UserService extends BaseService {
+  
+  async getUserById(id: number): Promise<ServiceResult<UserEntity>> {
+    const cacheKey = `user:${id}`;
+    
+    // 尝试从缓存获取
+    let user = await cacheManager.get<UserEntity>(cacheKey);
+    
+    if (!user) {
+      // 从数据库获取
+      const result = await this.userRepository.findById(id);
+      if (result.success && result.data) {
+        user = result.data;
+        // 缓存1小时
+        await cacheManager.set(cacheKey, user, 3600);
+      }
+    }
+
+    return new ServiceResult(true, user);
+  }
+}
+```
+
+### 3. 内存优化
+
+```typescript
+export class UserService extends BaseService {
+  private repositoryCache = new Map<string, any>();
+
+  // 定期清理缓存
+  private cleanupCache(): void {
+    if (this.repositoryCache.size > 100) {
+      this.repositoryCache.clear();
+    }
+  }
+
+  // 在服务销毁时清理资源
+  cleanup(): void {
+    this.repositoryCache.clear();
+  }
+}
+```
+
+## 🎯 最佳实践
+
+### 1. 错误处理
+
+```typescript
+// 统一的错误处理
+export class BaseService {
+  protected handleError(error: Error, context: string): ServiceResult<any> {
+    this.logger.error(`${context} 执行失败`, { error: error.message });
+    
+    if (error instanceof ValidationError) {
+      return new ServiceResult(false, undefined, error.message, 400);
+    }
+    
+    if (error instanceof DatabaseError) {
+      return new ServiceResult(false, undefined, '数据库操作失败', 500);
+    }
+    
+    return new ServiceResult(false, undefined, '服务器内部错误', 500);
+  }
+}
+```
+
+### 2. 数据验证
+
+```typescript
+import { validate } from 'class-validator';
+
+export class UserService extends BaseService {
+  
+  async createUser(userData: any): Promise<ServiceResult<UserEntity>> {
+    // 验证输入数据
+    const validationErrors = await validate(userData);
+    if (validationErrors.length > 0) {
+      const errorMessages = validationErrors.map(error => 
+        Object.values(error.constraints || {}).join(', ')
+      );
+      return new ServiceResult(false, undefined, errorMessages.join('; '), 400);
+    }
+
+    // 业务逻辑验证
+    const existingUser = await this.userRepository.findByEmail(userData.email);
+    if (existingUser) {
+      return new ServiceResult(false, undefined, '邮箱已存在', 409);
+    }
+
+    // 创建用户
+    const user = await this.userRepository.create(userData);
+    return new ServiceResult(true, user);
+  }
+}
+```
+
+### 3. 安全实践
+
+```typescript
+import bcrypt from 'bcryptjs';
+
+export class UserService extends BaseService {
+  
+  async createUser(userData: any): Promise<ServiceResult<UserEntity>> {
+    // 密码加密
+    const saltRounds = parseInt(process.env.BCRYPT_ROUNDS || '12');
+    const hashedPassword = await bcrypt.hash(userData.password, saltRounds);
+    
+    const userDataWithHashedPassword = {
+      ...userData,
+      password: hashedPassword
+    };
+
+    const user = await this.userRepository.create(userDataWithHashedPassword);
+    
+    // 返回时移除密码
+    const { password, ...userWithoutPassword } = user;
+    return new ServiceResult(true, userWithoutPassword);
+  }
+}
+```
+
+### 4. 代码复用
+
+```typescript
+// 通用分页服务
+export class PaginationService {
+  static async paginate<T>(
+    repository: Repository<T>,
+    page: number,
+    size: number,
+    where?: any,
+    order?: any
+  ): Promise<{ data: T[]; total: number; page: number; size: number }> {
+    const queryBuilder = repository.createQueryBuilder();
+    
+    if (where) {
+      queryBuilder.where(where);
+    }
+    
+    if (order) {
+      queryBuilder.orderBy(order);
+    }
+    
+    const [data, total] = await queryBuilder
+      .skip((page - 1) * size)
+      .take(size)
+      .getManyAndCount();
+
+    return { data, total, page, size };
+  }
+}
+```
+
+## 📚 相关文档
+
+- [注解系统指南](ENTERPRISE_ANNOTATION_SYSTEM_GUIDE.md) - 详细注解使用说明
+- [服务层指南](SERVICE_PATTERN_GUIDE.md) - 服务层设计模式
+- [拦截器指南](SERVICE_INTERCEPTOR_GUIDE.md) - 拦截器使用
+- [测试指南](TESTING_GUIDE.md) - 测试策略和工具
+- [API 文档](API_DOCUMENTATION.md) - API 参考
+
+---
+
+**相关链接**:
+- [快速开始指南](QUICK_START.md) - 5分钟快速上手
+- [安装配置指南](INSTALLATION_GUIDE.md) - 详细安装步骤
+- [故障排除指南](TROUBLESHOOTING.md) - 常见问题解决
+
+