wwjcloud/docs/FRAMEWORK-PRINCIPLES.md

# 🏗️ 三大框架原则对比与统一标准

## 📋 概述

本文档为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 框架标准命名规范

| 文件类型 | 命名规范 | 标准示例 | 说明 |
|---------|----------|----------|------|
| **控制器** | `camelCaseController.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标准）
- **示例**：文件 `userController.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 标准，使用camelCase)
- **示例**: `userController.ts`, `orderController.ts`, `adminController.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/        # 管理端控制器目录
│   │   └── authController.ts
│   └── api/             # 前台控制器目录
│       └── authController.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开发者必须严格遵循这些原则，确保代码质量和规范一致性。