fix:修复模块依赖注入问题并补充架构检查规范
修复问题: - ZulipModule:修正exports配置,导出ZulipCoreModule而非单独服务 - ZulipModule:添加CacheModule.register()解决CACHE_MANAGER依赖 - ZulipGatewayModule:添加LoginCoreModule解决JwtAuthGuard依赖 文档补充(step4-architecture-layer.md): - 新增「应用启动验证」强制检查步骤 - 添加常见启动错误示例和修复方案 - 明确启动验证是步骤4的强制完成条件 - 补充启动验证检查清单和失败处理流程
This commit is contained in:
@@ -672,17 +672,172 @@ export class AuthModule {}
|
|||||||
- Core层是否不依赖业务层
|
- Core层是否不依赖业务层
|
||||||
- 依赖注入是否正确使用
|
- 依赖注入是否正确使用
|
||||||
|
|
||||||
7. **检查架构违规**
|
8. **检查架构违规**
|
||||||
- 识别常见的分层违规模式
|
- 识别常见的分层违规模式
|
||||||
- 检查技术实现和业务逻辑的边界
|
- 检查技术实现和业务逻辑的边界
|
||||||
- 检查协议处理和业务逻辑的边界
|
- 检查协议处理和业务逻辑的边界
|
||||||
- 确保架构清晰度
|
- 确保架构清晰度
|
||||||
|
|
||||||
8. **游戏服务器特殊检查**
|
9. **游戏服务器特殊检查**
|
||||||
- WebSocket Gateway的分层正确性
|
- 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的完整检查!**
|
**如果在本步骤中执行了任何修改操作(调整分层结构、修正依赖关系、重构代码等),必须立即重新执行步骤4的完整检查!**
|
||||||
@@ -697,4 +852,9 @@ export class AuthModule {}
|
|||||||
- ❌ **禁止递增版本号**:不要修改@version字段
|
- ❌ **禁止递增版本号**:不要修改@version字段
|
||||||
- ✅ **仅提供检查报告**:说明检查结果,确认符合规范
|
- ✅ **仅提供检查报告**:说明检查结果,确认符合规范
|
||||||
|
|
||||||
**不能跳过重新检查环节!**
|
**🚀 步骤4完成的强制条件:**
|
||||||
|
1. **架构分层检查通过**:Gateway/Business/Core层职责清晰
|
||||||
|
2. **依赖注入检查通过**:所有Module的imports/exports配置正确
|
||||||
|
3. **🔥 应用启动验证通过**:执行 `pnpm dev` 应用能成功启动,无依赖错误
|
||||||
|
|
||||||
|
**不能跳过应用启动验证环节!如果启动失败,必须修复后重新执行整个步骤4!**
|
||||||
@@ -30,6 +30,7 @@
|
|||||||
*/
|
*/
|
||||||
|
|
||||||
import { Module } from '@nestjs/common';
|
import { Module } from '@nestjs/common';
|
||||||
|
import { CacheModule } from '@nestjs/cache-manager';
|
||||||
// 业务服务
|
// 业务服务
|
||||||
import { ZulipEventProcessorService } from './services/zulip_event_processor.service';
|
import { ZulipEventProcessorService } from './services/zulip_event_processor.service';
|
||||||
import { ZulipAccountsBusinessService } from './services/zulip_accounts_business.service';
|
import { ZulipAccountsBusinessService } from './services/zulip_accounts_business.service';
|
||||||
@@ -42,10 +43,11 @@ import { LoginCoreModule } from '../../core/login_core/login_core.module';
|
|||||||
import { AuthModule } from '../auth/auth.module';
|
import { AuthModule } from '../auth/auth.module';
|
||||||
// 通过接口依赖 ChatModule(解耦)
|
// 通过接口依赖 ChatModule(解耦)
|
||||||
import { ChatModule } from '../chat/chat.module';
|
import { ChatModule } from '../chat/chat.module';
|
||||||
import { DynamicConfigManagerService } from '../../core/zulip_core/services/dynamic_config_manager.service';
|
|
||||||
|
|
||||||
@Module({
|
@Module({
|
||||||
imports: [
|
imports: [
|
||||||
|
// 缓存模块
|
||||||
|
CacheModule.register(),
|
||||||
// Zulip核心服务模块
|
// Zulip核心服务模块
|
||||||
ZulipCoreModule,
|
ZulipCoreModule,
|
||||||
// Zulip账号关联模块
|
// Zulip账号关联模块
|
||||||
@@ -73,8 +75,8 @@ import { DynamicConfigManagerService } from '../../core/zulip_core/services/dyna
|
|||||||
ZulipEventProcessorService,
|
ZulipEventProcessorService,
|
||||||
// 导出账号业务服务
|
// 导出账号业务服务
|
||||||
ZulipAccountsBusinessService,
|
ZulipAccountsBusinessService,
|
||||||
// 重新导出动态配置管理服务(来自ZulipCoreModule)
|
// 重新导出ZulipCoreModule(包含DynamicConfigManagerService)
|
||||||
DynamicConfigManagerService,
|
ZulipCoreModule,
|
||||||
],
|
],
|
||||||
})
|
})
|
||||||
export class ZulipModule {}
|
export class ZulipModule {}
|
||||||
|
|||||||
@@ -31,6 +31,7 @@ import { ZulipAccountsController } from './zulip_accounts.controller';
|
|||||||
// 依赖Business层模块
|
// 依赖Business层模块
|
||||||
import { ZulipModule } from '../../business/zulip/zulip.module';
|
import { ZulipModule } from '../../business/zulip/zulip.module';
|
||||||
import { AuthModule } from '../../business/auth/auth.module';
|
import { AuthModule } from '../../business/auth/auth.module';
|
||||||
|
import { LoginCoreModule } from '../../core/login_core/login_core.module';
|
||||||
|
|
||||||
@Module({
|
@Module({
|
||||||
imports: [
|
imports: [
|
||||||
@@ -38,6 +39,8 @@ import { AuthModule } from '../../business/auth/auth.module';
|
|||||||
ZulipModule,
|
ZulipModule,
|
||||||
// 导入认证模块(用于JwtAuthGuard)
|
// 导入认证模块(用于JwtAuthGuard)
|
||||||
AuthModule,
|
AuthModule,
|
||||||
|
// 导入登录核心模块(JwtAuthGuard依赖)
|
||||||
|
LoginCoreModule,
|
||||||
],
|
],
|
||||||
controllers: [
|
controllers: [
|
||||||
// 动态配置管理控制器
|
// 动态配置管理控制器
|
||||||
|
|||||||
Reference in New Issue
Block a user