create-dp-koa 1.0.0

package/template/docs/SERVICE_RETURN_VALUE_SPECIFICATION.md

@@ -0,0 +1,466 @@
+# Service 层返回值规范
+
+## 概述
+
+本文档定义了 Service 层的标准返回值规范，确保所有 Service 方法遵循统一的返回格式。
+
+## 核心返回类型：CommonServiceResult<T>
+
+所有 Service 方法必须返回 `CommonServiceResult<T>` 对象，其中 `T` 是实际返回的数据类型。
+
+### 结构定义
+
+```typescript
+class CommonServiceResult<T> {
+    code: CommonServiceResultCode;     // 状态码
+    data: T | null;                    // 返回数据
+    message?: string;                  // 提示消息
+}
+```
+
+## 状态码枚举
+
+```typescript
+enum CommonServiceResultCode {
+    SUCCESS = "SUCCESS",                    // 成功
+    FAIL = "FAIL",                          // 失败
+    ERROR = "ERROR",                        // 错误
+    NOT_FOUND = "NOT_FOUND",                // 未找到
+    VALIDATION_ERROR = "VALIDATION_ERROR",   // 验证错误
+    UNAUTHORIZED = "UNAUTHORIZED",          // 未授权
+    FORBIDDEN = "FORBIDDEN",                // 禁止访问
+    CONFLICT = "CONFLICT",                  // 冲突
+    TIMEOUT = "TIMEOUT",                    // 超时
+    RATE_LIMITED = "RATE_LIMITED",          // 限流
+}
+```
+
+## 使用方式
+
+### 1. 静态工厂方法（推荐）
+
+```typescript
+import { CommonServiceResult, CommonServiceResultCode } from '@src/framework/types/ServiceResult';
+
+// 创建成功结果
+const result = CommonServiceResult.success(user, "用户创建成功");
+
+// 创建失败结果
+const result = CommonServiceResult.fail(
+    CommonServiceResultCode.NOT_FOUND,
+    "用户不存在"
+);
+
+// 创建验证错误
+const result = CommonServiceResult.validationError("邮箱格式不正确");
+
+// 创建未找到结果
+const result = CommonServiceResult.notFound("用户不存在");
+
+// 创建未授权结果
+const result = CommonServiceResult.unauthorized("密码错误");
+
+// 创建禁止访问结果
+const result = CommonServiceResult.forbidden("用户已被禁用");
+
+// 创建冲突结果
+const result = CommonServiceResult.conflict("邮箱已被使用");
+
+// 创建服务器错误
+const result = CommonServiceResult.error("创建用户时发生错误");
+```
+
+### 2. 构造方法
+
+```typescript
+// 使用构造函数
+const result = new CommonServiceResult(
+    CommonServiceResultCode.SUCCESS,
+    user,
+    "用户创建成功"
+);
+```
+
+### 3. 常用结果类型
+
+#### 成功结果
+
+```typescript
+// 成功返回数据
+return CommonServiceResult.success(user);
+// 或
+return CommonServiceResult.success(user, "操作成功");
+
+// 返回类型
+Promise<CommonServiceResult<UserEntity>>
+```
+
+#### 验证错误
+
+```typescript
+return CommonServiceResult.validationError("邮箱格式不正确");
+return CommonServiceResult.validationError("密码长度不能少于6个字符", null);
+
+// 返回类型
+Promise<CommonServiceResult<UserEntity | null>>
+```
+
+#### 资源未找到
+
+```typescript
+return CommonServiceResult.notFound("用户不存在");
+return CommonServiceResult.notFound("订单不存在", null);
+
+// 返回类型
+Promise<CommonServiceResult<UserEntity | null>>
+```
+
+#### 权限错误
+
+```typescript
+// 未授权
+return CommonServiceResult.unauthorized("密码错误");
+
+// 禁止访问
+return CommonServiceResult.forbidden("账户已被禁用");
+```
+
+#### 资源冲突
+
+```typescript
+return CommonServiceResult.conflict("邮箱已被使用");
+return CommonServiceResult.conflict("手机号已被注册");
+```
+
+#### 服务器错误
+
+```typescript
+return CommonServiceResult.error("创建用户时发生错误");
+```
+
+## 完整示例
+
+### 示例 1：创建用户 Service
+
+```typescript
+import { Injectable } from "dp-ioc";
+import { CommonServiceResult } from '@src/framework/types/ServiceResult';
+import { CreateUserDto } from '@src/dto/user.dto';
+
+@Injectable()
+export class YtUserService extends BaseService {
+    async createUser(dto: CreateUserDto): Promise<CommonServiceResult<UserEntity>> {
+        try {
+            // 1. 验证数据
+            if (!dto.email) {
+                return CommonServiceResult.validationError("邮箱不能为空");
+            }
+
+            // 2. 检查业务规则
+            const existingUser = await this.userRepository.findByEmail(dto.email);
+            if (existingUser) {
+                return CommonServiceResult.conflict("邮箱已被使用");
+            }
+
+            // 3. 执行业务逻辑
+            const user = await this.userRepository.save({
+                ...dto,
+                password: await bcrypt.hash(dto.password, 10)
+            });
+
+            // 4. 返回成功
+            return CommonServiceResult.success(user, "用户创建成功");
+
+        } catch (error) {
+            logger.error("创建用户失败:", error);
+            return CommonServiceResult.error("创建用户时发生错误");
+        }
+    }
+}
+```
+
+### 示例 2：查找用户 Service
+
+```typescript
+async getUserById(id: number): Promise<CommonServiceResult<UserEntity | null>> {
+    try {
+        const user = await this.userRepository.findById(id);
+        
+        if (!user) {
+            return CommonServiceResult.notFound("用户不存在");
+        }
+
+        return CommonServiceResult.success(user);
+    } catch (error) {
+        logger.error("获取用户失败:", error);
+        return CommonServiceResult.error("获取用户时发生错误");
+    }
+}
+```
+
+### 示例 3：更新用户 Service
+
+```typescript
+async updateUser(
+    id: number, 
+    dto: UpdateUserDto
+): Promise<CommonServiceResult<UserEntity | null>> {
+    try {
+        // 检查用户是否存在
+        const existingUser = await this.userRepository.findById(id);
+        if (!existingUser) {
+            return CommonServiceResult.notFound("用户不存在");
+        }
+
+        // 检查业务冲突
+        if (dto.email && dto.email !== existingUser.email) {
+            const userWithEmail = await this.userRepository.findByEmail(dto.email);
+            if (userWithEmail) {
+                return CommonServiceResult.conflict("邮箱已被其他用户使用");
+            }
+        }
+
+        // 执行更新
+        await this.userRepository.update(id, dto);
+        const updatedUser = await this.userRepository.findById(id);
+
+        return CommonServiceResult.success(updatedUser, "用户更新成功");
+    } catch (error) {
+        logger.error("更新用户失败:", error);
+        return CommonServiceResult.error("更新用户时发生错误");
+    }
+}
+```
+
+### 示例 4：查询列表 Service
+
+```typescript
+async getUsers(query: QueryUserDto): Promise<CommonServiceResult<[UserEntity[], number]>> {
+    try {
+        const [users, total] = await this.userRepository.findAndCount(query);
+
+        return CommonServiceResult.success([users, total]);
+    } catch (error) {
+        logger.error("查询用户列表失败:", error);
+        return CommonServiceResult.error("查询用户列表时发生错误");
+    }
+}
+```
+
+## Controller 层的处理
+
+### 标准处理模式
+
+```typescript
+@Post('/users')
+async createUser(ctx: Context) {
+    const dto = ctx.request.body;
+    const result = await userService.createUser(dto);
+
+    if (result.isSuccess()) {
+        ctx.status = 200;
+        ctx.body = {
+            code: 0,
+            message: result.message,
+            data: result.data
+        };
+    } else {
+        // 根据不同的错误码返回不同的 HTTP 状态码
+        ctx.status = this.getHttpStatus(result.code);
+        ctx.body = {
+            code: this.getHttpCode(result.code),
+            message: result.message || result.getErrorMessage(),
+            data: result.data
+        };
+    }
+}
+
+private getHttpStatus(code: CommonServiceResultCode): number {
+    const statusMap = {
+        [CommonServiceResultCode.SUCCESS]: 200,
+        [CommonServiceResultCode.VALIDATION_ERROR]: 400,
+        [CommonServiceResultCode.UNAUTHORIZED]: 401,
+        [CommonServiceResultCode.FORBIDDEN]: 403,
+        [CommonServiceResultCode.NOT_FOUND]: 404,
+        [CommonServiceResultCode.CONFLICT]: 409,
+        [CommonServiceResultCode.ERROR]: 500,
+    };
+    return statusMap[code] || 500;
+}
+```
+
+### 简化处理模式
+
+```typescript
+@Post('/users')
+async createUser(ctx: Context) {
+    const dto = ctx.request.body;
+    const result = await userService.createUser(dto);
+
+    // 统一处理
+    ctx.status = result.isSuccess() ? 200 : 400;
+    ctx.body = {
+        success: result.isSuccess(),
+        data: result.data,
+        message: result.message
+    };
+}
+```
+
+## 状态码映射表
+
+| Service 状态码 | HTTP 状态码 | 说明 |
+|---------------|------------|------|
+| SUCCESS | 200 | 操作成功 |
+| VALIDATION_ERROR | 400 | 数据验证失败 |
+| UNAUTHORIZED | 401 | 未授权 |
+| FORBIDDEN | 403 | 禁止访问 |
+| NOT_FOUND | 404 | 资源不存在 |
+| CONFLICT | 409 | 资源冲突 |
+| ERROR | 500 | 服务器错误 |
+| TIMEOUT | 504 | 请求超时 |
+| RATE_LIMITED | 429 | 请求过频 |
+
+## 辅助方法
+
+### isSuccess() / isFailure()
+
+```typescript
+const result = await userService.createUser(dto);
+
+if (result.isSuccess()) {
+    // 处理成功情况
+    console.log(result.data);
+} else {
+    // 处理失败情况
+    console.error(result.message);
+}
+```
+
+### getErrorMessage()
+
+```typescript
+const result = await userService.createUser(dto);
+
+if (result.isFailure()) {
+    const errorMsg = result.getErrorMessage();
+    // 返回默认错误消息或自定义消息
+    console.error(errorMsg);
+}
+```
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **总是返回 CommonServiceResult**
+   ```typescript
+   async createUser(dto: CreateUserDto): Promise<CommonServiceResult<UserEntity>> {
+       // ...
+   }
+   ```
+
+2. **使用工厂方法创建结果**
+   ```typescript
+   return CommonServiceResult.success(user);
+   return CommonServiceResult.validationError("邮箱不能为空");
+   ```
+
+3. **提供有意义的错误消息**
+   ```typescript
+   return CommonServiceResult.notFound("用户不存在");
+   // 而不是
+   return CommonServiceResult.notFound();
+   ```
+
+4. **统一处理异常**
+   ```typescript
+   try {
+       // 业务逻辑
+   } catch (error) {
+       logger.error("操作失败:", error);
+       return CommonServiceResult.error("操作失败");
+   }
+   ```
+
+### ❌ 避免的做法
+
+1. **不要直接抛出异常**
+   ```typescript
+   // 不好的做法
+   async createUser(dto: CreateUserDto) {
+       throw new Error("用户创建失败");
+   }
+   
+   // 好的做法
+   async createUser(dto: CreateUserDto): Promise<CommonServiceResult<UserEntity>> {
+       return CommonServiceResult.error("用户创建失败");
+   }
+   ```
+
+2. **不要返回 null 或 undefined**
+   ```typescript
+   // 不好的做法
+   async getUser(id: number) {
+       const user = await this.repository.findById(id);
+       return user; // 可能返回 null
+   }
+   
+   // 好的做法
+   async getUser(id: number): Promise<CommonServiceResult<UserEntity | null>> {
+       const user = await this.repository.findById(id);
+       if (!user) {
+           return CommonServiceResult.notFound("用户不存在");
+       }
+       return CommonServiceResult.success(user);
+   }
+   ```
+
+3. **不要混合不同的返回类型**
+   ```typescript
+   // 不好的做法
+   async getUser(id: number) {
+       if (!id) return null;
+       const user = await this.repository.findById(id);
+       return user;
+   }
+   
+   // 好的做法
+   async getUser(id: number): Promise<CommonServiceResult<UserEntity | null>> {
+       // 所有路径都返回 CommonServiceResult
+   }
+   ```
+
+## 类型安全
+
+使用泛型确保类型安全：
+
+```typescript
+// 返回单个实体
+Promise<CommonServiceResult<UserEntity>>
+
+// 返回实体或 null
+Promise<CommonServiceResult<UserEntity | null>>
+
+// 返回列表
+Promise<CommonServiceResult<UserEntity[]>>
+
+// 返回元组 [data, total]
+Promise<CommonServiceResult<[UserEntity[], number]>>
+
+// 返回布尔值
+Promise<CommonServiceResult<boolean>>
+```
+
+## 总结
+
+- ✅ 所有 Service 方法必须返回 `CommonServiceResult<T>`
+- ✅ 使用静态工厂方法创建结果（推荐）
+- ✅ 提供有意义的错误消息
+- ✅ 正确处理异常
+- ✅ Controller 层统一处理返回结果
+- ✅ 保持类型安全
+
+遵循这些规范可以确保代码的一致性、可维护性和可读性。
+
+

