签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,270 @@
+# 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 依赖
+├── wiki/                   ← 文档站点（VitePress）
+├── 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` |