docs：补充 Gateway 层架构规范检查说明

- 新增 Gateway 层职责定义和检查规范 - 添加 Gateway 层协议处理示例代码 - 补充 Gateway 层依赖关系和文件类型检查 - 完善 4 层架构说明（Gateway、Business、Core、Common） - 增加 Gateway 层常见违规示例
2026-01-14 13:17:44 +08:00
parent 41c33d6159
commit cf431c210a
1 changed files with 189 additions and 13 deletions
--- a/docs/ai-reading/step4-architecture-layer.md
+++ b/docs/ai-reading/step4-architecture-layer.md
@@ -24,21 +24,142 @@
 ### 项目分层结构
 ```
 src/
-├── core/           # Core层：技术实现层
-│   ├── db/         # 数据访问
-│   ├── redis/      # 缓存服务
-│   └── utils/      # 工具服务
+├── gateway/        # Gateway层：网关层（HTTP协议处理）
+│   ├── auth/       # 认证网关
+│   ├── users/      # 用户网关
+│   └── admin/      # 管理网关
 ├── business/       # Business层：业务逻辑层
 │   ├── auth/       # 认证业务
 │   ├── users/      # 用户业务
 │   └── admin/      # 管理业务
+├── core/           # Core层：技术实现层
+│   ├── db/         # 数据访问
+│   ├── redis/      # 缓存服务
+│   └── utils/      # 工具服务
 └── common/         # 公共层：通用组件
 ```

+### 4层架构说明
+
+**Gateway Layer（网关层）**
+- 位置：`src/gateway/`
+- 职责：HTTP协议处理、数据验证、路由管理、认证守卫、错误转换
+- 依赖：Business层
+
+**Business Layer（业务层）**
+- 位置：`src/business/`
+- 职责：业务逻辑实现、业务流程控制、服务协调、业务规则验证
+- 依赖：Core层
+
+**Core Layer（核心层）**
+- 位置：`src/core/`
+- 职责：数据访问、基础设施、外部系统集成、技术实现细节
+- 依赖：无（或第三方库）
+
 ### 检查范围
 - **限制范围**：仅检查当前执行检查的文件夹
 - **不跨模块**：不考虑其他同层功能模块
 - **专注职责**：确保当前模块职责清晰
+- **按层检查**：根据文件夹所在层级应用对应的检查规则
+
+## 🌐 Gateway层规范检查
+
+### 职责定义
+**Gateway层专注HTTP协议处理，不包含业务逻辑**
+
+### Gateway层协议处理示例
+```typescript
+// ✅ 正确：Gateway层只做协议转换
+@Controller('auth')
+export class LoginController {
+  constructor(private readonly loginService: LoginService) {}
+
+  @Post('login')
+  async login(@Body() loginDto: LoginDto, @Res() res: Response): Promise<void> {
+    // 1. 接收HTTP请求，使用DTO验证
+    // 2. 调用Business层服务
+    const result = await this.loginService.login({
+      identifier: loginDto.identifier,
+      password: loginDto.password
+    });
+    
+    // 3. 将业务响应转换为HTTP响应
+    this.handleResponse(result, res);
+  }
+  
+  private handleResponse(result: any, res: Response): void {
+    if (result.success) {
+      res.status(HttpStatus.OK).json(result);
+    } else {
+      const statusCode = this.getErrorStatusCode(result);
+      res.status(statusCode).json(result);
+    }
+  }
+}
+
+// ❌ 错误：Gateway层包含业务逻辑
+@Controller('auth')
+export class LoginController {
+  @Post('login')
+  async login(@Body() loginDto: LoginDto): Promise<any> {
+    // 错误：在Controller中实现业务逻辑
+    const user = await this.userRepository.findOne({ 
+      where: { username: loginDto.identifier } 
+    });
+    
+    if (!user) {
+      throw new NotFoundException('用户不存在');
+    }
+    
+    const isValid = await bcrypt.compare(loginDto.password, user.password);
+    if (!isValid) {
+      throw new UnauthorizedException('密码错误');
+    }
+    
+    // ... 更多业务逻辑
+  }
+}
+```
+
+### Gateway层依赖关系检查
+```typescript
+// ✅ 允许的导入
+import { Controller, Post, Body, Res } from '@nestjs/common';  # NestJS框架
+import { Response } from 'express';                            # Express类型
+import { LoginService } from '../../business/auth/login.service'; # Business层服务
+import { LoginDto } from './dto/login.dto';                    # 同层DTO
+import { JwtAuthGuard } from './jwt_auth.guard';              # 同层Guard
+
+// ❌ 禁止的导入
+import { LoginCoreService } from '../../core/login_core/login_core.service'; # 跳过Business层直接调用Core层
+import { UsersRepository } from '../../core/db/users/users.repository';      # 直接访问数据层
+import { RedisService } from '../../core/redis/redis.service';               # 直接访问技术服务
+```
+
+### Gateway层文件类型检查
+```typescript
+// ✅ Gateway层应该包含的文件类型
+- *.controller.ts          # HTTP控制器
+- *.dto.ts                 # 数据传输对象
+- *.guard.ts               # 认证/授权守卫
+- *.decorator.ts           # 参数装饰器
+- *.interceptor.ts         # 拦截器
+- *.filter.ts              # 异常过滤器
+- *.gateway.module.ts      # 网关模块
+
+// ❌ Gateway层不应该包含的文件类型
+- *.service.ts             # 业务服务（应在Business层）
+- *.repository.ts          # 数据仓库（应在Core层）
+- *.entity.ts              # 数据实体（应在Core层）
+```
+
+### Gateway层职责检查清单
+- [ ] Controller方法是否只做协议转换？
+- [ ] 是否使用DTO进行数据验证？
+- [ ] 是否调用Business层服务而非Core层？
+- [ ] 是否有统一的错误处理机制？
+- [ ] 是否包含Swagger API文档？
+- [ ] 是否使用限流和超时保护？

 ## 🔧 Core层规范检查

