From cf431c210a6e5f160640e86c84455e4a8d173e7b Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 14 Jan 2026 13:17:44 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E8=A1=A5=E5=85=85=20Gateway=20?= =?UTF-8?q?=E5=B1=82=E6=9E=B6=E6=9E=84=E8=A7=84=E8=8C=83=E6=A3=80=E6=9F=A5?= =?UTF-8?q?=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 Gateway 层职责定义和检查规范 - 添加 Gateway 层协议处理示例代码 - 补充 Gateway 层依赖关系和文件类型检查 - 完善 4 层架构说明（Gateway、Business、Core、Common） - 增加 Gateway 层常见违规示例 --- docs/ai-reading/step4-architecture-layer.md | 202 ++++++++++++++++++-- 1 file changed, 189 insertions(+), 13 deletions(-) diff --git a/docs/ai-reading/step4-architecture-layer.md b/docs/ai-reading/step4-architecture-layer.md index eb0d148..2417eda 100644 --- 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 { + // 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 { + // 错误：在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 { + // 违规：在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 { + // 违规：直接调用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的分层正确性 - 双模式服务的架构设计 - 实时通信组件的职责分离