create-dp-koa 1.0.0

package/template/docs/ROUTE_SLASH_COMPATIBILITY_FIX.md

@@ -0,0 +1,191 @@
+# 路由斜杠兼容性修复
+
+## 🔍 问题描述
+
+用户发现健康检查接口的访问行为不一致：
+- ✅ `http://localhost:3000/health/` - 可以访问
+- ❌ `http://localhost:3000/health` - 无法访问
+
+## 🔧 问题分析
+
+### 根本原因
+
+问题出现在框架的路由注册逻辑中：
+
+```typescript
+// 路由绑定
+bindRouter("/health", HealthController);
+
+// 控制器方法
+@Get("/")
+async healthCheck() { ... }
+```
+
+### 路由构建过程
+
+1. `bindRouter("/health", HealthController)` 将控制器绑定到 `/health` 路径
+2. `@Get("/")` 表示在控制器路径下的根路径
+3. `path.join("/health", "/")` 生成 `/health/`
+4. 最终注册的路由是 `/health/`，而不是 `/health`
+
+### Koa Router 行为
+
+Koa Router 对路径匹配是严格的：
+- `/health/` 只匹配 `http://localhost:3000/health/`
+- `/health` 只匹配 `http://localhost:3000/health`
+
+## ✅ 解决方案
+
+### 修复策略
+
+在路由注册时，如果 URL 以斜杠结尾且不是根路径，同时注册无斜杠版本：
+
+```typescript
+// 原始逻辑
+_router.get(_url, cb)
+
+// 新增逻辑：同时注册无斜杠版本
+if (_url.endsWith('/') && _url !== '/') {
+   const urlWithoutSlash = _url.slice(0, -1);
+   _router.get(urlWithoutSlash, cb)
+}
+```
+
+### 修复范围
+
+为所有 HTTP 方法添加了斜杠兼容性支持：
+- ✅ GET 方法
+- ✅ POST 方法  
+- ✅ PUT 方法
+- ✅ DELETE 方法
+- ✅ ALL 方法
+
+### 中间件兼容性
+
+修复同时考虑了中间件的兼容性：
+
+```typescript
+// 原始URL的中间件
+if (middlewares.length > 0) {
+   for (const middleware of middlewares) {
+      _router.use(_url, middleware);
+   }
+}
+
+// 无斜杠版本的中间件
+if (_url.endsWith('/') && _url !== '/') {
+   const urlWithoutSlash = _url.slice(0, -1);
+   if (middlewares.length > 0) {
+      for (const middleware of middlewares) {
+         _router.use(urlWithoutSlash, middleware);
+      }
+   }
+}
+```
+
+## 🎯 修复效果
+
+### 健康检查接口
+
+现在两个地址都可以正常访问：
+- ✅ `http://localhost:3000/health` - 现在可以访问
+- ✅ `http://localhost:3000/health/` - 仍然可以访问
+
+### 其他接口
+
+所有使用 `@Get("/")` 的接口都获得了相同的兼容性：
+- ✅ `http://localhost:3000/api/users` - 可以访问
+- ✅ `http://localhost:3000/api/users/` - 也可以访问
+
+## 📊 技术细节
+
+### 路径处理逻辑
+
+```typescript
+// 原始路径构建
+const _url = path.join(_path, url).replace(/\\/g, "/");
+
+// 兼容性检查
+if (_url.endsWith('/') && _url !== '/') {
+   const urlWithoutSlash = _url.slice(0, -1);
+   // 注册无斜杠版本
+}
+```
+
+### 特殊情况处理
+
+- **根路径保护**: `_url !== '/'` 确保不会处理根路径
+- **中间件同步**: 确保两个版本使用相同的中间件
+- **方法一致性**: 所有 HTTP 方法都应用相同的逻辑
+
+## 🧪 测试验证
+
+### 基础测试
+
+```bash
+# 健康检查 - 无斜杠
+curl http://localhost:3000/health
+
+# 健康检查 - 有斜杠  
+curl http://localhost:3000/health/
+
+# 数据库健康检查
+curl http://localhost:3000/health/db
+
+# 缓存健康检查
+curl http://localhost:3000/health/cache
+```
+
+### 预期结果
+
+所有测试都应该返回相同的响应，证明路由兼容性正常工作。
+
+## 🔄 向后兼容性
+
+### 现有代码
+
+- ✅ 现有使用 `@Get("/")` 的代码无需修改
+- ✅ 现有使用 `@Post("/")` 的代码无需修改
+- ✅ 现有中间件配置无需修改
+
+### 文档更新
+
+- ✅ 文档中的地址 `http://localhost:3000/health` 现在可以正常工作
+- ✅ 无需更新任何文档内容
+
+## 🎉 总结
+
+这个修复解决了框架路由系统的斜杠兼容性问题：
+
+### 优势
+
+1. **用户体验提升**: 用户可以使用标准的无斜杠 URL
+2. **RESTful 兼容**: 符合 RESTful API 最佳实践
+3. **向后兼容**: 保持现有代码和文档的兼容性
+4. **全面支持**: 覆盖所有 HTTP 方法和中间件
+
+### 技术特点
+
+1. **自动检测**: 自动识别需要兼容的路径
+2. **中间件同步**: 确保两个版本使用相同的中间件
+3. **性能优化**: 只在必要时注册额外路由
+4. **安全保护**: 避免处理根路径等特殊情况
+
+### 影响范围
+
+- ✅ 所有使用 `@Get("/")` 的控制器方法
+- ✅ 所有使用 `@Post("/")` 的控制器方法
+- ✅ 所有使用 `@Put("/")` 的控制器方法
+- ✅ 所有使用 `@Delete("/")` 的控制器方法
+- ✅ 所有使用 `@All("/")` 的控制器方法
+
+现在框架支持同时访问有斜杠和无斜杠的 URL，提供了更好的用户体验和 API 兼容性！
+
+---
+
+**修复版本**: v1.0.1  
+**修复时间**: 2024-01-01  
+**影响范围**: 所有路由注册逻辑
+
+
+