@@ -202,6 +323,42 @@ import { DatabaseConnection } from '../../core/db/connection';

 ## 🚨 常见架构违规

+### Gateway层违规示例
+```typescript
+// ❌ 错误：Gateway层包含业务逻辑
+@Controller('users')
+export class UserController {
+  @Post('register')
+  async register(@Body() registerDto: RegisterDto): Promise<User> {
+    // 违规：在Controller中实现业务验证
+    if (registerDto.age < 18) {
+      throw new BadRequestException('用户年龄必须大于18岁');
+    }
+    
+    // 违规：在Controller中协调多个服务
+    const user = await this.userCoreService.create(registerDto);
+    await this.emailService.sendWelcomeEmail(user.email);
+    await this.zulipService.createAccount(user);
+    
+    return user;
+  }
+}
+
+// ❌ 错误：Gateway层直接调用Core层
+@Controller('auth')
+export class LoginController {
+  constructor(
+    private readonly loginCoreService: LoginCoreService,  // 违规：跳过Business层
+  ) {}
+  
+  @Post('login')
+  async login(@Body() loginDto: LoginDto): Promise<any> {
+    // 违规：直接调用Core层服务
+    return this.loginCoreService.login(loginDto);
+  }
+}
+```
+
 ### Business层违规示例
 ```typescript
 // ❌ 错误：Business层包含技术实现细节
@@ -288,30 +445,49 @@ export class UsersBusinessService {
 ## 🔍 检查执行步骤

 1. **识别当前模块的层级**
-   - 确定是Core层还是Business层
+   - 确定是Gateway层、Business层还是Core层
   - 检查文件夹路径和命名
+   - 根据层级应用对应的检查规则

-2. **检查Core层命名规范**
+2. **Gateway层检查（如果是Gateway层）**
+   - 检查是否只包含协议处理代码
+   - 检查是否使用DTO进行数据验证
+   - 检查是否只调用Business层服务
+   - 检查是否有统一的错误处理
+   - 检查文件类型是否符合Gateway层规范
+
+3. **Business层检查（如果是Business层）**
+   - 检查是否只包含业务逻辑
+   - 检查是否协调多个Core层服务
+   - 检查是否返回统一的业务响应
+   - 检查是否不包含HTTP协议处理
+
+4. **Core层检查（如果是Core层）**
+   - 检查Core层命名规范
   - 业务支撑模块是否使用_core后缀
   - 通用工具模块是否不使用后缀
   - 根据模块职责判断命名正确性
+   - 检查是否只包含技术实现

-3. **检查职责分离**
-   - Core层是否只包含技术实现
+5. **检查职责分离**
+   - Gateway层是否只做协议转换
   - Business层是否只包含业务逻辑
+   - Core层是否只包含技术实现
   - 是否有跨层职责混乱

-4. **检查依赖关系**
-   - Core层是否导入了Business层模块
-   - Business层是否直接使用底层技术实现
+6. **检查依赖关系**
+   - Gateway层是否只依赖Business层
+   - Business层是否只依赖Core层
+   - Core层是否不依赖业务层
   - 依赖注入是否正确使用

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

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