270 lines
12 KiB
Markdown
270 lines
12 KiB
Markdown
# 4.5 目录结构设计
|
||
|
||
:::tip 概述
|
||
目录结构遵循"按职责分层、按模块分组"的原则。后端以 `app/` 为核心，按 Controller → Logic → Model → Validate 四层组织；前端以 `src/` 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
|
||
:::
|
||
|
||
## 后端整体结构
|
||
|
||
```text
|
||
项目根目录/
|
||
├── app/ ← 应用代码（核心）
|
||
├── config/ ← 配置文件
|
||
├── extend/ ← 扩展类库（非 Composer）
|
||
├── public/ ← Web 入口 + 静态资源
|
||
├── route/ ← 路由定义
|
||
├── templates/ ← 代码生成器模板
|
||
├── runtime/ ← 运行时缓存（自动生成）
|
||
├── vendor/ ← Composer 依赖
|
||
├── document/ ← 开发参考手册（txt）
|
||
├── .env ← 环境变量配置
|
||
└── think ← ThinkPHP 命令行入口
|
||
```
|
||
|
||
## app/ 目录详解
|
||
|
||
```text
|
||
app/
|
||
├── BaseController.php 控制器基类
|
||
├── BaseModel.php 模型基类
|
||
├── BaseLogic.php 业务逻辑基类（系统共享模块）
|
||
├── BaseTenantLogic.php 租户逻辑基类（租户隔离模块）
|
||
├── ExceptionHandle.php 统一异常处理（JSON 响应）
|
||
├── Request.php 请求类扩展
|
||
├── common.php 公共函数库
|
||
├── event.php 事件定义
|
||
├── middleware.php 全局中间件注册
|
||
│
|
||
├── controller/ 控制器层（28 个）
|
||
├── logic/ 业务逻辑层（26 个）
|
||
├── model/ 数据模型层（25 个）
|
||
├── validate/ 验证器（21 个）
|
||
├── service/ 通用服务层（11 个）
|
||
├── middleware/ 中间件（5 个）
|
||
├── attribute/ 注解定义（3 个）
|
||
├── command/ 命令行命令（4 个）
|
||
└── task/ 定时任务处理器（3 个）
|
||
```
|
||
|
||
### 各目录职责与命名规范
|
||
|
||
| 目录 | 职责 | 命名规则 | 数量 | 说明 |
|
||
|------|------|----------|------|------|
|
||
| `controller/` | HTTP 请求入口 | `{Module}Controller.php` | 28 | 一个模块一个文件，注解标注权限和日志 |
|
||
| `logic/` | 业务逻辑 | `{Module}Logic.php` | 26 | 属性配置 + 生命周期钩子，核心业务层 |
|
||
| `model/` | 数据库映射 | `{TableName}.php`（大驼峰） | 25 | 继承 BaseModel，获软删除 + 审计字段 |
|
||
| `validate/` | 参数校验 | `{Module}Validate.php` | 21 | 定义规则 + 场景，Logic 层自动调用 |
|
||
| `service/` | 通用服务 | `{Name}Service.php` | 11 | 跨模块复用的无状态工具类 |
|
||
| `middleware/` | 中间件 | `{Name}Middleware.php` | 5 | 请求拦截：认证、租户、日志等 |
|
||
| `attribute/` | 注解类 | `{Name}.php` | 3 | PHP 8 注解：Log、Permission、DemoAllow |
|
||
| `command/` | 命令行 | `{Name}Command.php` | 4 | CLI 命令：定时任务、代码生成、迁移 |
|
||
| `task/` | 任务处理器 | `{Name}Task.php` | 3 | 定时任务的具体执行逻辑 |
|
||
|
||
### 模块文件对应关系
|
||
|
||
以"用户管理"模块为例，一个完整模块包含 4 个文件：
|
||
|
||
```text
|
||
app/
|
||
├── controller/UserController.php ← HTTP 入口（路由指向这里）
|
||
├── logic/UserLogic.php ← 业务逻辑（属性配置 + 钩子）
|
||
├── model/User.php ← 数据模型（表映射）
|
||
└── validate/UserValidate.php ← 参数校验（规则 + 场景）
|
||
```
|
||
|
||
请求流转：`Controller → Logic → Model → 数据库`
|
||
|
||
### 基类与公共文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `BaseController.php` | 控制器基类：统一响应、参数获取、通用 CRUD 快捷方法 |
|
||
| `BaseLogic.php` | 逻辑基类：声明式 CRUD、生命周期钩子、自动参数校验、文件/富文本/枚举/权限/租户处理 |
|
||
| `BaseTenantLogic.php` | 租户逻辑基类：继承 BaseLogic，自动启用 `tenant_id` 隔离 |
|
||
| `BaseModel.php` | 模型基类：软删除（`is_delete`）、审计字段自动写入 |
|
||
| `ExceptionHandle.php` | 异常处理：所有异常统一渲染为 JSON 响应 |
|
||
| `common.php` | 公共函数：字符串处理、加密、文件操作、驼峰转换等 |
|
||
| `event.php` | 事件定义：全局事件监听 |
|
||
| `middleware.php` | 全局中间件注册：CORS 等 |
|
||
|
||
### service/ 服务层清单
|
||
|
||
服务层提供跨模块复用的无状态能力，按单一职责拆分：
|
||
|
||
| 服务 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| JWT 认证 | `JwtService.php` | 登录、刷新、解析 Token |
|
||
| 密码加密 | `PasswordService.php` | bcrypt 双重加盐 |
|
||
| 字典服务 | `DictService.php` | 字典缓存与查询（两级缓存） |
|
||
| 系统参数 | `ParamService.php` | 系统参数服务（两级缓存） |
|
||
| 验证码 | `CaptchaService.php` | 图片验证码生成与校验 |
|
||
| 请求信息 | `RequestInfoService.php` | 客户端 IP、UA、归属地解析 |
|
||
| 注解读取 | `AttributeService.php` | PHP 8 注解反射读取 + 缓存 |
|
||
| 代码生成 | `GeneratorService.php` | 根据数据库表生成 CRUD 代码 |
|
||
| 数据库迁移 | `DbMigrateService.php` | 跨数据库迁移引擎 |
|
||
| DDL 生成 | `DbSchemaBuilder.php` | 跨库类型映射的 DDL 生成器 |
|
||
| Excel | `ExcelService.php` | 导入导出（支持大数据量分批） |
|
||
|
||
### middleware/ 中间件清单
|
||
|
||
| 中间件 | 文件 | 作用域 | 说明 |
|
||
|--------|------|--------|------|
|
||
| 跨域 | `CorsMiddleware.php` | 全局 | CORS 头设置 |
|
||
| 认证权限 | `AuthMiddleware.php` | 路由级 | JWT 校验 + 权限校验 |
|
||
| 租户上下文 | `TenantMiddleware.php` | 路由级 | 解析注入 tenantId |
|
||
| 演示环境 | `DemoMiddleware.php` | 路由级 | 演示环境写操作拦截 |
|
||
| 操作日志 | `LogMiddleware.php` | 路由级 | 基于注解记录操作日志 |
|
||
|
||
### command/ 命令行清单
|
||
|
||
| 命令 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| 定时任务执行 | `JobRunCommand.php` | 执行一次定时任务 |
|
||
| 定时任务守护 | `JobDaemonCommand.php` | 常驻进程循环扫描执行 |
|
||
| 代码生成 | `GeneratorCommand.php` | CLI 方式生成 CRUD 代码 |
|
||
| 数据库迁移 | `DbMigrateCommand.php` | 跨数据库迁移 CLI 工具 |
|
||
|
||
## config/ 配置文件
|
||
|
||
```text
|
||
config/
|
||
├── api.php API 配置（驼峰转换开关）
|
||
├── app.php 应用配置（调试模式、异常处理）
|
||
├── cache.php 缓存配置（支持 Redis）
|
||
├── console.php 命令行配置
|
||
├── cors.php 跨域配置
|
||
├── database.php 数据库配置
|
||
├── file.php 文件上传配置（域名、大小限制）
|
||
├── jwt.php JWT 配置（密钥、过期时间）
|
||
├── middleware.php 中间件排除列表
|
||
└── route.php 路由配置
|
||
```
|
||
|
||
| 配置文件 | 关键配置项 | 说明 |
|
||
|----------|-----------|------|
|
||
| `api.php` | `camel_snake_convert` | 驼峰/下划线自动转换开关 |
|
||
| `database.php` | `type` / `hostname` / `database` | 数据库连接（支持 MySQL/PG/SqlServer/Oracle/SQLite） |
|
||
| `file.php` | `domain_url` / `max_size` | 文件上传域名和大小限制 |
|
||
| `jwt.php` | `secret` / `access_ttl` / `refresh_ttl` | JWT 密钥和令牌有效期 |
|
||
| `cache.php` | `type` / `host` | 缓存驱动（file/redis） |
|
||
|
||
## extend/ 扩展类库
|
||
|
||
存放不通过 Composer 管理的自定义类库，按 PSR-4 自动加载：
|
||
|
||
```text
|
||
extend/
|
||
├── jwt/
|
||
│ └── Jwt.php JWT 工具类（封装 firebase/php-jwt）
|
||
├── response/
|
||
│ └── Result.php 统一响应类（success/fail/page 等）
|
||
└── (无自定义扩展类)
|
||
```
|
||
|
||
使用方式：直接通过命名空间引用，如 `\response\Result::success()`、`\jwt\Jwt::getTokenFromHeader()`。
|
||
|
||
## route/ 路由定义
|
||
|
||
```text
|
||
route/
|
||
└── app.php 应用路由定义（所有 API 路由）
|
||
```
|
||
|
||
路由按模块分组，示例：
|
||
|
||
```php
|
||
// 公开接口（无需认证）
|
||
Route::group('login', function () {
|
||
Route::post('login', 'LoginController/login');
|
||
Route::get('captcha', 'LoginController/captcha');
|
||
});
|
||
|
||
// 需认证接口（AuthMiddleware）
|
||
Route::group('article', function () {
|
||
Route::get('page', 'ArticleController/page');
|
||
Route::post('add', 'ArticleController/add');
|
||
Route::put('update', 'ArticleController/update');
|
||
Route::delete('delete/:id', 'ArticleController/delete');
|
||
})->middleware(AuthMiddleware::class);
|
||
```
|
||
|
||
## templates/ 代码生成模板
|
||
|
||
```text
|
||
templates/
|
||
├── controller.php.tpl 控制器模板
|
||
├── logic.php.tpl 业务逻辑模板
|
||
├── model.php.tpl 模型模板
|
||
├── validate.php.tpl 验证器模板
|
||
├── ui/ 普通列表前端模板
|
||
└── ui2/ 树形结构前端模板
|
||
```
|
||
|
||
由 `GeneratorService` 渲染，通过代码生成器 CLI 或 API 调用。
|
||
|
||
## 前端目录设计
|
||
|
||
```text
|
||
ui/src/
|
||
├── api/ ← API 接口（按业务域分组）
|
||
├── views/ ← 页面视图（按业务域分组）
|
||
├── components/ ← 公共组件（跨页面复用）
|
||
├── store/ ← 状态管理（Pinia）
|
||
├── router/ ← 路由配置
|
||
├── hooks/ ← 组合式函数
|
||
├── directives/ ← 自定义指令
|
||
├── enums/ ← 枚举常量
|
||
├── styles/ ← 全局样式
|
||
├── utils/ ← 工具函数
|
||
├── layout/ ← 布局组件
|
||
├── plugins/ ← 插件
|
||
├── settings/ ← 项目配置
|
||
└── assets/ ← 静态资源
|
||
```
|
||
|
||
## 前后端目录对应关系
|
||
|
||
| 后端 | 前端 | 说明 |
|
||
|------|------|------|
|
||
| `app/controller/UserController.php` | `src/api/system/user.ts` | API 接口函数 |
|
||
| `app/logic/UserLogic.php` | `src/views/system/user/` | 业务页面 |
|
||
| `app/model/User.php` | — | 前端不直接操作模型 |
|
||
| `app/validate/UserValidate.php` | — | 前端校验由表单组件处理 |
|
||
| `route/app.php` | `src/api/**/*.ts` | 路由 ↔ API 函数映射 |
|
||
| `config/dict*.php` | `src/enums/` | 字典 ↔ 枚举常量 |
|
||
|
||
## 设计原则
|
||
|
||
### 按职责分层
|
||
|
||
每层只做一件事，层间通过方法调用串联：
|
||
|
||
| 层 | 职责 | 不应该做 |
|
||
|----|------|----------|
|
||
| Controller | 参数获取、响应封装、注解标注 | 业务逻辑、数据库操作 |
|
||
| Logic | 业务编排、钩子处理、校验 | 直接 HTTP 交互 |
|
||
| Model | 表映射、关联关系、软删除 | 复杂业务判断 |
|
||
| Validate | 参数格式校验 | 业务规则校验 |
|
||
|
||
### 按模块分组
|
||
|
||
同一业务模块的 4 个文件（Controller / Logic / Model / Validate）分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：
|
||
|
||
- 便于按职责查找（所有控制器在一起）
|
||
- 便于代码生成器按模板批量生成
|
||
- 便于基类统一处理（如 BaseLogic 的属性驱动）
|
||
|
||
### 文件命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 控制器 | 大驼峰 + Controller | `ArticleController.php` |
|
||
| 逻辑层 | 大驼峰 + Logic | `ArticleLogic.php` |
|
||
| 模型 | 大驼峰（表名） | `Article.php` |
|
||
| 验证器 | 大驼峰 + Validate | `ArticleValidate.php` |
|
||
| 服务 | 大驼峰 + Service | `DictService.php` |
|
||
| 中间件 | 大驼峰 + Middleware | `AuthMiddleware.php` |
|
||
| 注解 | 大驼峰 | `Log.php`、`Permission.php` |
|
||
| 命令 | 大驼峰 + Command | `GeneratorCommand.php` |
|
||
| 任务 | 大驼峰 + Task | `SendSmsTask.php` |
|