127a4db1e3
- 重构sys模块架构，严格按admin/api/core分层 - 对齐所有sys实体与数据库表结构 - 实现完整的adminapi控制器，匹配PHP/Java契约 - 修复依赖注入问题，确保服务正确注册 - 添加自动迁移工具和契约验证 - 完善多租户支持和审计功能 - 统一命名规范，与PHP业务逻辑保持一致
274 lines
10 KiB
Plaintext
274 lines
10 KiB
Plaintext
---
|
||
description:
|
||
globs:
|
||
alwaysApply: true
|
||
---
|
||
# 🏷️ 命名规范指南
|
||
|
||
## 📋 概述
|
||
|
||
本文档为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项目完全一致，不能添加或删除索引
|
||
|
||
### 实体映射规范
|
||
|
||
```typescript
|
||
// 正确示例：与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-WORKFLOW-GUIDE.md)
|
||
- [AI开发禁止规则](./AI-DEVELOPMENT-RULES.md)
|
||
- [三框架原则对比](./FRAMEWORK-PRINCIPLES.md)
|
||
- [项目整体结构参考](./PROJECT-STRUCTURE.md)
|
||
|
||
---
|
||
|
||
**重要提醒**: 命名规范是代码质量的基础，所有AI开发者必须严格遵循此命名规范，确保项目的一致性和可维护性。 |