127a4db1e3
- 重构sys模块架构，严格按admin/api/core分层 - 对齐所有sys实体与数据库表结构 - 实现完整的adminapi控制器，匹配PHP/Java契约 - 修复依赖注入问题，确保服务正确注册 - 添加自动迁移工具和契约验证 - 完善多租户支持和审计功能 - 统一命名规范，与PHP业务逻辑保持一致
278 lines
11 KiB
Markdown
278 lines
11 KiB
Markdown
# AI 框架功能对比图 - NestJS vs ThinkPHP
|
||
|
||
## 📋 概述
|
||
|
||
本文档为 AI 开发者提供 NestJS 和 ThinkPHP 框架的详细对比，包含功能映射、开发规范、命名约定和目录结构对比，确保 AI 能够更好地理解和开发功能。
|
||
|
||
**重要原则：既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致**
|
||
|
||
## 🔄 核心功能映射
|
||
|
||
### 1. 基础架构对比
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|----------|----------|
|
||
| **路由系统** | `Route::get()` | `@Get()` | ✅ 直接对应 | 装饰器路由 |
|
||
| **控制器** | `Controller` | `@Controller()` | ✅ 直接对应 | 装饰器控制器 |
|
||
| **中间件** | `Middleware` | `@UseGuards()` | ✅ 功能对应 | 守卫/拦截器 |
|
||
| **依赖注入** | `Container::get()` | `constructor()` | ✅ 更强大 | 自动注入 |
|
||
| **数据验证** | `Validate` | `@UsePipes()` | ✅ 功能对应 | 验证管道 |
|
||
| **异常处理** | `Exception` | `@UseFilters()` | ✅ 功能对应 | 异常过滤器 |
|
||
|
||
### 2. 数据库操作对比
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|----------|----------|
|
||
| **模型定义** | `Model` | `@Entity()` | ✅ 功能对应 | TypeORM 实体 |
|
||
| **查询构建** | `Db::table()` | `Repository` | ✅ 功能对应 | TypeORM 仓库 |
|
||
| **关联关系** | `hasMany()` | `@OneToMany()` | ✅ 功能对应 | TypeORM 关联 |
|
||
| **事务处理** | `Db::startTrans()` | `@Transaction()` | ✅ 功能对应 | TypeORM 事务 |
|
||
| **软删除** | `SoftDelete` | `@DeleteDateColumn()` | ✅ 功能对应 | TypeORM 软删除 |
|
||
|
||
### 3. 缓存和会话
|
||
|
||
| 功能模块 | ThinkPHP | NestJS | 对应关系 | 实现方式 |
|
||
|---------|----------|---------|----------|----------|
|
||
| **缓存管理** | `Cache::get()` | `@Inject(CACHE_MANAGER)` | ✅ 功能对应 | Cache Manager |
|
||
| **会话管理** | `Session` | `@Session()` | ✅ 功能对应 | Session 装饰器 |
|
||
| **Redis 集成** | `Redis::get()` | `@InjectRedis()` | ✅ 功能对应 | Redis 模块 |
|
||
|
||
## 🏗️ 目录结构对比
|
||
|
||
### ThinkPHP 目录结构
|
||
```
|
||
thinkphp/
|
||
├── app/ # 应用目录
|
||
│ ├── controller/ # 控制器
|
||
│ ├── model/ # 模型
|
||
│ ├── service/ # 服务层
|
||
│ └── middleware/ # 中间件
|
||
├── config/ # 配置文件
|
||
├── public/ # 公共资源
|
||
├── route/ # 路由定义
|
||
└── vendor/ # 第三方包
|
||
```
|
||
|
||
### NestJS 目录结构
|
||
```
|
||
wwjcloud/
|
||
├── src/ # 源代码目录
|
||
│ ├── common/ # 通用服务层 (对应 ThinkPHP app/)
|
||
│ │ ├── admin/ # 管理端服务
|
||
│ │ ├── member/ # 会员服务
|
||
│ │ ├── rbac/ # 权限管理
|
||
│ │ └── settings/ # 系统设置
|
||
│ ├── config/ # 配置管理层 (对应 ThinkPHP config/)
|
||
│ │ ├── entity/ # 实体配置
|
||
│ │ ├── database/ # 数据库配置
|
||
│ │ └── env/ # 环境配置
|
||
│ ├── core/ # 核心基础设施层 (对应 ThinkPHP 核心)
|
||
│ │ ├── base/ # 基础类
|
||
│ │ ├── traits/ # 特性类
|
||
│ │ ├── database/ # 数据库核心
|
||
│ │ └── security/ # 安全核心
|
||
│ └── vendor/ # 第三方服务适配层 (对应 ThinkPHP vendor/)
|
||
│ ├── payment/ # 支付适配器
|
||
│ ├── storage/ # 存储适配器
|
||
│ └── sms/ # 短信适配器
|
||
├── public/ # 公共资源
|
||
└── package.json # 依赖管理
|
||
```
|
||
|
||
### 层级对应关系
|
||
|
||
| 层级 | ThinkPHP | NestJS | 说明 |
|
||
|------|----------|---------|------|
|
||
| **应用层** | `app/` | `src/common/` | 业务逻辑和通用服务 |
|
||
| **配置层** | `config/` | `src/config/` | 配置管理和环境变量 |
|
||
| **核心层** | 框架核心 | `src/core/` | 基础设施和核心功能 |
|
||
| **适配层** | `vendor/` | `src/vendor/` | 第三方服务集成 |
|
||
|
||
## 📝 命名规范和约束
|
||
|
||
### 1. 数据库命名规范
|
||
|
||
**重要约束：与 PHP 项目共用数据库，必须保持命名一致**
|
||
|
||
- **表名**: 与 PHP 项目完全一致，包括前缀和命名方式
|
||
- **字段名**: 与 PHP 项目完全一致，不能修改任何字段名
|
||
- **字段类型**: 与 PHP 项目完全一致，不能修改字段类型
|
||
- **索引结构**: 与 PHP 项目完全一致，不能添加或删除索引
|
||
|
||
**原则：看到 PHP 项目怎么命名，我们就怎么命名，保持 100% 一致**
|
||
|
||
### 2. 代码命名规范
|
||
|
||
#### 类名规范
|
||
- **实体类**: 使用 PascalCase，如 `User`, `OrderDetail`
|
||
- **服务类**: 使用 PascalCase + Service，如 `UserService`, `OrderService`
|
||
- **控制器**: 使用 PascalCase + Controller，如 `UserController`
|
||
- **DTO 类**: 使用 PascalCase + Dto，如 `CreateUserDto`, `UpdateUserDto`
|
||
|
||
#### 方法名规范
|
||
**业务逻辑方法优先与 PHP 项目保持一致，NestJS 特有方法按 NestJS 规范：**
|
||
|
||
- **CRUD 方法**: 与 PHP 项目方法名保持一致
|
||
- **查询方法**: 与 PHP 项目方法名保持一致
|
||
- **业务方法**: 与 PHP 项目方法名保持一致
|
||
- **NestJS 生命周期方法**: 按 NestJS 规范，如 `onModuleInit()`, `onApplicationBootstrap()`
|
||
|
||
**原则：业务逻辑与 PHP 保持一致，NestJS 特性按 NestJS 规范**
|
||
|
||
#### 变量名规范
|
||
**业务变量优先与 PHP 项目保持一致，NestJS 特有变量按 NestJS 规范：**
|
||
|
||
- **业务变量**: 与 PHP 项目变量名保持一致
|
||
- **业务常量**: 与 PHP 项目常量名保持一致
|
||
- **NestJS 注入变量**: 按 NestJS 规范，如 `private readonly userService: UserService`
|
||
- **TypeORM 相关变量**: 按 TypeORM 规范，如 `@InjectRepository(User)`
|
||
|
||
**原则：业务变量与 PHP 保持一致，NestJS 特性按 NestJS 规范**
|
||
|
||
### 3. 文件命名规范
|
||
|
||
#### 目录结构
|
||
```
|
||
src/common/admin/
|
||
├── controllers/ # 控制器目录
|
||
│ ├── user.controller.ts
|
||
│ └── order.controller.ts
|
||
├── services/ # 服务目录
|
||
│ ├── user.service.ts
|
||
│ └── order.service.ts
|
||
├── entities/ # 实体目录
|
||
│ ├── user.entity.ts
|
||
│ └── order.entity.ts
|
||
└── dto/ # DTO 目录
|
||
├── create-user.dto.ts
|
||
└── update-user.dto.ts
|
||
```
|
||
|
||
#### 文件命名
|
||
**NestJS 特有的文件类型，按照 NestJS 规范命名：**
|
||
|
||
- **控制器**: `{模块名}.controller.ts` (NestJS 规范)
|
||
- **服务**: `{模块名}.service.ts` (NestJS 规范)
|
||
- **实体**: `{模块名}.entity.ts` (TypeORM 规范，对应 PHP 的模型)
|
||
- **DTO**: `{操作}-{模块名}.dto.ts` (NestJS 规范，对应 PHP 的验证器)
|
||
- **模块**: `{模块名}.module.ts` (NestJS 规范)
|
||
|
||
**原则：NestJS 特有的文件类型按 NestJS 规范，业务逻辑与 PHP 保持一致**
|
||
|
||
## 🔧 开发约束和规范
|
||
|
||
### 1. 数据库约束
|
||
|
||
#### 必须遵守的规则
|
||
- **表结构**: 与 PHP 项目完全一致，不能修改任何结构
|
||
- **索引**: 与 PHP 项目完全一致，不能修改索引
|
||
- **外键**: 与 PHP 项目完全一致，不能修改外键
|
||
- **触发器**: 与 PHP 项目完全一致，不能修改触发器
|
||
|
||
#### 数据一致性
|
||
- **事务处理**: 与 PHP 项目保持一致的事务处理方式
|
||
- **软删除**: 与 PHP 项目保持一致的软删除方式
|
||
- **状态管理**: 与 PHP 项目保持一致的状态管理方式
|
||
|
||
**原则：PHP 项目怎么做，我们就怎么做，保持 100% 一致**
|
||
|
||
### 2. API 设计约束
|
||
|
||
#### 接口规范
|
||
- **URL 格式**: 与 PHP 项目完全一致
|
||
- **请求方法**: 与 PHP 项目完全一致
|
||
- **响应格式**: 与 PHP 项目完全一致
|
||
- **错误处理**: 与 PHP 项目完全一致
|
||
|
||
**原则：PHP 项目怎么设计接口，我们就怎么设计，保持 100% 一致**
|
||
|
||
#### 权限控制
|
||
- **认证**: 与 PHP 项目保持一致的认证方式
|
||
- **授权**: 与 PHP 项目保持一致的授权方式
|
||
- **数据隔离**: 与 PHP 项目保持一致的数据隔离方式
|
||
|
||
**原则：PHP 项目怎么控制权限，我们就怎么控制，保持 100% 一致**
|
||
|
||
### 3. 代码质量约束
|
||
|
||
#### 类型安全
|
||
- **必须使用 TypeScript**: 不允许使用 `any` 类型
|
||
- **接口定义**: 所有 DTO 和响应对象必须有接口定义
|
||
- **类型检查**: 启用严格模式，不允许隐式类型转换
|
||
|
||
#### 错误处理
|
||
- **异常捕获**: 与 PHP 项目保持一致的异常处理方式
|
||
- **日志记录**: 与 PHP 项目保持一致的日志记录方式
|
||
- **错误响应**: 与 PHP 项目保持一致的错误响应格式
|
||
|
||
**原则：PHP 项目怎么处理错误，我们就怎么处理，保持 100% 一致**
|
||
|
||
## 🚀 AI 开发指南
|
||
|
||
### 1. 开发流程
|
||
|
||
#### 创建新功能模块
|
||
1. **分析需求**: 确定功能属于哪个层级 (common/config/core/vendor)
|
||
2. **参考 PHP 项目**: 查看 PHP 项目如何实现相同功能
|
||
3. **保持一致性**: 与 PHP 项目保持 100% 一致
|
||
4. **创建组件**: 按照 NestJS 规范创建相应的组件
|
||
5. **配置模块**: 在相应的模块中注册组件
|
||
|
||
#### 开发原则
|
||
**既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致**
|
||
|
||
- **框架特性**: 按照 NestJS 规范使用装饰器、依赖注入、管道等特性
|
||
- **业务逻辑**: 与 PHP 项目保持 100% 一致
|
||
- **数据操作**: 与 PHP 项目保持 100% 一致
|
||
- **接口设计**: 与 PHP 项目保持 100% 一致
|
||
|
||
### 2. 常见问题解决
|
||
|
||
#### 常见问题解决原则
|
||
**遇到问题时，首先查看 PHP 项目是如何解决的，然后按照相同方式解决**
|
||
|
||
- **数据库问题**: 参考 PHP 项目的数据库配置和操作方式
|
||
- **权限问题**: 参考 PHP 项目的权限控制方式
|
||
- **性能问题**: 参考 PHP 项目的性能优化方式
|
||
- **业务问题**: 参考 PHP 项目的业务实现方式
|
||
|
||
**原则：PHP 项目怎么解决，我们就怎么解决，保持 100% 一致**
|
||
|
||
### 3. 最佳实践
|
||
|
||
#### 最佳实践原则
|
||
**参考 PHP 项目的最佳实践，保持 100% 一致**
|
||
|
||
- **代码组织**: 与 PHP 项目保持一致的代码组织方式
|
||
- **错误处理**: 与 PHP 项目保持一致的错误处理方式
|
||
- **测试策略**: 与 PHP 项目保持一致的测试策略
|
||
|
||
**原则：PHP 项目怎么组织代码，我们就怎么组织，保持 100% 一致**
|
||
|
||
## 📚 参考资源
|
||
|
||
### 官方文档
|
||
- **NestJS**: https://nest.nodejs.cn/
|
||
- **TypeORM**: https://typeorm.io/
|
||
- **ThinkPHP**: https://doc.thinkphp.cn/
|
||
|
||
### 项目相关
|
||
- **数据库结构**: 参考 PHP 项目的数据库设计
|
||
- **API 接口**: 参考 PHP 项目的接口文档
|
||
- **业务逻辑**: 参考 PHP 项目的业务实现
|
||
|
||
## 🎯 总结
|
||
|
||
### 平衡原则
|
||
1. **尊重 NestJS**: 充分利用 NestJS 的装饰器、依赖注入、管道等特性
|
||
2. **保持业务一致**: 业务逻辑、数据操作、接口设计与 PHP 项目 100% 一致
|
||
3. **框架适配**: 用 NestJS 的方式实现 PHP 项目的功能
|
||
|
||
### 开发策略
|
||
- **看到 PHP 项目怎么做的，我们就怎么做** (业务层面)
|
||
- **看到 NestJS 怎么做的，我们就怎么做** (框架层面)
|
||
- **两者结合，发挥各自优势**
|
||
|
||
---
|
||
|
||
**注意**: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。 |