1cd5d3bdef
主要更新： 1. 后端核心底座完成 (M1-M6)： - 健康检查、指标监控、分布式锁 - 事件总线、队列系统、事务管理 - 安全守卫、多租户隔离、存储适配器 - 审计日志、配置管理、多语言支持 2. 前端迁移到 Ant Design Vue： - 从 Element Plus 迁移到 Ant Design Vue - 完善 system 模块 (role/menu/dept) - 修复依赖和配置问题 3. 文档完善： - AI 开发工作流文档 - 架构约束和开发规范 - 项目进度跟踪 4. 其他改进： - 修复编译错误和类型问题 - 完善测试用例 - 优化项目结构
314 lines
13 KiB
Markdown
314 lines
13 KiB
Markdown
框架层面: 100% 使用 NestJS 的方式
|
||
业务层面: 与 PHP 项目保持 100% 一致
|
||
数据层面: 与 PHP 项目数据库结构 100% 一致
|
||
# 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 怎么做的，我们就怎么做** (框架层面)
|
||
- **两者结合，发挥各自优势**
|
||
|
||
---
|
||
时间戳 → 使用 TypeORM 的 @CreateDateColumn, @UpdateDateColumn，但指定 type: 'int'
|
||
软删除 → 使用 @Column 手动定义 is_del 和 delete_time，都是 number 类型
|
||
JSON 字段 → 使用 @Column('json')
|
||
状态管理 → 使用 NestJS 的 ValidationPipe
|
||
**注意**: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。
|
||
开发步骤和注意事项
|
||
开发检查清单
|
||
✅ 开发前检查
|
||
[ ] 查看PHP模型字段定义
|
||
[ ] 检查数据库表结构
|
||
[ ] 确认字段类型和约束
|
||
[ ] 了解业务逻辑关系
|
||
✅ 开发中检查
|
||
[ ] 字段名与数据库一致
|
||
[ ] 时间戳使用int类型
|
||
[ ] 软删除使用is_del字段
|
||
[ ] 关联关系正确定义
|
||
[ ] 查询语法使用TypeORM操作符
|
||
✅ 开发后检查
|
||
[ ] npm run build 无错误
|
||
[ ] 与PHP项目字段名100%一致，并列出php的model层，数据库，nestjs字段名清单。
|
||
[ ] 业务逻辑与PHP保持一致，并列出，php与nestjs的，命名规范对比清单
|
||
[ ] 类型安全无警告
|
||
🚀 简化处理步骤
|
||
三步快速修复法
|
||
看PHP → 找到对应字段名和类型
|
||
查数据库 → 确认实际字段结构
|
||
写NestJS → 使用框架特性实现相同逻辑
|
||
优先级处理顺序
|
||
高优先级：字段名不匹配（直接复用PHP）
|
||
中优先级：类型不匹配（遵守NestJS规范）
|
||
低优先级：语法优化（保持代码整洁）
|
||
一句话总结
|
||
"
|
||
用NestJS的语法，写PHP的逻辑，保持数据库的一致性" |