wwjcloud/docs/NAMING-CONVENTIONS.md

🏷️ 命名规范指南

📋 概述

本文档为AI开发者提供完整的命名规范指南，确保NestJS项目与PHP项目在业务层面保持100%一致，同时遵循NestJS框架特性。

🎯 核心原则

1. 业务对齐优先: 业务逻辑命名与PHP项目保持一致
2. 框架规范遵循: NestJS特有文件类型按NestJS规范
3. 可读性保证: 确保命名清晰、语义明确
4. 数据库一致性: 与PHP项目共用数据库，命名必须完全一致

🏗️ 三大框架命名规范对比

1. PHP (ThinkPHP) 实际命名规范

基于 niucloud-php 项目的实际分析：

文件类型	命名规范	实际示例	说明
控制器	PascalCase.php	User.php, Order.php	无Controller后缀
模型	PascalCase.php	SysUser.php, MemberLevel.php	直接使用业务名称
验证器	PascalCase.php	User.php, Member.php	无Validate后缀
服务	PascalCase.php	UserService.php, OrderService.php	有Service后缀
目录	snake_case	adminapi/, validate/, model/	小写下划线

2. Java (Spring Boot) 标准命名规范

文件类型	命名规范	标准示例	说明
控制器	PascalCase + Controller.java	UserController.java	有Controller后缀
实体	PascalCase.java	User.java, Order.java	直接使用业务名称
服务	PascalCase + Service.java	UserService.java	有Service后缀
DTO	PascalCase + Dto.java	CreateUserDto.java	有Dto后缀
仓储	PascalCase + Repository.java	UserRepository.java	有Repository后缀

3. NestJS 框架标准命名规范

文件类型	命名规范	标准示例	说明
控制器	camelCase.controller.ts	userController.ts, userProfileController.ts	camelCase + 后缀
实体	camelCase.entity.ts	userEntity.ts, sysUser.entity.ts	camelCase + 后缀
服务	camelCase.service.ts	userService.ts, userProfileService.ts	camelCase + 后缀
DTO	camelCase.dto.ts	createUser.dto.ts, updateUser.dto.ts	camelCase + 后缀
模块	camelCase.module.ts	userModule.ts, adminModule.ts	camelCase + 后缀

重要说明：

• 文件名：使用 camelCase.suffix.ts 格式（项目统一规范）
• 类名：使用 PascalCase 格式（TypeScript 标准）
• 示例：文件 userController.ts 导出类 UserController

🎯 统一命名标准（最终规范）

文件命名规范（camelCase + 后缀）

实体文件命名

• 规范: {PHP模型名转camelCase}.entity.ts
• 对应关系: 与 PHP 模型文件一一对应，但使用 camelCase 命名
• 示例:
  • PHP SysUser.php → NestJS sysUser.entity.ts
  • PHP SysConfig.php → NestJS sysConfig.entity.ts
  • PHP MemberLevel.php → NestJS memberLevel.entity.ts

控制器文件命名

• 规范: {模块名}.controller.ts（使用 camelCase）
• 示例: userController.ts, orderController.ts, adminController.ts

服务文件命名

• 规范: {模块名}.service.ts（使用 camelCase）
• 示例: userService.ts, orderService.ts, adminService.ts

DTO文件命名

• 规范: {操作动词}{模块名}.dto.ts（使用 camelCase）
• 示例: createUser.dto.ts, updateUser.dto.ts, queryAdmin.dto.ts

验证器文件命名

• 规范: {模块名}.validator.ts (区别于PHP无后缀)
• 示例: user.validator.ts, member.validator.ts

模块文件命名

• 规范: {模块名}.module.ts (NestJS 标准)
• 示例: user.module.ts, admin.module.ts, auth.module.ts

类命名规范

实体类命名

• 规范: PascalCase (与PHP模型名保持一致)
• 示例: SysUser, SysConfig, MemberLevel

控制器类命名

• 规范: PascalCase + Controller
• 示例: UserController, AdminController, AuthController

服务类命名

• 规范: PascalCase + Service
• 示例: UserService, OrderService, AdminService

DTO类命名

• 规范: {操作动词}{模块名}Dto
• 示例: CreateUserDto, UpdateOrderDto, QueryMemberDto

方法命名规范

业务逻辑方法

优先与PHP项目保持一致，NestJS特有方法按NestJS规范

• CRUD方法: 与PHP项目方法名保持一致
• 查询方法: 与PHP项目方法名保持一致
• 业务方法: 与PHP项目方法名保持一致
• NestJS生命周期方法: 按NestJS规范，如 onModuleInit(), onApplicationBootstrap()

变量命名规范

业务变量优先与PHP项目保持一致，NestJS特有变量按NestJS规范

• 业务变量: 与PHP项目变量名保持一致
• 业务常量: 与PHP项目常量名保持一致
• NestJS注入变量: 按NestJS规范，如 private readonly userService: UserService
• TypeORM相关变量: 按TypeORM规范，如 @InjectRepository(User)

