Files

moyin 662694ba9f docs：优化命名规范中的扁平化标准说明

- 将扁平化标准从3个文件调整为1-2个文件
- 明确单文件必须扁平化，双文件建议扁平化
- 3个文件保持独立文件夹结构
- 更新相关检查步骤和常见错误说明

2026-01-15 10:58:01 +08:00

9.7 KiB

Raw Blame History

步骤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          # 错误！类型标识符应该用点分隔，不是下划线

关键规则：

文件名部分：使用 snake_case（如 user_profile、auth_core）
类型标识符：使用点分隔（如 .controller、.service）
完整格式：文件名.类型标识符.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）

命名规则说明：

文件名使用 snake_case：多个单词用下划线连接（如 user_profile、auth_core）
类型标识符使用点分隔：遵循 NestJS/Angular 风格（如 .controller、.service）
组合格式：snake_case文件名.类型标识符.ts
社区标准：这是本项目结合 NestJS 规范和 snake_case 约定的标准做法

普通文件和文件夹命名

规则：snake_case（下划线分隔），保持项目一致性
适用范围：非 NestJS 框架文件、工具类、配置文件、普通文件夹等

示例：

✅ 正确：user_utils.ts, admin_operation_log.ts, config_loader.ts
❌ 错误：UserUtils.ts, user-utils.ts, adminOperationLog.ts

变量和函数命名

规则：camelCase（小驼峰命名）

示例：

✅ 正确：const userName = 'test'; function getUserInfo() {}
❌ 错误：const UserName = 'test'; function GetUserInfo() {}

类和接口命名

规则：PascalCase（大驼峰命名）

示例：

✅ 正确：class UserService {} interface GameConfig {}
❌ 错误：class userService {} interface gameConfig {}

常量命名

规则：SCREAMING_SNAKE_CASE（全大写+下划线）

示例：

✅ 正确：const MAX_RETRY_COUNT = 3; const SALT_ROUNDS = 10;
❌ 错误：const maxRetryCount = 3; const saltRounds = 10;

路由命名

规则：kebab-case（短横线分隔）

示例：

✅ 正确：@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           # 性能测试

🏗️ 文件夹结构检查

检查方法（必须使用工具）

使用listDirectory工具：listDirectory(path, depth=2)获取完整结构
统计文件数量：逐个文件夹统计文件数量
识别单文件文件夹：只有1个文件的文件夹
执行扁平化：将文件移动到上级目录
更新引用路径：修改所有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后缀 ✓

⚠️ 常见检查错误

只看文件夹名称，不检查内容
凭印象判断，不使用工具获取准确数据
遗漏单文件或双文件文件夹的识别
忽略测试文件夹扁平化：认为tests文件夹是"标准结构"
🚨 错误地要求修改 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

🔍 检查执行步骤

使用listDirectory工具检查目标文件夹结构
逐个检查文件和文件夹命名是否符合规范
统计每个文件夹的文件数量
识别需要扁平化的文件夹（1-2个文件）
检查Core层模块命名是否正确
执行必要的文件移动和重命名操作
更新所有相关的import路径引用
验证修改后的结构和命名

🔥 重要提醒

如果在本步骤中执行了任何修改操作（文件重命名、移动、删除等），必须立即重新执行步骤1的完整检查！

✅ 执行修改 → 🔥 立即重新执行步骤1 → 提供验证报告 → 等待用户确认
❌ 执行修改 → 直接进入步骤2（错误做法）

🚨 重要强调：纯检查步骤不更新修改记录 如果检查发现命名已经符合规范，无需任何修改，则：

❌ 禁止添加检查记录：不要添加"AI代码检查步骤1：命名规范检查和优化"
❌ 禁止更新时间戳：不要修改@lastModified字段
❌ 禁止递增版本号：不要修改@version字段
✅ 仅提供检查报告：说明检查结果，确认符合规范

不能跳过重新检查环节！

9.7 KiB Raw Blame History Unescape Escape