forked from datawhale/whale-town-end
docs：添加开发者代码检查规范文档
- 整合AI-Reading的完整7步检查流程 - 提供详细的代码规范标准和检查要求 - 包含游戏服务器特殊要求（WebSocket、双模式架构） - 添加AI-Reading使用指南和最佳实践 主要内容： - 命名规范：文件、变量、类、常量命名标准 - 注释规范：文件头、类、方法注释要求 - 代码质量：未使用代码清理、TODO处理 - 架构分层：Core层和Business层职责分离 - 测试覆盖：一对一测试映射、测试分离 - 功能文档：README文档、API接口文档 - 代码提交：Git变更校验、规范化提交 使用指南： - AI-Reading系统介绍和使用场景 - 详细的使用方法和执行步骤 - 使用技巧和最佳实践建议
This commit is contained in:
moyin
399
docs/开发者代码检查规范.md
Normal file
399
docs/开发者代码检查规范.md
Normal file
@@ -0,0 +1,399 @@
|
||||
# 开发者代码检查规范
|
||||
|
||||
## 🎯 规范目标
|
||||
|
||||
本规范旨在确保代码质量、提升开发效率、维护项目一致性。通过系统化的代码检查流程，保障Whale Town游戏服务器项目的代码标准和技术质量。
|
||||
|
||||
## 📋 检查流程概述
|
||||
|
||||
代码检查分为7个步骤，必须按顺序执行，每步完成后等待确认才能进行下一步：
|
||||
|
||||
1. **步骤1：命名规范检查** - 文件、变量、类、常量命名规范
|
||||
2. **步骤2：注释规范检查** - 文件头、类、方法注释完整性
|
||||
3. **步骤3：代码质量检查** - 清理未使用代码、处理TODO项
|
||||
4. **步骤4：架构分层检查** - Core层和Business层职责分离
|
||||
5. **步骤5：测试覆盖检查** - 一对一测试映射、测试分离
|
||||
6. **步骤6：功能文档生成** - README文档、API接口文档
|
||||
7. **步骤7：代码提交** - Git变更校验、规范化提交
|
||||
|
||||
## 🔄 执行原则
|
||||
|
||||
### ⚠️ 强制要求
|
||||
- **分步执行**：每次只执行一个步骤，严禁跳步骤或合并执行
|
||||
- **等待确认**：每步完成后必须等待确认才能进行下一步
|
||||
- **修改验证**：每次修改文件后必须重新检查该步骤并提供验证报告
|
||||
- **🔥 修改后必须重新执行当前步骤**：如果在当前步骤中发生了任何修改行为，必须立即重新执行该步骤的完整检查
|
||||
- **问题修复后重检**：如果当前步骤出现问题需要修改时，必须在解决问题后重新执行该步骤
|
||||
|
||||
## 📚 详细检查标准
|
||||
|
||||
### 步骤1：命名规范检查
|
||||
|
||||
#### 文件和文件夹命名
|
||||
- **规则**：snake_case（下划线分隔）
|
||||
- **示例**：
|
||||
```
|
||||
✅ 正确：user_controller.ts, admin_operation_log_service.ts
|
||||
❌ 错误：UserController.ts, user-service.ts
|
||||
```
|
||||
|
||||
#### 变量和函数命名
|
||||
- **规则**：camelCase（小驼峰命名）
|
||||
- **示例**：
|
||||
```typescript
|
||||
✅ 正确：const userName = 'test'; function getUserInfo() {}
|
||||
❌ 错误：const UserName = 'test'; function GetUserInfo() {}
|
||||
```
|
||||
|
||||
#### 类和接口命名
|
||||
- **规则**：PascalCase（大驼峰命名）
|
||||
- **示例**：
|
||||
```typescript
|
||||
✅ 正确：class UserService {} interface GameConfig {}
|
||||
❌ 错误：class userService {} interface gameConfig {}
|
||||
```
|
||||
|
||||
#### 常量命名
|
||||
- **规则**：SCREAMING_SNAKE_CASE（全大写+下划线）
|
||||
- **示例**：
|
||||
```typescript
|
||||
✅ 正确：const MAX_RETRY_COUNT = 3; const SALT_ROUNDS = 10;
|
||||
❌ 错误：const maxRetryCount = 3; const saltRounds = 10;
|
||||
```
|
||||
|
||||
#### 文件夹结构扁平化
|
||||
- **≤3个文件**：必须扁平化处理
|
||||
- **≥4个文件**：通常保持独立文件夹
|
||||
- **测试文件位置**：测试文件与源文件放在同一目录
|
||||
|
||||
#### Core层命名规则
|
||||
- **业务支撑模块**：使用_core后缀（如location_broadcast_core/）
|
||||
- **通用工具模块**：不使用后缀（如redis/、logger/）
|
||||
|
||||
### 步骤2：注释规范检查
|
||||
|
||||
#### 文件头注释（必须包含）
|
||||
```typescript
|
||||
/**
|
||||
* 文件功能描述
|
||||
*
|
||||
* 功能描述：
|
||||
* - 主要功能点1
|
||||
* - 主要功能点2
|
||||
*
|
||||
* 职责分离：
|
||||
* - 职责描述1
|
||||
* - 职责描述2
|
||||
*
|
||||
* 最近修改：
|
||||
* - [用户日期]: 修改类型 - 修改内容 (修改者: [用户名称])
|
||||
* - [历史日期]: 修改类型 - 修改内容 (修改者: 历史修改者)
|
||||
*
|
||||
* @author [处理后的作者名称]
|
||||
* @version x.x.x
|
||||
* @since [创建日期]
|
||||
* @lastModified [用户日期]
|
||||
*/
|
||||
```
|
||||
|
||||
#### @author字段处理规范
|
||||
- **保留人名**：如果@author是人名，必须保留不变
|
||||
- **替换AI标识**：只有AI标识（kiro、ChatGPT、Claude、AI等）才可替换为用户名称
|
||||
|
||||
#### 修改记录规范
|
||||
- **修改类型**：代码规范优化、功能新增、功能修改、Bug修复、性能优化、重构
|
||||
- **最多保留5条**：超出时自动删除最旧记录
|
||||
- **版本号递增**：
|
||||
- 修订版本+1：代码规范优化、Bug修复
|
||||
- 次版本+1：功能新增、功能修改
|
||||
- 主版本+1：重构、架构变更
|
||||
|
||||
### 步骤3：代码质量检查
|
||||
|
||||
#### 未使用代码清理
|
||||
- 清理未使用的导入
|
||||
- 清理未使用的变量和方法
|
||||
- 删除未调用的私有方法
|
||||
|
||||
#### 常量定义规范
|
||||
- 使用SCREAMING_SNAKE_CASE
|
||||
- 提取魔法数字为常量
|
||||
- 统一常量命名
|
||||
|
||||
#### TODO项处理（强制要求）
|
||||
- **最终文件不能包含TODO项**
|
||||
- 必须真正实现功能或删除未完成代码
|
||||
|
||||
#### 方法长度检查
|
||||
- **建议**：方法不超过50行
|
||||
- **原则**：一个方法只做一件事
|
||||
- **拆分**：复杂方法拆分为多个小方法
|
||||
|
||||
### 步骤4：架构分层检查
|
||||
|
||||
#### Core层规范
|
||||
- **职责**：专注技术实现，不包含业务逻辑
|
||||
- **命名**：业务支撑模块使用_core后缀，通用工具模块不使用后缀
|
||||
- **依赖**：只能导入其他Core层模块和第三方技术库
|
||||
|
||||
#### Business层规范
|
||||
- **职责**：专注业务逻辑实现，不关心底层技术细节
|
||||
- **依赖**：可以导入Core层模块和其他Business层模块
|
||||
- **禁止**：不能直接使用底层技术实现
|
||||
|
||||
### 步骤5：测试覆盖检查
|
||||
|
||||
#### 严格一对一测试映射
|
||||
- **强制要求**：每个测试文件必须严格对应一个源文件
|
||||
- **禁止多对一**：不允许一个测试文件测试多个源文件
|
||||
- **命名对应**：测试文件名必须与源文件名完全对应
|
||||
|
||||
#### 需要测试文件的类型
|
||||
```typescript
|
||||
✅ 必须有测试文件：
|
||||
- *.service.ts # Service类
|
||||
- *.controller.ts # Controller类
|
||||
- *.gateway.ts # Gateway类
|
||||
- *.guard.ts # Guard类
|
||||
- *.interceptor.ts # Interceptor类
|
||||
- *.middleware.ts # Middleware类
|
||||
|
||||
❌ 不需要测试文件：
|
||||
- *.dto.ts # DTO类
|
||||
- *.interface.ts # Interface文件
|
||||
- *.constants.ts # Constants文件
|
||||
```
|
||||
|
||||
#### 测试分离架构
|
||||
```
|
||||
test/
|
||||
├── integration/ # 集成测试
|
||||
├── e2e/ # 端到端测试
|
||||
├── performance/ # 性能测试
|
||||
├── property/ # 属性测试
|
||||
└── fixtures/ # 测试数据和工具
|
||||
```
|
||||
|
||||
### 步骤6：功能文档生成
|
||||
|
||||
#### README文档结构
|
||||
每个功能模块文件夹都必须有README.md文档，包含：
|
||||
- 模块功能描述
|
||||
- 对外提供的接口
|
||||
- 对外API接口（如适用）
|
||||
- WebSocket事件接口（如适用）
|
||||
- 使用的项目内部依赖
|
||||
- 核心特性
|
||||
- 潜在风险
|
||||
|
||||
#### 游戏服务器特殊要求
|
||||
- **WebSocket Gateway**：详细的事件接口文档
|
||||
- **双模式服务**：模式特点和切换指南
|
||||
- **属性测试**：测试策略说明
|
||||
|
||||
### 步骤7：代码提交
|
||||
|
||||
#### Git变更检查
|
||||
- 检查Git状态和变更内容
|
||||
- 校验文件修改记录与实际修改内容一致性
|
||||
- 确认修改记录、版本号、时间戳正确更新
|
||||
|
||||
#### 分支管理规范
|
||||
```bash
|
||||
# 代码规范优化分支
|
||||
feature/code-standard-optimization-[日期]
|
||||
|
||||
# Bug修复分支
|
||||
fix/[具体问题描述]
|
||||
|
||||
# 功能新增分支
|
||||
feature/[功能名称]
|
||||
|
||||
# 重构分支
|
||||
refactor/[模块名称]
|
||||
```
|
||||
|
||||
#### 提交信息规范
|
||||
```bash
|
||||
<类型>：<简短描述>
|
||||
|
||||
[可选的详细描述]
|
||||
```
|
||||
|
||||
提交类型：
|
||||
- `style`：代码规范优化
|
||||
- `refactor`：代码重构
|
||||
- `feat`：新功能
|
||||
- `fix`：Bug修复
|
||||
- `perf`：性能优化
|
||||
- `test`：测试相关
|
||||
- `docs`：文档更新
|
||||
|
||||
## 🎮 游戏服务器特殊要求
|
||||
|
||||
### WebSocket相关
|
||||
- **Gateway文件**：必须有完整的连接、消息处理测试
|
||||
- **实时通信**：心跳检测、重连机制、性能监控
|
||||
- **事件文档**：详细的输入输出格式说明
|
||||
|
||||
### 双模式架构
|
||||
- **内存服务和数据库服务**：都需要完整测试覆盖
|
||||
- **行为一致性**：确保两种模式行为完全一致
|
||||
- **切换机制**：提供模式切换指南和数据迁移工具
|
||||
|
||||
### 属性测试
|
||||
- **管理员模块**：使用fast-check进行属性测试
|
||||
- **随机化测试**：验证边界条件和异常处理
|
||||
- **测试策略**：详细的属性测试实现说明
|
||||
|
||||
## 📋 统一报告模板
|
||||
|
||||
每步完成后使用此模板报告：
|
||||
|
||||
```
|
||||
## 步骤X：[步骤名称]检查报告
|
||||
|
||||
### 🔍 检查结果
|
||||
[发现的问题列表]
|
||||
|
||||
### 🛠️ 修正方案
|
||||
[具体修正建议]
|
||||
|
||||
### ✅ 完成状态
|
||||
- 检查项1 ✓/✗
|
||||
- 检查项2 ✓/✗
|
||||
|
||||
**请确认修正方案，确认后进行下一步骤**
|
||||
```
|
||||
|
||||
## 🚨 全局约束
|
||||
|
||||
### 文件修改记录规范
|
||||
每次执行完修改后，文件顶部都需要更新：
|
||||
- 添加修改记录（最多保留5条）
|
||||
- 更新版本号（按规则递增）
|
||||
- 更新@lastModified字段
|
||||
- 正确处理@author字段
|
||||
|
||||
### 时间更新规则
|
||||
- **仅检查不修改**：不更新@lastModified字段
|
||||
- **实际修改才更新**：只有真正修改了文件内容时才更新
|
||||
- **Git变更检测**：通过git检查文件是否有实际变更
|
||||
|
||||
### 修改验证流程
|
||||
任何步骤中发生修改行为后，必须立即重新执行该步骤：
|
||||
```
|
||||
步骤执行中 → 发现问题 → 执行修改 → 🔥 立即重新执行该步骤 → 验证无遗漏 → 用户确认 → 下一步骤
|
||||
```
|
||||
|
||||
## 🔧 AI-Reading使用指南
|
||||
|
||||
### 什么是AI-Reading
|
||||
|
||||
AI-Reading是一套系统化的代码检查执行指南，专门为Whale Town游戏服务器项目设计。它提供了完整的7步代码检查流程，确保代码质量和项目规范的一致性。
|
||||
|
||||
### 使用场景
|
||||
|
||||
#### 适用情况
|
||||
- **新功能开发完成后**：确保新代码符合项目规范
|
||||
- **Bug修复后**：验证修复代码的质量和规范性
|
||||
- **代码重构时**：保证重构后代码的一致性和质量
|
||||
- **代码审查前**：提前发现和解决规范问题
|
||||
- **项目维护期**：定期检查和优化代码质量
|
||||
|
||||
#### 不适用情况
|
||||
- **紧急热修复**：紧急生产问题修复时可简化流程
|
||||
- **实验性代码**：概念验证或原型开发阶段
|
||||
- **第三方代码集成**：外部库或组件的集成
|
||||
|
||||
### 使用方法
|
||||
|
||||
#### 1. 准备阶段
|
||||
在开始检查前，必须收集以下信息：
|
||||
- **用户当前日期**：用于修改记录和时间戳更新
|
||||
- **用户名称**：用于@author字段处理和修改记录
|
||||
|
||||
#### 2. 执行流程
|
||||
```
|
||||
用户请求代码检查
|
||||
↓
|
||||
收集用户信息（日期、名称）
|
||||
↓
|
||||
识别项目特性（NestJS游戏服务器）
|
||||
↓
|
||||
按顺序执行7个步骤
|
||||
↓
|
||||
每步完成后等待用户确认
|
||||
↓
|
||||
如有修改立即重新执行当前步骤
|
||||
```
|
||||
|
||||
#### 3. 使用AI-Reading的具体步骤
|
||||
|
||||
**第一步：启动检查**
|
||||
```
|
||||
请使用ai-reading对[模块名称]进行代码检查
|
||||
当前日期：[YYYY-MM-DD]
|
||||
用户名称：[您的名称]
|
||||
```
|
||||
|
||||
**第二步：逐步执行**
|
||||
AI会按照以下顺序执行：
|
||||
1. 读取对应步骤的详细指导文档
|
||||
2. 执行该步骤的所有检查项
|
||||
3. 提供详细的检查报告
|
||||
4. 等待用户确认后进行下一步
|
||||
|
||||
**第三步：处理修改**
|
||||
如果某步骤需要修改代码：
|
||||
1. AI会执行必要的修改操作
|
||||
2. 更新文件的修改记录和版本信息
|
||||
3. 立即重新执行该步骤进行验证
|
||||
4. 提供验证报告确认无遗漏问题
|
||||
|
||||
**第四步：完成检查**
|
||||
所有7个步骤完成后：
|
||||
1. 提供完整的检查总结报告
|
||||
2. 确认所有问题已解决
|
||||
3. 代码已准备好进行提交或部署
|
||||
|
||||
### 使用技巧
|
||||
|
||||
#### 高效使用
|
||||
- **批量检查**：可以一次性检查整个模块或功能
|
||||
- **增量检查**：只检查修改的文件和相关依赖
|
||||
- **定期检查**：建议每周对核心模块进行一次完整检查
|
||||
|
||||
#### 注意事项
|
||||
- **不要跳步骤**：必须按顺序完成所有步骤
|
||||
- **确认每一步**：每步完成后仔细检查报告再确认
|
||||
- **保存检查记录**：保留检查报告用于后续参考
|
||||
- **及时处理问题**：发现问题立即修复，不要积累
|
||||
|
||||
#### 常见问题处理
|
||||
- **检查时间过长**：可以分模块进行，不必一次性检查整个项目
|
||||
- **修改冲突**：如果与其他开发者的修改冲突，先解决冲突再继续检查
|
||||
- **测试失败**：如果测试不通过，必须先修复测试再继续后续步骤
|
||||
|
||||
### 最佳实践
|
||||
|
||||
#### 团队协作
|
||||
- **统一标准**：团队成员都使用相同的AI-Reading流程
|
||||
- **代码审查**：在代码审查前先完成AI-Reading检查
|
||||
- **知识分享**：定期分享AI-Reading发现的问题和解决方案
|
||||
|
||||
#### 质量保证
|
||||
- **持续改进**：根据检查结果不断优化代码规范
|
||||
- **文档同步**：确保文档与代码实现保持一致
|
||||
- **测试覆盖**：通过AI-Reading确保测试覆盖率达标
|
||||
|
||||
#### 效率提升
|
||||
- **自动化集成**：考虑将AI-Reading集成到CI/CD流程
|
||||
- **模板使用**：使用标准模板减少重复工作
|
||||
- **工具辅助**：结合IDE插件和代码格式化工具
|
||||
|
||||
通过正确使用AI-Reading，可以显著提升代码质量，减少bug数量，提高开发效率，确保项目的长期可维护性。
|
||||
|
||||
---
|
||||
|
||||
**重要提醒**：使用AI-Reading时，请严格按照7步流程执行，不要跳过任何步骤，确保每一步都得到充分验证后再进行下一步。
|
||||
Reference in New Issue
Block a user