package/template/docs/SERVICE_INTERCEPTOR_GUIDE.md

@@ -0,0 +1,243 @@
+# Service调用拦截器插件
+
+基于dp-ioc的Interceptor注解规则，提供完整的Service调用周期监控和管理功能。
+
+## 🚀 功能特性
+
+### 基础拦截器 (ServiceCallInterceptor)
+- ✅ **完整调用周期监控** - 记录方法调用的开始、执行、结束、异常等各个阶段
+- ✅ **性能统计** - 自动统计调用次数、成功率、平均耗时等指标
+- ✅ **敏感信息脱敏** - 自动过滤密码、token等敏感字段
+- ✅ **调用历史记录** - 保存最近的调用历史，便于调试和分析
+- ✅ **详细日志记录** - 提供结构化的调用日志
+
+### 高级拦截器 (AdvancedServiceCallInterceptor)
+- 🔄 **自动重试机制** - 支持指数退避重试策略
+- 💾 **智能缓存** - 可配置的方法结果缓存
+- ⚡ **熔断器模式** - 防止级联故障的熔断保护
+- 📊 **性能监控** - 慢调用检测和性能指标收集
+- 🎛️ **灵活配置** - 支持多种配置选项
+
+## 📦 安装和导入
+
+```typescript
+import { Injectable, Interceptor } from "dp-ioc";
+import { createServiceCallInterceptor } from '@src/framework/interceptors/ServiceCallInterceptor';
+import { createAdvancedServiceCallInterceptor, InterceptorOptions } from '@src/framework/interceptors/AdvancedServiceCallInterceptor';
+```
+
+## 🔧 基础使用
+
+### 1. 基础拦截器使用
+
+```typescript
+@Injectable()
+export class UserService {
+    
+    @Interceptor(createServiceCallInterceptor())
+    async getUserById(id: number): Promise<User> {
+        // 你的业务逻辑
+        return await this.userRepository.findById(id);
+    }
+    
+    @Interceptor(createServiceCallInterceptor())
+    async createUser(userData: CreateUserDto): Promise<User> {
+        // 你的业务逻辑
+        return await this.userRepository.create(userData);
+    }
+}
+```
+
+### 2. 高级拦截器使用
+
+```typescript
+@Injectable()
+export class OrderService {
+    
+    @Interceptor(createAdvancedServiceCallInterceptor({
+        enablePerformanceMonitoring: true,
+        enableCaching: true,
+        enableRetry: true,
+        enableCircuitBreaker: true,
+        cacheTTL: 300000, // 5分钟
+        maxRetries: 3,
+        retryDelay: 1000,
+        circuitBreakerThreshold: 5,
+        slowCallThreshold: 1000
+    }))
+    async getOrderById(orderId: number): Promise<Order> {
+        // 可能失败的外部API调用
+        return await this.externalOrderService.getOrder(orderId);
+    }
+}
+```
+
+## ⚙️ 配置选项
+
+### InterceptorOptions
+
+```typescript
+interface InterceptorOptions {
+    enablePerformanceMonitoring?: boolean;  // 启用性能监控
+    enableCaching?: boolean;                // 启用缓存
+    enableRetry?: boolean;                  // 启用重试
+    enableCircuitBreaker?: boolean;         // 启用熔断器
+    cacheTTL?: number;                      // 缓存TTL (毫秒)
+    maxRetries?: number;                    // 最大重试次数
+    retryDelay?: number;                    // 重试延迟 (毫秒)
+    circuitBreakerThreshold?: number;       // 熔断器阈值
+    slowCallThreshold?: number;             // 慢调用阈值 (毫秒)
+}
+```
+
+## 📊 监控和统计
+
+### 获取调用统计
+
+```typescript
+import { serviceCallInterceptor } from '@src/framework/interceptors/ServiceCallInterceptor';
+
+// 获取统计报告
+const report = serviceCallInterceptor.generateReport();
+console.log(report);
+
+// 获取调用历史
+const history = serviceCallInterceptor.getCallHistory();
+console.log(history);
+
+// 获取方法统计
+const methodStats = serviceCallInterceptor.getMethodStats('UserService.getUserById');
+console.log(methodStats);
+```
+
+### 高级拦截器状态
+
+```typescript
+import { advancedServiceCallInterceptor } from '@src/framework/interceptors/AdvancedServiceCallInterceptor';
+
+// 获取拦截器状态
+const status = advancedServiceCallInterceptor.getStatus();
+console.log(status);
+
+// 清理缓存
+advancedServiceCallInterceptor.clearCache();
+
+// 重置熔断器
+advancedServiceCallInterceptor.resetCircuitBreakers();
+```
+
+## 📝 日志输出示例
+
+### 基础拦截器日志
+
+```
+🚀 Service调用开始: UserService.getUserById 参数: [123], 时间: 2025-10-27T00:30:00.000Z
+✅ Service调用成功: UserService.getUserById 耗时: 150ms, 结果: {"id":123,"name":"张三"}, 时间: 2025-10-27T00:30:00.150Z
+```
+
+### 高级拦截器日志
+
+```
+执行方法: OrderService.getOrderById (尝试 1) 参数: [456]
+方法调用失败，1000ms后重试 (1/3): OrderService.getOrderById 错误: 外部API调用失败, 尝试次数: 1/3
+执行方法: OrderService.getOrderById (尝试 2) 参数: [456]
+方法执行成功: OrderService.getOrderById 耗时: 300ms, 尝试次数: 2
+```
+
+## 🎯 使用场景
+
+### 1. 基础监控场景
+- 开发环境调试
+- 生产环境监控
+- 性能分析
+- 错误追踪
+
+### 2. 高级功能场景
+- 外部API调用（重试 + 熔断）
+- 频繁查询优化（缓存）
+- 性能敏感操作（监控）
+- 高可用性要求（熔断器）
+
+## 🔍 示例代码
+
+查看完整示例：
+- `src/examples/ServiceInterceptorExample.ts` - 基础拦截器示例
+- `src/examples/InterceptorExampleRunner.ts` - 完整使用示例
+
+## 🛠️ 自定义扩展
+
+### 创建自定义拦截器
+
+```typescript
+const customInterceptor = (params: Array<any>, instance: any, fn: Function, done: (err: any, param: any) => void) => {
+    // 你的自定义逻辑
+    const startTime = Date.now();
+    
+    try {
+        const result = fn.apply(instance, params);
+        
+        if (result && typeof result.then === 'function') {
+            result.then((res: any) => {
+                const duration = Date.now() - startTime;
+                console.log(`方法执行完成，耗时: ${duration}ms`);
+                done(null, res);
+            }).catch((error: Error) => {
+                done(error, null);
+            });
+        } else {
+            done(null, result);
+        }
+    } catch (error) {
+        done(error as Error, null);
+    }
+};
+
+@Interceptor(customInterceptor)
+async myMethod() {
+    // 你的方法
+}
+```
+
+## 📈 性能考虑
+
+- 拦截器对性能影响很小（< 1ms）
+- 缓存可以显著提升重复调用的性能
+- 重试机制会增加失败调用的延迟
+- 熔断器可以防止系统过载
+
+## 🔒 安全特性
+
+- 自动脱敏敏感字段（password, token, secret等）
+- 支持自定义脱敏规则
+- 不记录敏感参数和返回值
+
+## 📋 最佳实践
+
+1. **开发环境**：使用基础拦截器进行调试
+2. **生产环境**：根据需要启用高级功能
+3. **外部调用**：建议启用重试和熔断器
+4. **频繁查询**：考虑启用缓存
+5. **性能敏感**：启用性能监控
+6. **定期清理**：定期清理缓存和历史记录
+
+## 🐛 故障排除
+
+### 常见问题
+
+1. **拦截器不生效**：确保正确导入和使用了`@Interceptor`装饰器
+2. **缓存不工作**：检查`enableCaching`配置和`cacheTTL`设置
+3. **重试不生效**：确认`enableRetry`为true且方法抛出异常
+4. **熔断器误触发**：调整`circuitBreakerThreshold`阈值
+
+### 调试技巧
+
+```typescript
+// 启用详细日志
+logger.setLevel('debug');
+
+// 查看拦截器状态
+console.log(serviceCallInterceptor.getStats());
+console.log(advancedServiceCallInterceptor.getStatus());
+```
+
+

