Files

万物街 127a4db1e3 feat: 完成sys模块迁移，对齐PHP/Java框架

- 重构sys模块架构，严格按admin/api/core分层
- 对齐所有sys实体与数据库表结构
- 实现完整的adminapi控制器，匹配PHP/Java契约
- 修复依赖注入问题，确保服务正确注册
- 添加自动迁移工具和契约验证
- 完善多租户支持和审计功能
- 统一命名规范，与PHP业务逻辑保持一致

2025-09-21 21:29:28 +08:00

11 KiB

Raw Blame History

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. 开发流程

创建新功能模块

分析需求: 确定功能属于哪个层级 (common/config/core/vendor)
参考 PHP 项目: 查看 PHP 项目如何实现相同功能
保持一致性: 与 PHP 项目保持 100% 一致
创建组件: 按照 NestJS 规范创建相应的组件
配置模块: 在相应的模块中注册组件

开发原则

既要尊重 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% 一致

📚 参考资源

官方文档

项目相关

数据库结构: 参考 PHP 项目的数据库设计
API 接口: 参考 PHP 项目的接口文档
业务逻辑: 参考 PHP 项目的业务实现

🎯 总结

平衡原则

尊重 NestJS: 充分利用 NestJS 的装饰器、依赖注入、管道等特性
保持业务一致: 业务逻辑、数据操作、接口设计与 PHP 项目 100% 一致
框架适配: 用 NestJS 的方式实现 PHP 项目的功能

开发策略

看到 PHP 项目怎么做的，我们就怎么做 (业务层面)
看到 NestJS 怎么做的，我们就怎么做 (框架层面)
两者结合，发挥各自优势

注意: 本文档是 AI 开发的重要参考，请严格按照平衡原则进行开发，既要尊重 NestJS 框架特性，又要与 PHP 项目业务逻辑保持一致。

11 KiB Raw Blame History Unescape Escape