🗄️ 数据库命名规范

重要约束

与PHP项目共用数据库，必须保持命名100%一致

• 表名: 与PHP项目完全一致，包括前缀和命名方式
• 字段名: 与PHP项目完全一致，不能修改任何字段名
• 字段类型: 与PHP项目完全一致，不能修改字段类型
• 索引结构: 与PHP项目完全一致，不能添加或删除索引

实体映射规范

// 正确示例：与PHP模型SysUser.php对应
@Entity('sys_user') // 表名与PHP项目一致
export class SysUser {
  @PrimaryGeneratedColumn()
  id: number; // 字段名与PHP项目一致

  @Column({ name: 'username', length: 50 })
  username: string; // 字段名与PHP项目一致

  @Column({ name: 'created_at', type: 'timestamp' })
  createdAt: Date; // 字段名与PHP项目一致
}

📁 目录结构命名规范

标准模块目录结构

src/common/{模块名}/
├── {模块名}.module.ts    # 模块定义文件
├── controllers/          # 控制器目录
│   ├── adminapi/        # 管理端控制器目录（对应PHP adminapi/controller）
│   │   └── {模块名}.controller.ts
│   └── api/             # 前台控制器目录（对应PHP api/controller）
│       └── {模块名}.controller.ts
├── services/            # 服务目录
│   ├── admin/           # 管理端服务目录（对应PHP service/admin）
│   │   └── {模块名}.service.ts
│   ├── api/             # 前台服务目录（对应PHP service/api）
│   │   └── {模块名}.service.ts
│   └── core/            # 核心服务目录（对应PHP service/core）
│       └── {模块名}.service.ts
├── entity/              # 实体目录（对应PHP model）
│   ├── {实体名}.entity.ts      # 实体文件（camelCase.entity.ts 格式）
│   └── {配置实体}.entity.ts    # 配置实体文件
├── dto/                 # DTO 目录（对应PHP validate）
│   ├── admin/           # 管理端DTO目录
│   │   ├── create-{模块名}.dto.ts
│   │   └── update-{模块名}.dto.ts
│   └── api/             # 前台DTO目录
│       ├── {操作}-{模块}.dto.ts
│       └── {操作}-{模块}.dto.ts
├── guards/              # 守卫目录（可选）
├── decorators/          # 装饰器目录（可选）
├── interfaces/          # 接口目录（可选）
└── enums/               # 枚举目录（可选）

实际示例（基于auth模块）

src/common/auth/
├── auth.module.ts
├── controllers/
│   ├── adminapi/
│   │   └── auth.controller.ts        # 管理端控制器
│   └── api/
│       └── auth.controller.ts        # 前台控制器
├── services/
│   ├── admin/
│   │   └── auth.service.ts           # 管理端服务
│   ├── api/
│   │   └── auth.service.ts           # 前台服务
│   └── core/
│       └── auth.service.ts           # 核心服务
├── entity/
│   └── auth-token.entity.ts          # 实体文件
├── dto/
│   ├── admin/
│   │   ├── create-auth.dto.ts        # 管理端DTO
│   │   └── update-auth.dto.ts
│   └── api/
│       ├── login.dto.ts              # 前台DTO
│       └── register.dto.ts
├── guards/
│   ├── global-auth.guard.ts
│   ├── jwt-auth.guard.ts
│   └── roles.guard.ts
├── decorators/
│   ├── roles.decorator.ts
│   ├── public.decorator.ts
│   └── user-context.decorator.ts
└── interfaces/
    └── user.interface.ts

🚫 命名禁止规则

绝对禁止的命名行为

1. 🚫 禁止修改数据库相关命名

   • 不能修改表名、字段名、索引名
   • 不能修改字段类型和长度
   • 必须与PHP项目数据库结构100%一致

2. 🚫 禁止自创业务方法名

   • 业务方法名必须与PHP项目对应方法保持一致
   • 不能随意创造新的业务方法名

3. 🚫 禁止使用非标准缩写

   • 避免使用不明确的缩写，如 usr 代替 user
   • 避免使用中文拼音命名

4. 🚫 禁止混合命名风格

   • 同一项目内必须保持命名风格一致
   • 不能在同一文件中混用不同的命名规范

✅ 命名检查清单

开发前检查

• 已查看对应的PHP源码文件命名
• 已确认数据库表结构和字段命名
• 已理解业务逻辑和方法命名
• 已确认模块目录结构规范

开发中检查

• 实体类名与PHP模型名保持一致
• 数据库表名和字段名与PHP项目一致
• 业务方法名与PHP项目对应方法一致
• 文件命名符合NestJS规范

开发后检查

• 所有命名符合统一标准
• 没有使用禁止的命名方式
• 目录结构清晰规范
• 文档和注释命名准确

📚 相关文档

• AI智能体工作流程指南
• AI开发禁止规则
• 三框架原则对比
• 项目整体结构参考

---

重要提醒: 命名规范是代码质量的基础，所有AI开发者必须严格遵循此命名规范，确保项目的一致性和可维护性。