package/template/docs/SERVICE_LAYER_INDEX.md

@@ -0,0 +1,205 @@
+# Service 层文档索引
+
+## 📚 核心文档
+
+### 1. [Service 返回值规范](./SERVICE_RETURN_VALUE_SPECIFICATION.md) ⭐ 推荐阅读
+
+**必读**：所有 Service 方法必须返回 `CommonServiceResult<T>` 对象
+
+主要内容：
+- ✅ CommonServiceResult 结构和使用方式
+- ✅ 状态码枚举和含义
+- ✅ 静态工厂方法使用
+- ✅ 完整示例（创建、查询、更新、删除）
+- ✅ Controller 层如何处理返回值
+- ✅ 最佳实践和常见错误
+
+**何时查看**：
+- 编写新的 Service 方法时
+- 不确定如何返回结果时
+- 需要了解错误处理方式时
+
+---
+
+### 2. [Service 层开发指南](./SERVICE_PATTERN_GUIDE.md) ⭐ 推荐阅读
+
+**必读**：如何编写 Service 层代码
+
+主要内容：
+- ✅ 使用懒加载 Getter 初始化 Repository
+- ✅ 继承 BaseService 的用法
+- ✅ 多 Repository 的场景处理
+- ✅ 完整示例代码
+
+**何时查看**：
+- 第一次编写 Service 时
+- 需要初始化 Repository 时
+- 不知道如何设计 Service 结构时
+
+---
+
+### 3. [TransactionManager 使用指南](./TRANSACTION_MANAGER_USAGE.md)
+
+**推荐**：事务管理器的使用
+
+主要内容：
+- ✅ 基本事务使用
+- ✅ 隔离级别设置
+- ✅ 只读事务优化
+- ✅ 批量操作
+- ✅ 嵌套事务
+- ✅ 错误处理和回滚
+
+**何时查看**：
+- 需要执行事务操作时
+- 需要保证数据一致性时
+- 处理复杂业务逻辑时
+
+---
+
+## 🎯 快速开始
+
+### 创建新 Service 的步骤
+
+1. **创建 Service 文件**
+   ```typescript
+   import { Injectable } from "dp-ioc";
+   import { BaseService } from "@src/service/base.service";
+   import { CommonServiceResult } from "@src/framework/types/ServiceResult";
+
+   @Injectable()
+   export class MyService extends BaseService {
+       // 添加方法
+   }
+   ```
+
+2. **编写 Service 方法**
+   ```typescript
+   async myMethod(dto: MyDto): Promise<CommonServiceResult<MyEntity>> {
+       try {
+           // 业务逻辑
+           return CommonServiceResult.success(result);
+       } catch (error) {
+           return CommonServiceResult.error("操作失败");
+       }
+   }
+   ```
+
+3. **返回 CommonServiceResult**
+   ```typescript
+   // 成功
+   return CommonServiceResult.success(data);
+   
+   // 验证错误
+   return CommonServiceResult.validationError("错误消息");
+   
+   // 未找到
+   return CommonServiceResult.notFound("资源不存在");
+   
+   // 冲突
+   return CommonServiceResult.conflict("资源冲突");
+   
+   // 服务器错误
+   return CommonServiceResult.error("操作失败");
+   ```
+
+---
+
+## 📋 文档结构
+
+```
+docs/
+├── SERVICE_LAYER_INDEX.md                    # 本文件 - Service 层文档索引
+├── SERVICE_RETURN_VALUE_SPECIFICATION.md     # Service 返回值规范 ⭐
+├── SERVICE_PATTERN_GUIDE.md                  # Service 层开发指南 ⭐
+└── TRANSACTION_MANAGER_USAGE.md              # 事务管理器使用指南
+```
+
+---
+
+## 🔍 常见问题
+
+### Q: Service 方法必须返回什么？
+
+**A**: 所有 Service 方法必须返回 `CommonServiceResult<T>`
+
+```typescript
+// ✅ 正确
+async createUser(dto: CreateUserDto): Promise<CommonServiceResult<UserEntity>> {
+    return CommonServiceResult.success(user);
+}
+
+// ❌ 错误
+async createUser(dto: CreateUserDto): Promise<UserEntity> {
+    return user; // 不要这样做
+}
+```
+
+### Q: 如何处理 Service 中的异常？
+
+**A**: 使用 try-catch 捕获异常，返回适当的错误结果
+
+```typescript
+try {
+    // 业务逻辑
+    return CommonServiceResult.success(data);
+} catch (error) {
+    logger.error("操作失败:", error);
+    return CommonServiceResult.error("操作失败");
+}
+```
+
+### Q: 如何初始化 Repository？
+
+**A**: 使用懒加载 Getter 或继承 BaseService
+
+```typescript
+// 方案1: 懒加载 Getter
+private get userRepository(): IUserRepository {
+    return this.createLazyRepository(YtUserEntity, UserRepository, this.repositoryCache);
+}
+
+// 方案2: 继承 BaseService
+const repo = this.getDataRepository(YtUserEntity);
+```
+
+### Q: 何时使用事务？
+
+**A**: 需要保证多个操作原子性时
+
+```typescript
+await transactionManager.executeInTransaction(async (manager) => {
+    await this.userRepository.save(user1);
+    await this.userRepository.save(user2);
+});
+```
+
+详细说明请查看 [TransactionManager 使用指南](./TRANSACTION_MANAGER_USAGE.md)
+
+---
+
+## 🛠️ 相关文档
+
+### 基础
+- [企业级数据库架构](./ENTERPRISE_DATABASE_ARCHITECTURE.md) - 数据库设计
+- [企业级错误处理](./ENTERPRISE_ERROR_HANDLING_GUIDE.md) - 错误处理
+- [企业级日志系统](./ENTERPRISE_LOGGING_SYSTEM_GUIDE.md) - 日志管理
+
+### 高级
+- [企业级部署指南](./ENTERPRISE_DEPLOYMENT_GUIDE.md) - 部署流程
+- [环境配置示例](./ENVIRONMENT_CONFIG_EXAMPLE.md) - 环境配置
+
+---
+
+## 📞 获取帮助
+
+遇到问题？
+1. 首先查看对应的详细文档
+2. 查看代码示例（src/service/ 目录）
+3. 查看测试用例（test/service/ 目录）
+
+需要更多信息？
+- 查看项目 README.md
+- 查看完整的文档列表
+
+