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开发者必须严格遵循这些原则，确保代码质量和规范一致性。