forked from datawhale/whale-town-end
251 lines
9.7 KiB
Markdown
251 lines
9.7 KiB
Markdown
# 步骤1：命名规范检查
|
||
|
||
## ⚠️ 执行前必读规范
|
||
|
||
**🔥 重要：在执行本步骤之前，AI必须先完整阅读同级目录下的 `README.md` 文件！**
|
||
|
||
该README文件包含：
|
||
- 🎯 执行前准备和用户信息收集要求
|
||
- 🔄 强制执行原则和分步执行流程
|
||
- 🔥 修改后立即重新执行当前步骤的强制规则
|
||
- 📝 文件修改记录规范和版本号递增规则
|
||
- 🧪 测试文件调试规范和测试指令使用规范
|
||
- 🚨 全局约束和游戏服务器特殊要求
|
||
|
||
**不阅读README直接执行步骤将导致执行不规范，违反项目要求！**
|
||
|
||
---
|
||
|
||
## 🎯 检查目标
|
||
检查和修正所有命名规范问题，确保项目代码命名一致性。
|
||
|
||
## 📋 命名规范标准
|
||
|
||
### 文件和文件夹命名
|
||
|
||
#### 🚨 NestJS 框架文件命名规范（重要）
|
||
**本项目使用 NestJS 框架，框架相关文件命名规则：**
|
||
|
||
**命名组成 = 文件名（snake_case） + 类型标识符（点分隔） + 扩展名**
|
||
|
||
```
|
||
✅ 正确的 NestJS 文件命名：
|
||
- login.controller.ts # 单词文件名 + .controller
|
||
- user_profile.service.ts # snake_case文件名 + .service
|
||
- auth_core.module.ts # snake_case文件名 + .module
|
||
- login_request.dto.ts # snake_case文件名 + .dto
|
||
- jwt_auth.guard.ts # snake_case文件名 + .guard
|
||
- current_user.decorator.ts # snake_case文件名 + .decorator
|
||
- user_profile.controller.spec.ts # snake_case文件名 + .controller.spec
|
||
|
||
❌ 错误的命名示例：
|
||
- loginController.ts # 错误！应该是 login.controller.ts
|
||
- user-profile.service.ts # 错误！应该是 user_profile.service.ts
|
||
- authCore.module.ts # 错误！应该是 auth_core.module.ts
|
||
- login_controller.ts # 错误！类型标识符应该用点分隔，不是下划线
|
||
```
|
||
|
||
**关键规则：**
|
||
1. **文件名部分**：使用 snake_case（如 `user_profile`、`auth_core`）
|
||
2. **类型标识符**：使用点分隔（如 `.controller`、`.service`）
|
||
3. **完整格式**：`文件名.类型标识符.ts`（如 `user_profile.service.ts`）
|
||
|
||
**NestJS 文件类型标识符（必须使用点分隔）：**
|
||
- `.controller.ts` - 控制器（如 `user_auth.controller.ts`）
|
||
- `.service.ts` - 服务（如 `user_profile.service.ts`）
|
||
- `.module.ts` - 模块（如 `auth_core.module.ts`）
|
||
- `.dto.ts` - 数据传输对象（如 `login_request.dto.ts`）
|
||
- `.entity.ts` - 实体（如 `user_account.entity.ts`）
|
||
- `.interface.ts` - 接口（如 `game_config.interface.ts`）
|
||
- `.guard.ts` - 守卫（如 `jwt_auth.guard.ts`）
|
||
- `.interceptor.ts` - 拦截器（如 `response_transform.interceptor.ts`）
|
||
- `.pipe.ts` - 管道（如 `validation_pipe.pipe.ts`）
|
||
- `.filter.ts` - 过滤器（如 `http_exception.filter.ts`）
|
||
- `.decorator.ts` - 装饰器（如 `current_user.decorator.ts`）
|
||
- `.middleware.ts` - 中间件（如 `logger_middleware.middleware.ts`）
|
||
- `.spec.ts` - 单元测试（如 `user_profile.service.spec.ts`）
|
||
- `.e2e.spec.ts` - E2E 测试（如 `auth_flow.e2e.spec.ts`）
|
||
|
||
**命名规则说明：**
|
||
1. **文件名使用 snake_case**：多个单词用下划线连接（如 `user_profile`、`auth_core`）
|
||
2. **类型标识符使用点分隔**：遵循 NestJS/Angular 风格（如 `.controller`、`.service`）
|
||
3. **组合格式**：`snake_case文件名.类型标识符.ts`
|
||
4. **社区标准**：这是本项目结合 NestJS 规范和 snake_case 约定的标准做法
|
||
|
||
#### 普通文件和文件夹命名
|
||
- **规则**：snake_case（下划线分隔），保持项目一致性
|
||
- **适用范围**：非 NestJS 框架文件、工具类、配置文件、普通文件夹等
|
||
- **示例**：
|
||
```
|
||
✅ 正确：user_utils.ts, admin_operation_log.ts, config_loader.ts
|
||
❌ 错误：UserUtils.ts, user-utils.ts, adminOperationLog.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;
|
||
```
|
||
|
||
### 路由命名
|
||
- **规则**：kebab-case（短横线分隔）
|
||
- **示例**：
|
||
```typescript
|
||
✅ 正确：@Get('user/get-info') @Post('room/join-room')
|
||
❌ 错误：@Get('user/getInfo') @Post('room/joinRoom')
|
||
```
|
||
|
||
## 🎮 游戏服务器特殊文件类型
|
||
|
||
### WebSocket相关文件
|
||
```
|
||
✅ 正确命名：
|
||
- location_broadcast.gateway.ts # WebSocket网关
|
||
- websocket_auth.guard.ts # WebSocket认证守卫
|
||
- realtime_chat.service.ts # 实时通信服务
|
||
```
|
||
|
||
### 双模式服务文件
|
||
```
|
||
✅ 正确命名：
|
||
- users_memory.service.ts # 内存模式服务
|
||
- users_database.service.ts # 数据库模式服务
|
||
- file_redis.service.ts # Redis文件存储
|
||
```
|
||
|
||
### 测试文件分类
|
||
```
|
||
✅ 正确命名：
|
||
- user.service.spec.ts # 单元测试
|
||
- admin.integration.spec.ts # 集成测试
|
||
- location.property.spec.ts # 属性测试（管理员模块）
|
||
- auth.e2e.spec.ts # E2E测试
|
||
- websocket.perf.spec.ts # 性能测试
|
||
```
|
||
|
||
## 🏗️ 文件夹结构检查
|
||
|
||
### 检查方法（必须使用工具）
|
||
1. **使用listDirectory工具**：`listDirectory(path, depth=2)`获取完整结构
|
||
2. **统计文件数量**：逐个文件夹统计文件数量
|
||
3. **识别单文件文件夹**：只有1个文件的文件夹
|
||
4. **执行扁平化**：将文件移动到上级目录
|
||
5. **更新引用路径**：修改所有import语句
|
||
|
||
### 扁平化标准
|
||
- **1个文件**：必须扁平化处理
|
||
- **2个文件**：建议扁平化处理（除非是完整功能模块）
|
||
- **≥3个文件**：保持独立文件夹
|
||
- **完整功能模块**：即使文件较少也可保持独立（需特殊说明）
|
||
|
||
### 测试文件位置规范（重要）
|
||
- ✅ **正确**：测试文件与源文件放在同一目录
|
||
- ❌ **错误**：测试文件放在单独的tests/、test/、spec/、__tests__/文件夹
|
||
|
||
```
|
||
✅ 正确结构：
|
||
src/business/auth/
|
||
├── auth.service.ts
|
||
├── auth.service.spec.ts
|
||
├── auth.controller.ts
|
||
└── auth.controller.spec.ts
|
||
|
||
❌ 错误结构：
|
||
src/business/auth/
|
||
├── auth.service.ts
|
||
├── auth.controller.ts
|
||
└── tests/
|
||
├── auth.service.spec.ts
|
||
└── auth.controller.spec.ts
|
||
```
|
||
|
||
## 🔧 Core层命名规则
|
||
|
||
### 业务支撑模块（使用_core后缀）
|
||
专门为特定业务功能提供技术支撑：
|
||
```
|
||
✅ 正确：
|
||
- location_broadcast_core/ # 为位置广播业务提供技术支撑
|
||
- admin_core/ # 为管理员业务提供技术支撑
|
||
- user_auth_core/ # 为用户认证业务提供技术支撑
|
||
```
|
||
|
||
### 通用工具模块（不使用后缀）
|
||
提供可复用的数据访问或技术服务：
|
||
```
|
||
✅ 正确：
|
||
- user_profiles/ # 通用用户档案数据访问
|
||
- redis/ # 通用Redis技术封装
|
||
- logger/ # 通用日志工具服务
|
||
```
|
||
|
||
### 判断方法
|
||
```
|
||
1. 模块是否专门为某个特定业务服务？
|
||
├─ 是 → 使用_core后缀
|
||
└─ 否 → 不使用后缀
|
||
|
||
2. 实际案例：
|
||
- user_profiles: 通用数据访问 → 不使用后缀 ✓
|
||
- location_broadcast_core: 专门为位置广播服务 → 使用_core后缀 ✓
|
||
```
|
||
|
||
## ⚠️ 常见检查错误
|
||
|
||
1. **只看文件夹名称，不检查内容**
|
||
2. **凭印象判断，不使用工具获取准确数据**
|
||
3. **遗漏单文件或双文件文件夹的识别**
|
||
4. **忽略测试文件夹扁平化**：认为tests文件夹是"标准结构"
|
||
5. **🚨 错误地要求修改 NestJS 框架文件命名**：
|
||
- ❌ 错误：要求将 `login.controller.ts` 改为 `login_controller.ts`（类型标识符不能用下划线）
|
||
- ❌ 错误：要求将 `userProfile.service.ts` 改为 `userProfile.service.ts`（文件名应该用 snake_case）
|
||
- ✅ 正确：`user_profile.service.ts`（文件名用 snake_case + 类型标识符用点分隔）
|
||
- **判断方法**：
|
||
- 检查类型标识符是否用点分隔（`.controller`、`.service` 等）
|
||
- 检查文件名本身是否用 snake_case
|
||
- 完整格式：`snake_case文件名.类型标识符.ts`
|
||
|
||
## 🔍 检查执行步骤
|
||
|
||
1. **使用listDirectory工具检查目标文件夹结构**
|
||
2. **逐个检查文件和文件夹命名是否符合规范**
|
||
3. **统计每个文件夹的文件数量**
|
||
4. **识别需要扁平化的文件夹（1-2个文件）**
|
||
5. **检查Core层模块命名是否正确**
|
||
6. **执行必要的文件移动和重命名操作**
|
||
7. **更新所有相关的import路径引用**
|
||
8. **验证修改后的结构和命名**
|
||
|
||
## 🔥 重要提醒
|
||
|
||
**如果在本步骤中执行了任何修改操作（文件重命名、移动、删除等），必须立即重新执行步骤1的完整检查！**
|
||
|
||
- ✅ 执行修改 → 🔥 立即重新执行步骤1 → 提供验证报告 → 等待用户确认
|
||
- ❌ 执行修改 → 直接进入步骤2（错误做法）
|
||
|
||
**🚨 重要强调：纯检查步骤不更新修改记录**
|
||
**如果检查发现命名已经符合规范，无需任何修改，则：**
|
||
- ❌ **禁止添加检查记录**：不要添加"AI代码检查步骤1：命名规范检查和优化"
|
||
- ❌ **禁止更新时间戳**：不要修改@lastModified字段
|
||
- ❌ **禁止递增版本号**：不要修改@version字段
|
||
- ✅ **仅提供检查报告**：说明检查结果，确认符合规范
|
||
|
||
**不能跳过重新检查环节！** |