create-dp-koa 1.0.0

package/template/docs/SERVICE_PATTERN_GUIDE.md

@@ -0,0 +1,270 @@
+# Service 层开发指南
+
+## 问题
+
+在之前的实现中，每个 Service 如果需要延迟初始化 Repository，都要写很多冗余代码：
+
+```typescript
+private userRepository: IUserRepository;
+
+constructor() {
+    this.userRepository = null as any;
+}
+
+private ensureRepositoryInitialized(): void {
+    if (!this.userRepository) {
+        this.initializeRepository();
+    }
+    if (!this.userRepository) {
+        throw new Error("数据库未初始化，请等待数据库初始化完成");
+    }
+}
+
+private initializeRepository(): void {
+    const dataSource = getDataSource();
+    if (!dataSource) {
+        logger.warn("数据库未初始化，将在数据库初始化后重试");
+        return;
+    }
+    
+    const repository = dataSource.getRepository(YtUserEntity);
+    this.userRepository = new UserRepository(repository);
+    
+    transactionManager.setDataSource(dataSource);
+}
+
+// 每个方法都要调用
+async createUser(...) {
+    this.ensureRepositoryInitialized(); // 每次都调用
+    // ...
+}
+```
+
+这样写确实很冗余，而且每个方法都要调用 `ensureRepositoryInitialized()`。
+
+## 解决方案
+
+### 方案1：使用懒加载 Getter（推荐）
+
+继承 `BaseService`，使用 `createLazyRepository` 方法：
+
+```typescript
+export class YtUserService extends BaseService {
+    private repositoryCache = new Map<string, any>();
+
+    /**
+     * 获取用户Repository（懒加载）
+     * 使用基类的通用方法
+     */
+    private get userRepository(): IUserRepository {
+        return this.createLazyRepository(
+            YtUserEntity,
+            UserRepository,
+            this.repositoryCache
+        );
+    }
+
+    // 使用时直接访问，无需额外初始化
+    async createUser(...) {
+        const user = await this.userRepository.save(...); // 自动初始化
+    }
+}
+```
+
+**优点**：
+- 代码非常简洁，只需几行代码
+- 通用方法可复用，所有 Service 都能用
+- 懒加载，只在真正使用时才初始化
+- 自动处理数据库未初始化的情况
+
+**优点**：
+- 代码简洁，无需在每个方法中调用初始化
+- 懒加载，只在真正使用时才初始化
+- 自动处理数据库未初始化的情况
+
+### 方案2：继承 BaseService（适用于简单 CRUD）
+
+对于简单的 CRUD 操作，直接继承 `BaseService`：
+
+```typescript
+import { BaseService } from "@src/service/base.service";
+
+export class YtGoodsService extends BaseService {
+    
+    async unlockGoodsImage(goodsId: number, userId: number, key: string) {
+        // 直接使用 getDataRepository
+        const keyRepo = this.getDataRepository(GoodsImagesUnlockKeyEntity);
+        const unlockKey = await keyRepo.findOneBy({ key });
+        
+        // ...
+    }
+}
+```
+
+**优点**：
+- 最简洁，无需初始化代码
+- 适合简单的数据库操作
+- `BaseService` 已经处理了数据库初始化检查
+
+## 使用场景
+
+### 场景1：需要 Repository 模式（自定义逻辑）
+
+适合：
+- 需要复杂的业务逻辑
+- 需要封装 Repository 方法
+- 需要事务管理
+
+```typescript
+@Injectable()
+export class YtUserService {
+    private _userRepository: IUserRepository | null = null;
+
+    private get userRepository(): IUserRepository {
+        if (!this._userRepository) {
+            const dataSource = getDataSource();
+            if (!dataSource || !dataSource.isInitialized) {
+                throw new Error("数据库未初始化");
+            }
+            this._userRepository = new UserRepository(
+                dataSource.getRepository(YtUserEntity)
+            );
+        }
+        return this._userRepository;
+    }
+
+    async createUser(dto: CreateUserDto) {
+        // 直接使用，自动初始化
+        return await this.userRepository.save(user);
+    }
+}
+```
+
+### 场景2：简单的 CRUD 操作
+
+适合：
+- 直接使用 TypeORM Repository
+- 简单的数据库操作
+- 无需自定义 Repository 逻辑
+
+```typescript
+export class YtShopService extends BaseService {
+    
+    async getGoodsListByShopId(shopId: number) {
+        const ds = this.getDataRepository(YtGoodsEntity);
+        return await ds.find({ where: { shopId } });
+    }
+}
+```
+
+## 最佳实践
+
+1. **优先使用 BaseService**
+   - 大多数场景下，继承 `BaseService` 就足够了
+   - 代码更简洁，维护成本更低
+
+2. **只在需要时使用懒加载 Getter**
+   - 当你需要封装 Repository 方法时
+   - 当你需要更复杂的业务逻辑时
+
+3. **避免重复初始化代码**
+   - 不要在构造器中初始化 Repository
+   - 不要在每个方法中手动初始化
+   - 使用 getter 或继承 BaseService
+
+## 完整示例
+
+### 使用懒加载 Getter 的 Service
+
+```typescript
+@Injectable()
+export class YtUserService extends BaseService {
+    private repositoryCache = new Map<string, any>();
+
+    /**
+     * 获取用户Repository（懒加载）
+     * 使用基类的通用方法
+     */
+    private get userRepository(): IUserRepository {
+        return this.createLazyRepository(
+            YtUserEntity,
+            UserRepository,
+            this.repositoryCache
+        );
+    }
+
+    async createUser(dto: CreateUserDto): Promise<CommonServiceResult<YtUserEntity>> {
+        try {
+            // Repository 自动初始化，无需手动调用
+            const user = await this.userRepository.save(...);
+            return CommonServiceResult.success(user);
+        } catch (error) {
+            return CommonServiceResult.error("创建失败");
+        }
+    }
+}
+```
+
+### 需要多个 Repository 的 Service
+
+```typescript
+@Injectable()
+export class ComplexService extends BaseService {
+    private repositoryCache = new Map<string, any>();
+
+    private get userRepository(): IUserRepository {
+        return this.createLazyRepository(YtUserEntity, UserRepository, this.repositoryCache);
+    }
+
+    private get goodsRepository(): IGoodsRepository {
+        return this.createLazyRepository(YtGoodsEntity, GoodsRepository, this.repositoryCache);
+    }
+
+    async complexOperation() {
+        // 自动初始化两个 Repository
+        const user = await this.userRepository.findById(1);
+        const goods = await this.goodsRepository.findById(1);
+    }
+}
+```
+
+### 使用 BaseService 的 Service
+
+```typescript
+export class YtShopService extends BaseService {
+    
+    async getGoodsListByShopId(shopId: number, page: number, pageSize: number) {
+        try {
+            const ds = this.getDataRepository(YtGoodsEntity);
+            const result = await ds.findAndCount({
+                where: { shopId },
+                skip: (page - 1) * pageSize,
+                take: pageSize
+            });
+            return CommonServiceResult.success(result);
+        } catch (error) {
+            return CommonServiceResult.error("查询失败");
+        }
+    }
+}
+```
+
+## 总结
+
+- ✅ **推荐**：简单 CRUD 使用 `BaseService`
+- ✅ **推荐**：复杂逻辑使用懒加载 Getter
+- ❌ **避免**：每个方法都调用 `ensureRepositoryInitialized()`
+- ❌ **避免**：在构造器中初始化 Repository
+
+这样可以让代码更简洁、更易维护。
+
+---
+
+## 相关文档
+
+- 📖 [Service 返回值规范](./SERVICE_RETURN_VALUE_SPECIFICATION.md) - Service 层必须返回 `CommonServiceResult<T>` 对象
+- 📖 [TransactionManager 使用指南](./TRANSACTION_MANAGER_USAGE.md) - 事务管理器的使用
+- 📖 [企业级数据库架构](./ENTERPRISE_DATABASE_ARCHITECTURE.md) - 数据库架构设计
+
+
+