docs:完善 NestJS 框架文件命名规范说明

- 详细说明 NestJS 文件命名规则(snake_case + 点分隔类型标识符)
- 添加正确和错误的命名示例对比
- 补充所有 NestJS 文件类型标识符列表
- 增加常见错误判断方法说明
This commit is contained in:
moyin
2026-01-14 13:17:23 +08:00
parent 8bcd22ea50
commit 41c33d6159

View File

@@ -22,11 +22,63 @@
## 📋 命名规范标准 ## 📋 命名规范标准
### 文件和文件夹命名 ### 文件和文件夹命名
#### 🚨 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下划线分隔保持项目一致性 - **规则**snake_case下划线分隔保持项目一致性
- **适用范围**:非 NestJS 框架文件、工具类、配置文件、普通文件夹等
- **示例** - **示例**
``` ```
✅ 正确user_controller.ts, admin_operation_log_service.ts ✅ 正确user_utils.ts, admin_operation_log.ts, config_loader.ts
❌ 错误UserController.ts, user-service.ts, adminOperationLog.service.ts ❌ 错误UserUtils.ts, user-utils.ts, adminOperationLog.ts
``` ```
### 变量和函数命名 ### 变量和函数命名
@@ -161,6 +213,14 @@ src/business/auth/
2. **凭印象判断,不使用工具获取准确数据** 2. **凭印象判断,不使用工具获取准确数据**
3. **遗漏≤3个文件文件夹的识别** 3. **遗漏≤3个文件文件夹的识别**
4. **忽略测试文件夹扁平化**认为tests文件夹是"标准结构" 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`
## 🔍 检查执行步骤 ## 🔍 检查执行步骤