package/template/docs/SWAGGER_DEBUG_MODE_GUIDE.md

@@ -0,0 +1,80 @@
+# Swagger 调试模式配置指南
+
+## 🎯 调试模式特点
+
+当你使用 VS Code 调试模式时：
+- 使用 `ts-node` 直接运行 TypeScript 源码
+- 不需要编译步骤
+- 支持热重载和断点调试
+- 环境变量在 `launch.json` 中配置
+
+## 🔧 当前配置
+
+### VS Code 调试配置
+```json
+{
+    "name": "Debug TS Server",
+    "env": {
+        "NODE_ENV": "development",
+        "USE_NEW_ANNOTATION_SYSTEM": "1",
+        "db_memory": "1",
+        "db_enable": "1",
+        "SWAGGER_ROUTE_PREFIX": "/swagger/b"  // 新增
+    }
+}
+```
+
+### Swagger 路径检测逻辑
+1. **优先使用环境变量** - `SWAGGER_ROUTE_PREFIX`
+2. **自动检测路由前缀** - 从实际路由注册中获取
+3. **默认值回退** - `/swagger/b`
+
+## 📋 修改 bindRouter 路径的调试模式流程
+
+### 方法1：修改环境变量（推荐）
+1. **修改 `.vscode/launch.json`**：
+   ```json
+   "SWAGGER_ROUTE_PREFIX": "/your/new/path"
+   ```
+
+2. **重新启动调试**：
+   - 停止当前调试会话
+   - 重新启动调试（F5）
+
+3. **验证更新**：
+   - 访问 http://127.0.0.1:3000/swagger.json
+   - 检查路径是否已更新
+
+### 方法2：修改默认值
+1. **修改 `src/framework/utils/dynamicSwagger.ts`**：
+   ```typescript
+   const defaultPrefix = '/your/new/path';
+   ```
+
+2. **重新启动调试**
+
+## 🎯 当前 Swagger 路径
+
+基于当前配置，Swagger UI 应该显示：
+- **GET** `/swagger/b/user/list` - 获取用户列表
+- **GET** `/swagger/b/user/{id}` - 获取用户详情
+- **POST** `/swagger/b/user` - 创建用户
+- **PUT** `/swagger/b/user/{id}` - 更新用户
+- **DELETE** `/swagger/b/user/{id}` - 删除用户
+
+## 🔍 调试信息
+
+启动调试时，查看控制台日志：
+```
+使用环境变量中的 Swagger 路径前缀: /swagger/b
+动态生成 Swagger 规范成功，包含 5 个路由
+```
+
+## 💡 最佳实践
+
+1. **使用环境变量** - 便于不同环境配置
+2. **保持同步** - 确保 `bindRouter` 路径与环境变量一致
+3. **验证更新** - 每次修改后检查 Swagger UI
+4. **日志监控** - 关注控制台的 Swagger 相关日志
+
+