127a4db1e3
- 重构sys模块架构，严格按admin/api/core分层 - 对齐所有sys实体与数据库表结构 - 实现完整的adminapi控制器，匹配PHP/Java契约 - 修复依赖注入问题，确保服务正确注册 - 添加自动迁移工具和契约验证 - 完善多租户支持和审计功能 - 统一命名规范，与PHP业务逻辑保持一致
352 lines
15 KiB
Markdown
352 lines
15 KiB
Markdown
# 🏗️ 三大框架原则对比与统一标准
|
||
|
||
## 📋 概述
|
||
|
||
本文档为AI开发者提供NestJS、ThinkPHP、Spring Boot三大框架的详细对比，包含功能映射、开发规范、命名约定和目录结构对比，确保AI能够更好地理解和开发功能。
|
||
|
||
**重要原则：既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致**
|
||
|
||
## 🔄 核心功能映射
|
||
|
||
### 1. 基础架构对比
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|-------------|----------|----------|
|
||
| **路由系统** | `Route::get()` | `@Get()` | `@GetMapping()` | ✅ 直接对应 | 装饰器路由 |
|
||
| **控制器** | `Controller` | `@Controller()` | `@RestController` | ✅ 直接对应 | 装饰器控制器 |
|
||
| **中间件** | `Middleware` | `@UseGuards()` | `@Component` | ✅ 功能对应 | 守卫/拦截器 |
|
||
| **依赖注入** | `Container::get()` | `constructor()` | `@Autowired` | ✅ 更强大 | 自动注入 |
|
||
| **数据验证** | `Validate` | `@UsePipes()` | `@Valid` | ✅ 功能对应 | 验证管道 |
|
||
| **异常处理** | `Exception` | `@UseFilters()` | `@ExceptionHandler` | ✅ 功能对应 | 异常过滤器 |
|
||
|
||
### 2. 数据库操作对比
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|-------------|----------|----------|
|
||
| **模型定义** | `Model` | `@Entity()` | `@Entity` | ✅ 功能对应 | TypeORM/JPA 实体 |
|
||
| **查询构建** | `Db::table()` | `Repository` | `JpaRepository` | ✅ 功能对应 | TypeORM/JPA 仓库 |
|
||
| **关联关系** | `hasMany()` | `@OneToMany()` | `@OneToMany` | ✅ 功能对应 | ORM 关联 |
|
||
| **事务处理** | `Db::startTrans()` | `@Transaction()` | `@Transactional` | ✅ 功能对应 | 声明式事务 |
|
||
| **软删除** | `SoftDelete` | `@DeleteDateColumn()` | `@SQLDelete` | ✅ 功能对应 | ORM 软删除 |
|
||
|
||
### 3. 缓存和会话
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | Spring Boot | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|-------------|----------|----------|
|
||
| **缓存管理** | `Cache::get()` | `@Inject(CACHE_MANAGER)` | `@Cacheable` | ✅ 功能对应 | Cache Manager |
|
||
| **会话管理** | `Session` | `@Session()` | `HttpSession` | ✅ 功能对应 | Session 装饰器 |
|
||
| **Redis 集成** | `Redis::get()` | `@InjectRedis()` | `@Autowired RedisTemplate` | ✅ 功能对应 | Redis 模块 |
|
||
|
||
## 🏗️ 目录结构对比
|
||
|
||
### ThinkPHP 目录结构
|
||
```
|
||
thinkphp/
|
||
├── app/ # 应用目录
|
||
│ ├── controller/ # 控制器
|
||
│ ├── model/ # 模型
|
||
│ ├── service/ # 服务层
|
||
│ └── middleware/ # 中间件
|
||
├── config/ # 配置文件
|
||
├── public/ # 公共资源
|
||
├── route/ # 路由定义
|
||
└── vendor/ # 第三方包
|
||
```
|
||
|
||
### Spring Boot 目录结构
|
||
```
|
||
spring-boot/
|
||
├── src/main/java/
|
||
│ ├── controller/ # 控制器层
|
||
│ ├── service/ # 服务层
|
||
│ ├── repository/ # 数据访问层
|
||
│ ├── entity/ # 实体层
|
||
│ ├── dto/ # 数据传输对象
|
||
│ └── config/ # 配置类
|
||
├── src/main/resources/
|
||
│ ├── application.yml # 配置文件
|
||
│ └── static/ # 静态资源
|
||
└── pom.xml # 依赖管理
|
||
```
|
||
|
||
### NestJS 目录结构
|
||
```
|
||
wwjcloud/
|
||
├── src/ # 源代码目录
|
||
│ ├── common/ # 通用服务层 (对应 ThinkPHP app/)
|
||
│ │ ├── auth/ # 认证授权模块
|
||
│ │ ├── member/ # 会员管理模块
|
||
│ │ ├── sys/ # 系统管理模块
|
||
│ │ ├── site/ # 站点管理模块
|
||
│ │ ├── addon/ # 插件管理模块
|
||
│ │ ├── upload/ # 文件上传模块
|
||
│ │ └── ... # 其他业务模块
|
||
│ ├── config/ # 配置管理层 (对应 ThinkPHP config/)
|
||
│ │ ├── database/ # 数据库配置
|
||
│ │ ├── redis/ # Redis配置
|
||
│ │ ├── jwt/ # JWT配置
|
||
│ │ └── app/ # 应用配置
|
||
│ ├── core/ # 核心基础设施层 (对应 ThinkPHP 核心)
|
||
│ │ ├── base/ # 基础类
|
||
│ │ ├── database/ # 数据库核心
|
||
│ │ ├── security/ # 安全核心
|
||
│ │ └── interceptors/ # 拦截器
|
||
│ └── vendor/ # 第三方服务适配层 (对应 ThinkPHP vendor/)
|
||
│ ├── payment/ # 支付适配器
|
||
│ ├── storage/ # 存储适配器
|
||
│ └── sms/ # 短信适配器
|
||
├── public/ # 公共资源
|
||
└── package.json # 依赖管理
|
||
```
|
||
|
||
### 层级对应关系
|
||
|
||
| 层级 | ThinkPHP | Spring Boot | NestJS | 说明 |
|
||
|------|----------|-------------|---------|------|
|
||
| **应用层** | `app/` | `src/main/java/` | `src/common/` | 业务逻辑和通用服务 |
|
||
| **配置层** | `config/` | `src/main/resources/` | `src/config/` | 配置管理和环境变量 |
|
||
| **核心层** | 框架核心 | Spring框架 | `src/core/` | 基础设施和核心功能 |
|
||
| **适配层** | `vendor/` | 第三方依赖 | `src/vendor/` | 第三方服务集成 |
|
||
|
||
## 📝 命名规范对比
|
||
|
||
### 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`, `OrderController.java` | 有Controller后缀 |
|
||
| **实体** | `PascalCase.java` | `User.java`, `Order.java` | 直接使用业务名称 |
|
||
| **服务** | `PascalCase + Service.java` | `UserService.java`, `OrderService.java` | 有Service后缀 |
|
||
| **DTO** | `PascalCase + Dto.java` | `CreateUserDto.java`, `UserResponseDto.java` | 有Dto后缀 |
|
||
| **仓储** | `PascalCase + Repository.java` | `UserRepository.java` | 有Repository后缀 |
|
||
| **目录** | `camelCase` | `controller/`, `service/`, `dto/` | 驼峰命名 |
|
||
|
||
### 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` | `controllers/`, `services/`, `dto/` | camelCase 目录 |
|
||
|
||
**重要说明**：
|
||
- **文件名**：使用 `camelCase.suffix.ts` 格式（本项目统一规范）
|
||
- **类名**：使用 `PascalCase` 格式（TypeScript标准）
|
||
- **示例**：文件 `user.controller.ts` 导出类 `UserController`
|
||
|
||
## 🎯 统一命名标准（最终规范）
|
||
|
||
### 核心原则
|
||
1. **业务对齐优先**: 业务逻辑命名与PHP项目保持一致
|
||
2. **框架规范遵循**: NestJS特有文件类型按NestJS规范
|
||
3. **可读性保证**: 确保命名清晰、语义明确
|
||
|
||
### 文件命名规范（最终版）
|
||
|
||
#### 实体文件命名
|
||
- **规范**: `{PHP模型名首字母小写}.entity.ts`
|
||
- **对应关系**: 与PHP模型文件一一对应，但使用PascalCase命名
|
||
- **示例**:
|
||
- PHP `SysUser.php` → NestJS `SysUser.entity.ts`
|
||
- PHP `SysConfig.php` → NestJS `SysConfig.entity.ts`
|
||
- PHP `MemberLevel.php` → NestJS `MemberLevel.entity.ts`
|
||
|
||
#### 控制器文件命名
|
||
- **规范**: `{模块名}.controller.ts` (NestJS 标准，使用PascalCase)
|
||
- **示例**: `User.controller.ts`, `Order.controller.ts`, `Admin.controller.ts`
|
||
|
||
#### 服务文件命名
|
||
- **规范**: `{模块名}.service.ts` (NestJS 标准，使用PascalCase)
|
||
- **示例**: `User.service.ts`, `Order.service.ts`, `Admin.service.ts`
|
||
|
||
#### DTO文件命名
|
||
- **规范**: `{操作动词}{模块名}Dto.ts` (项目实际使用格式)
|
||
- **示例**: `CreateUserDto.ts`, `UpdateUserDto.ts`, `QueryAdminDto.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类命名
|
||
- **规范**: `PascalCase + Dto`
|
||
- **示例**: `CreateUserDto`, `UpdateUserDto`, `QueryAdminDto`
|
||
|
||
### 方法命名规范（最终版）
|
||
|
||
#### 业务逻辑方法
|
||
**优先与 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 项目共用数据库，必须保持命名一致
|
||
|
||
- **表名**: 与 PHP 项目完全一致，包括前缀和命名方式
|
||
- **字段名**: 与 PHP 项目完全一致，不能修改任何字段名
|
||
- **字段类型**: 与 PHP 项目完全一致，不能修改字段类型
|
||
- **索引结构**: 与 PHP 项目完全一致，不能添加或删除索引
|
||
|
||
**原则：看到 PHP 项目怎么命名，我们就怎么命名，保持 100% 一致**
|
||
|
||
## 🏗️ 模块目录结构规范
|
||
|
||
### 标准模块目录结构
|
||
```
|
||
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 # 实体文件（PascalCase.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/
|
||
│ └── AuthToken.entity.ts
|
||
├── dto/
|
||
│ ├── admin/ # 管理端DTO目录
|
||
│ │ ├── CreateAuthDto.ts
|
||
│ │ └── UpdateAuthDto.ts
|
||
│ └── api/ # 前台DTO目录
|
||
│ ├── LoginDto.ts
|
||
│ └── RegisterDto.ts
|
||
├── guards/
|
||
│ ├── GlobalAuthGuard.ts
|
||
│ ├── JwtAuthGuard.ts
|
||
│ └── RolesGuard.ts
|
||
├── decorators/
|
||
│ ├── RolesDecorator.ts
|
||
│ ├── public.decorator.ts
|
||
│ └── user-context.decorator.ts
|
||
└── interfaces/
|
||
└── user.interface.ts
|
||
```
|
||
|
||
## 🔄 模块间通信规范
|
||
|
||
### 模块依赖管理
|
||
|
||
## 🎯 框架特性对比
|
||
|
||
### 依赖注入对比
|
||
|
||
| 框架 | 实现方式 | 示例 |
|
||
|------|----------|------|
|
||
| **ThinkPHP** | 容器获取 | `Container::get('UserService')` |
|
||
| **Spring Boot** | 注解注入 | `@Autowired private UserService userService;` |
|
||
| **NestJS** | 构造函数注入 | `constructor(private userService: UserService) {}` |
|
||
|
||
### 装饰器对比
|
||
|
||
| 功能 | ThinkPHP | Spring Boot | NestJS |
|
||
|------|----------|-------------|---------|
|
||
| **路由** | `Route::get()` | `@GetMapping()` | `@Get()` |
|
||
| **验证** | `validate()` | `@Valid` | `@UsePipes()` |
|
||
| **事务** | `Db::startTrans()` | `@Transactional` | `@Transaction()` |
|
||
| **缓存** | `Cache::remember()` | `@Cacheable` | `@UseInterceptors()` |
|
||
|
||
## 📚 最佳实践
|
||
|
||
### 1. 业务逻辑迁移原则
|
||
- 严格按照PHP项目的业务逻辑实现
|
||
- 保持API接口的输入输出格式一致
|
||
- 维护相同的数据验证规则
|
||
- 确保错误处理机制一致
|
||
|
||
### 2. 框架特性使用原则
|
||
- 充分利用NestJS的依赖注入特性
|
||
- 使用装饰器简化代码编写
|
||
- 采用模块化设计提高代码可维护性
|
||
- 利用TypeScript的类型系统提高代码质量
|
||
|
||
### 3. 性能优化原则
|
||
- 合理使用缓存机制
|
||
- 优化数据库查询
|
||
- 实现异步处理
|
||
- 采用批量操作减少数据库访问
|
||
|
||
---
|
||
|
||
**重要提醒**: 本文档是三框架对比的权威指南，AI开发者必须严格遵循这些原则，确保代码质量和规范一致性。 |