create-dp-koa 1.0.0

package/template/docs/TRANSACTION_MANAGER_USAGE.md

@@ -0,0 +1,360 @@
+# TransactionManager 使用指南
+
+## 概述
+
+TransactionManager 是一个企业级事务管理器，提供了简洁、安全的数据库事务处理能力。它确保数据库操作的原子性、一致性、隔离性和持久性（ACID 特性）。
+
+## 主要特性
+
+✅ **自动资源管理** - 自动释放连接，防止内存泄露  
+✅ **多种隔离级别** - 支持 READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE  
+✅ **只读事务优化** - 专门针对只读操作优化  
+✅ **批量操作支持** - 一次事务处理多个操作  
+✅ **嵌套事务** - 支持在现有事务中执行额外操作  
+✅ **完善的错误处理** - 自动回滚，确保数据一致性  
+
+## 快速开始
+
+### 1. 基本使用
+
+```typescript
+import { transactionManager } from '@src/framework/utils/TransactionManager';
+
+// 在事务中执行操作
+const result = await transactionManager.executeInTransaction(async (manager) => {
+    // 所有数据库操作都在事务中执行
+    const user = new YtUserEntity();
+    user.email = 'user@example.com';
+    user.password = await bcrypt.hash('password', 10);
+    
+    return await manager.save(user);
+});
+```
+
+### 2. 在 Service 中使用
+
+```typescript
+import { Injectable } from "dp-ioc";
+import { transactionManager } from "@src/framework/utils/TransactionManager";
+import { YtUserEntity } from "@src/entity/ytUser.entity";
+
+@Injectable()
+export class MyService {
+    async createUser(userData: any): Promise<YtUserEntity> {
+        return await transactionManager.executeInTransaction(async (manager) => {
+            // 1. 创建用户
+            const user = new YtUserEntity();
+            user.email = userData.email;
+            user.password = userData.password;
+            const savedUser = await manager.save(user);
+            
+            // 2. 创建相关记录（都在同一事务中）
+            // const profile = await manager.save(ProfileEntity, profileData);
+            
+            return savedUser;
+        });
+    }
+}
+```
+
+## 使用场景详解
+
+### 场景 1: 用户注册（多表操作）
+
+```typescript
+async createUserWithProfile(userData: any, profileData: any): Promise<any> {
+    return await transactionManager.executeInTransaction(async (manager) => {
+        // 步骤 1: 创建用户
+        const user = await manager.save(YtUserEntity, userData);
+        
+        // 步骤 2: 创建用户配置
+        const profile = await manager.save(ProfileEntity, {
+            ...profileData,
+            userId: user.id
+        });
+        
+        // 步骤 3: 创建默认权限
+        const permissions = await manager.save(PermissionEntity, {
+            userId: user.id,
+            permissions: ['read']
+        });
+        
+        // 如果任何一步失败，整个事务都会回滚
+        return { user, profile, permissions };
+    });
+}
+```
+
+### 场景 2: 转账操作（需要一致性保证）
+
+```typescript
+async transferMoney(fromUserId: number, toUserId: number, amount: number) {
+    return await transactionManager.executeInTransaction(
+        async (manager) => {
+            // 使用 SERIALIZABLE 隔离级别确保最高一致性
+            const fromAccount = await manager.findOne(AccountEntity, {
+                where: { userId: fromUserId }
+            });
+            
+            const toAccount = await manager.findOne(AccountEntity, {
+                where: { userId: toUserId }
+            });
+            
+            // 检查余额
+            if (fromAccount.balance < amount) {
+                throw new Error('余额不足');
+            }
+            
+            // 扣款
+            fromAccount.balance -= amount;
+            await manager.save(fromAccount);
+            
+            // 入账
+            toAccount.balance += amount;
+            await manager.save(toAccount);
+            
+            // 记录转账记录
+            await manager.save(TransferRecordEntity, {
+                fromUserId,
+                toUserId,
+                amount,
+                createdAt: new Date()
+            });
+            
+            return { success: true };
+        },
+        'SERIALIZABLE' // 最高隔离级别
+    );
+}
+```
+
+### 场景 3: 批量导入数据
+
+```typescript
+async importUsers(userList: any[]): Promise<any[]> {
+    const operations = userList.map(userData => {
+        return async (manager: EntityManager) => {
+            // 验证数据
+            if (!userData.email) {
+                throw new Error('邮箱不能为空');
+            }
+            
+            // 创建用户
+            const user = new YtUserEntity();
+            user.email = userData.email;
+            user.password = await bcrypt.hash(userData.password, 10);
+            
+            return await manager.save(user);
+        };
+    });
+    
+    // 所有操作在一个事务中执行
+    return await transactionManager.executeBatchTransaction(operations);
+}
+```
+
+### 场景 4: 只读查询优化
+
+```typescript
+async getReportData(startDate: Date, endDate: Date): Promise<any> {
+    return await transactionManager.executeInReadOnlyTransaction(async (manager) => {
+        // 只读事务，不会产生任何写操作
+        // 数据库可以优化只读查询
+        
+        const [users, orders, payments] = await Promise.all([
+            manager.count(YtUserEntity, {
+                where: { createDate: Between(startDate, endDate) }
+            }),
+            manager.count(OrderEntity, {
+                where: { createDate: Between(startDate, endDate) }
+            }),
+            manager.count(PaymentEntity, {
+                where: { createDate: Between(startDate, endDate) }
+            })
+        ]);
+        
+        return {
+            users,
+            orders,
+            payments
+        };
+    });
+}
+```
+
+### 场景 5: 需要嵌套事务的复杂操作
+
+```typescript
+async processOrder(orderId: number): Promise<any> {
+    return await transactionManager.executeInTransaction(async (manager) => {
+        // 主事务：处理订单
+        const order = await manager.findOne(OrderEntity, orderId);
+        order.status = 'processing';
+        await manager.save(order);
+        
+        // 嵌套事务：处理支付
+        await transactionManager.executeNestedTransaction(async (nestedManager) => {
+            const payment = await nestedManager.save(PaymentEntity, {
+                orderId: order.id,
+                amount: order.total
+            });
+            
+            // 嵌套事务：发送通知
+            await transactionManager.executeNestedTransaction(async (innerManager) => {
+                await innerManager.save(NotificationEntity, {
+                    userId: order.userId,
+                    message: '订单已支付'
+                });
+            });
+            
+            return payment;
+        });
+        
+        return order;
+    });
+}
+```
+
+### 场景 6: 错误处理和回滚
+
+```typescript
+async createOrderWithInventoryCheck(orderData: any): Promise<any> {
+    try {
+        return await transactionManager.executeInTransaction(async (manager) => {
+            // 检查库存
+            const product = await manager.findOne(ProductEntity, orderData.productId);
+            if (product.stock < orderData.quantity) {
+                throw new Error('库存不足'); // 抛出错误会自动回滚
+            }
+            
+            // 创建订单
+            const order = await manager.save(OrderEntity, orderData);
+            
+            // 更新库存
+            product.stock -= orderData.quantity;
+            await manager.save(product);
+            
+            return order;
+        });
+    } catch (error) {
+        // 所有操作已自动回滚
+        logger.error('创建订单失败，已回滚所有更改');
+        throw error;
+    }
+}
+```
+
+## 隔离级别说明
+
+| 隔离级别 | 说明 | 使用场景 |
+|---------|------|---------|
+| READ_UNCOMMITTED | 允许读取未提交数据 | 性能要求高，不太关心数据一致性 |
+| READ_COMMITTED | 只能读取已提交数据（默认） | 大多数业务场景 |
+| REPEATABLE_READ | 事务内多次读取一致 | 需要重复读取一致性 |
+| SERIALIZABLE | 最高隔离级别 | 金融交易、高一致性要求 |
+
+```typescript
+// 使用隔离级别
+await transactionManager.executeInTransaction(
+    async (manager) => {
+        // 业务逻辑
+    },
+    'SERIALIZABLE' // 指定隔离级别
+);
+```
+
+## 最佳实践
+
+### ✅ 推荐做法
+
+1. **始终使用事务处理多表操作**
+   ```typescript
+   // 好的做法
+   await transactionManager.executeInTransaction(async (manager) => {
+       await manager.save(user);
+       await manager.save(profile);
+   });
+   ```
+
+2. **为事务操作添加适当的错误处理**
+   ```typescript
+   try {
+       await transactionManager.executeInTransaction(async (manager) => {
+           // 操作
+       });
+   } catch (error) {
+       logger.error('操作失败:', error);
+       // 事务已自动回滚
+   }
+   ```
+
+3. **使用只读事务优化查询性能**
+   ```typescript
+   // 只读操作使用只读事务
+   await transactionManager.executeInReadOnlyTransaction(async (manager) => {
+       return await manager.find(UserEntity);
+   });
+   ```
+
+### ❌ 避免的做法
+
+1. **不要在事务中执行长时间运行的操作**
+   ```typescript
+   // 不好的做法
+   await transactionManager.executeInTransaction(async (manager) => {
+       await sleep(5000); // 长时间持有连接
+   });
+   ```
+
+2. **不要忘记处理错误**
+   ```typescript
+   // 不好的做法
+   await transactionManager.executeInTransaction(async (manager) => {
+       // 没有错误处理
+   });
+   ```
+
+3. **不要在事务中调用外部服务**
+   ```typescript
+   // 不好的做法
+   await transactionManager.executeInTransaction(async (manager) => {
+       await manager.save(data);
+       await externalApi.call(); // 可能会导致事务锁定
+   });
+   ```
+
+## 性能优化建议
+
+1. **事务应尽可能短** - 减少数据库锁定时间
+2. **合理使用隔离级别** - 高隔离级别会影响性能
+3. **批量操作使用 executeBatchTransaction** - 减少事务开启次数
+4. **只读操作使用 executeInReadOnlyTransaction** - 数据库可以优化
+
+## 常见问题
+
+### Q: 事务会自动提交吗？
+A: 是的，如果事务中的所有操作成功执行，会自动提交。如果出现任何错误，会自动回滚。
+
+### Q: 如何处理并发冲突？
+A: 使用适当的隔离级别（如 SERIALIZABLE）和重试机制。
+
+### Q: 事务会影响性能吗？
+A: 合理使用事务不会影响性能。避免长事务和在事务中执行耗时操作。
+
+### Q: 可以手动控制提交和回滚吗？
+A: 不需要，TransactionManager 会自动处理。业务逻辑通过返回值或抛出错误来控制事务。
+
+## 更多示例
+
+查看 `src/examples/TransactionManagerDemo.ts` 获取更多完整示例代码。
+
+## 内存泄露修复
+
+本次修复确保了以下资源的正确释放：
+- ✅ 所有数据库连接都会被正确释放
+- ✅ 事务中的 queryRunner 会被正确清理
+- ✅ 应用关闭时所有资源都会被释放
+
+请参考 `MEMORY_LEAK_FIX_REPORT.md` 了解详细的内存泄露修复说明。
+
+