fix：修复模块依赖注入问题并补充架构检查规范

修复问题： - ZulipModule：修正exports配置，导出ZulipCoreModule而非单独服务 - ZulipModule：添加CacheModule.register()解决CACHE_MANAGER依赖 - ZulipGatewayModule：添加LoginCoreModule解决JwtAuthGuard依赖文档补充（step4-architecture-layer.md）： - 新增「应用启动验证」强制检查步骤 - 添加常见启动错误示例和修复方案 - 明确启动验证是步骤4的强制完成条件 - 补充启动验证检查清单和失败处理流程
2026-01-15 11:09:46 +08:00
parent 4265943375
commit 8132300e38
3 changed files with 171 additions and 6 deletions
--- a/docs/ai-reading/step4-architecture-layer.md
+++ b/docs/ai-reading/step4-architecture-layer.md
@@ -672,17 +672,172 @@ export class AuthModule {}
   - Core层是否不依赖业务层
   - 依赖注入是否正确使用

-7. **检查架构违规**
+8. **检查架构违规**
   - 识别常见的分层违规模式
   - 检查技术实现和业务逻辑的边界
   - 检查协议处理和业务逻辑的边界
   - 确保架构清晰度

-8. **游戏服务器特殊检查**
+9. **游戏服务器特殊检查**
   - WebSocket Gateway的分层正确性
   - 双模式服务的架构设计
   - 实时通信组件的职责分离

+10. **🚀 应用启动验证（强制步骤）**
+    - 执行 `pnpm dev` 或 `npm run dev` 启动应用
+    - 验证应用能够成功启动，无模块依赖错误
+    - 检查控制台是否有依赖注入失败的错误信息
+    - 如有启动错误，必须修复后重新验证
+
+## 🚀 应用启动验证（强制要求）
+
+### 为什么需要启动验证？
+**静态代码检查无法发现所有的模块依赖问题！** 以下问题只有在应用启动时才会暴露：
+
+1. **Module exports 配置错误**：导出了不属于当前模块的服务
+2. **依赖注入链断裂**：中间模块未正确导出依赖
+3. **循环依赖问题**：模块间存在循环引用
+4. **Provider 注册遗漏**：服务未在正确的模块中注册
+5. **CacheModule/ConfigModule 等全局模块缺失**
+
+### 常见启动错误示例
+
+#### 错误1：导出不属于当前模块的服务
+```
+UnknownExportException [Error]: Nest cannot export a provider/module that 
+is not a part of the currently processed module (ZulipModule). 
+Please verify whether the exported DynamicConfigManagerService is available 
+in this particular context.
+```
+
+**原因**：ZulipModule 尝试导出 DynamicConfigManagerService，但该服务来自 ZulipCoreModule，不是 ZulipModule 自己的 provider。
+
+**修复方案**：
+```typescript
+// ❌ 错误：直接导出其他模块的服务
+@Module({
+  imports: [ZulipCoreModule],
+  exports: [DynamicConfigManagerService],  // 错误！
+})
+export class ZulipModule {}
+
+// ✅ 正确：导出整个模块
+@Module({
+  imports: [ZulipCoreModule],
+  exports: [ZulipCoreModule],  // 正确：导出模块而非服务
+})
+export class ZulipModule {}
+```
+
+#### 错误2：依赖注入失败
+```
+Nest can't resolve dependencies of the JwtAuthGuard (?). 
+Please make sure that the argument LoginCoreService at index [0] 
+is available in the ZulipGatewayModule context.
+```
+
+**原因**：JwtAuthGuard 需要 LoginCoreService，但 ZulipGatewayModule 没有导入 LoginCoreModule。
+
+**修复方案**：
+```typescript
+// ❌ 错误：缺少必要的模块导入
+@Module({
+  imports: [ZulipModule, AuthModule],
+  providers: [JwtAuthGuard],
+})
+export class ZulipGatewayModule {}
+
+// ✅ 正确：添加缺失的模块导入
+@Module({
+  imports: [
+    ZulipModule, 
+    AuthModule,
+    LoginCoreModule,  // 添加：JwtAuthGuard 依赖 LoginCoreService
+  ],
+  providers: [JwtAuthGuard],
+})
+export class ZulipGatewayModule {}
+```
+
+#### 错误3：CACHE_MANAGER 未注册
+```
+Nest can't resolve dependencies of the SomeService (?). 
+Please make sure that the argument "CACHE_MANAGER" at index [2] 
+is available in the SomeModule context.
+```
+
+**原因**：服务使用了 @Inject(CACHE_MANAGER)，但模块未导入 CacheModule。
+
+**修复方案**：
+```typescript
+// ❌ 错误：缺少 CacheModule
+@Module({
+  imports: [OtherModule],
+  providers: [SomeService],
+})
+export class SomeModule {}
+
+// ✅ 正确：添加 CacheModule
+import { CacheModule } from '@nestjs/cache-manager';
+
+@Module({
+  imports: [
+    CacheModule.register(),  // 添加缓存模块
+    OtherModule,
+  ],
+  providers: [SomeService],
+})
+export class SomeModule {}
+```
+
+### 启动验证执行流程
+
+```bash
+# 1. 执行启动命令
+pnpm dev
+# 或
+npm run dev
+
+# 2. 观察控制台输出，检查是否有以下错误类型：
+# - UnknownExportException
+# - Nest can't resolve dependencies
+# - Circular dependency detected
+# - Module not found
+
+# 3. 如果启动成功，应该看到类似输出：
+# [Nest] LOG [NestFactory] Starting Nest application...
+# [Nest] LOG [RoutesResolver] AppController {/}: +Xms
+# [Nest] LOG [NestApplication] Nest application successfully started +Xms
+
+# 4. 验证健康检查接口
+curl http://localhost:3000/health
+# 应返回：{"status":"ok",...}
+```
+
+### 启动验证检查清单
+
+- [ ] 执行 `pnpm dev` 或 `npm run dev`
+- [ ] 确认无 UnknownExportException 错误
+- [ ] 确认无依赖注入失败错误
+- [ ] 确认无循环依赖错误
+- [ ] 确认应用成功启动并监听端口
+- [ ] 验证健康检查接口返回正常
+- [ ] 如有错误，修复后重新启动验证
+
+### 🚨 启动验证失败处理
+
+**如果启动验证失败，必须：**
+1. **分析错误信息**：识别具体的模块和依赖问题
+2. **定位问题模块**：找到报错的 Module 文件
+3. **修复依赖配置**：
+   - 添加缺失的 imports
+   - 修正错误的 exports
+   - 注册缺失的 providers
+4. **重新启动验证**：修复后必须再次执行启动验证
+5. **记录修改**：更新文件头部的修改记录
+
+**🔥 重要：启动验证是步骤4的强制完成条件，不能跳过！**
+
 ## 🔥 重要提醒

 **如果在本步骤中执行了任何修改操作（调整分层结构、修正依赖关系、重构代码等），必须立即重新执行步骤4的完整检查！**
@@ -697,4 +852,9 @@ export class AuthModule {}
 - ❌ **禁止递增版本号**：不要修改@version字段
 - ✅ **仅提供检查报告**：说明检查结果，确认符合规范

-**不能跳过重新检查环节！**
+**🚀 步骤4完成的强制条件：**
+1. **架构分层检查通过**：Gateway/Business/Core层职责清晰
+2. **依赖注入检查通过**：所有Module的imports/exports配置正确
+3. **🔥 应用启动验证通过**：执行 `pnpm dev` 应用能成功启动，无依赖错误
+
+**不能跳过应用启动验证环节！如果启动失败，必须修复后重新执行整个步骤4！**