rxthinkcmf/rxthinkcmf-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

签入版本

Browse Source
This commit is contained in:
gitadmin
2026-10-08 17:50:29 +08:00
parent 809750b47e
commit e213a9b31d
444 changed files with 39366 additions and 37533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
RXThinkCMF_Laravel13_EleVue/zh/architecture/directory-design.md
+139 -158
View File
@@ -1,7 +1,7 @@
# 4.5 目录结构设计
:::tip 概述
目录结构遵循"按职责分层、按模块分组"的原则。后端以 `app/` 为核心，按 Controller → Logic → Model → Validate 四层组织；前端以 `src/` 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
目录结构遵循"按职责分层、按模块分组"的原则。后端以 `app/` 为核心，按 Controller → Request → Service → Model 四层组织；前端以 `src/` 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
:::
## 后端整体结构
@@ -9,57 +9,65 @@
```text
项目根目录/
├── app/ ← 应用代码（核心）
├── config/ ← 配置文件
├── extend/ ← 扩展类库（非 Composer）
├── bootstrap/ ← 应用引导（中间件别名/分组、健康检查路由）
├── config/ ← 配置文件（18 个，7 个独立业务配置）
├── database/ ← 迁移（空）/ 种子 / 工厂
├── docker/ ← Docker 部署文件
├── public/ ← Web 入口 + 静态资源
├── route/ ← 路由定义
├── templates/ ← 代码生成器模板
├── runtime/ ← 运行时缓存（自动生成）
├── resources/ ← 生成器模板（templates/）+ Blade 视图 + Vite 资源
├── routes/ ← 路由定义（api / web / console）
├── storage/ ← 运行时产物（日志/缓存/会话，需可写）
├── tests/ ← PHPUnit 测试
├── uploads/ ← 上传文件目录
├── vendor/ ← Composer 依赖
├── wiki/ ← 文档站点（VitePress）
├── document/ ← 开发参考手册（txt）
├── .env ← 环境变量配置
└── think ← ThinkPHP 命令行入口
├── document/ ← 五种数据库初始化脚本
├── artisan ← Artisan 命令行入口
└── .env ← 环境变量配置
```
## 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 个）
├── Attributes/ 注解定义（3 个）
│ ├── Permission.php 权限校验注解
│ ├── OperationLog.php 操作日志注解
│ └── DemoAllow.php 演示环境放行注解
├── Console/Commands/ 命令行命令（5 个）
├── Exceptions/ 异常处理
│ ├── BizException.php 业务异常
│ └── Handler.php 统一异常渲染（JSON）
├── Helpers/helpers.php 全局辅助函数（21 个）
├── Http/
│ ├── Controllers/
│ │ ├── Controller.php 控制器基类
│ │ └── Api/ 控制器层（28 个）
│ ├── Middleware/ 中间件（7 个）
│ └── Requests/ 表单请求（24 个 + BaseRequest）
├── Models/ 数据模型层（25 个）
│ └── Concerns/ 模型 Trait（3 个）
├── Observers/ 模型观察者（3 个，缓存失效）
├── Providers/ 服务提供者（启动校验 + Observer + oci 驱动注册）
├── Services/ 服务层（36 个）
│ └── Concerns/ Service Trait（7 个）
├── Support/ 基础支撑（Auth / Result）
└── 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 | 定时任务的具体执行逻辑 |
| `Http/Controllers/Api/` | HTTP 请求入口 | `{Module}Controller.php` | 28 | 一个模块一个文件，注解标注权限和日志 |
| `Http/Requests/` | 参数格式校验 | `{Module}Request.php` | 24+1 | 继承 BaseRequest，控制器类型注入 |
| `Services/` | 业务逻辑 | `{Module}Service.php` | 36 | 属性配置 + 生命周期钩子，核心业务层 |
| `Models/` | 数据库映射 | `{TableName}.php`（大驼峰） | 25 | 模型 Trait 获软删除 + 审计字段 |
| `Http/Middleware/` | 中间件 | 见下方清单 | 7 | 请求拦截：认证、租户、日志等 |
| `Attributes/` | 注解类 | `{Name}.php` | 3 | Permission、OperationLog、DemoAllow |
| `Console/Commands/` | 命令行 | `{Name}Command.php` 等 | 5 | CLI 命令：生成器、迁移、任务、字典缓存 |
| `Task/` | 任务处理器 | `{Name}Task.php` | 3 | 定时任务的具体执行逻辑 |
| `Observers/` | 缓存失效 | `{Name}Observer.php` | 3 | 字典/菜单/角色菜单变更 → 清缓存 |
| `Support/` | 基础支撑 | `Auth.php` / `Result.php` | 2 | 当前登录用户 / 统一响应 |
### 模块文件对应关系
@@ -67,141 +75,110 @@ app/
```text
app/
├── controller/UserController.php ← HTTP 入口（路由指向这里）
├── logic/UserLogic.php ← 业务逻辑（属性配置 + 钩子）
├── model/User.php ← 数据模型（表映射）
└── validate/UserValidate.php ← 参数校验（规则 + 场景）
├── Http/Controllers/Api/UserController.php ← HTTP 入口（路由指向这里）
├── Http/Requests/UserRequest.php ← 参数校验（规则 + 中文消息）
├── Services/UserService.php ← 业务逻辑（属性配置 + 钩子）
└── Models/User.php ← 数据模型（表映射 + Trait）
```
请求流转：`Controller → Logic → Model → 数据库`
请求流转：`Controller → (FormRequest 校验) → Service → 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 等 |
| `Http/Controllers/Controller.php` | 控制器基类：`success/fail/paginate` 响应 + `_page/_add` 等通用 CRUD 快捷方法 + 参数获取 |
| `Http/Requests/BaseRequest.php` | 请求基类：授权统一放行、失败统一 JSON |
| `Services/BaseService.php` | 服务基类：**全部声明式属性集中声明** + Trait 占位方法 + 处理链 |
| `Services/BaseTenantService.php` | 租户服务基类：继承 BaseService，自动 `tenant_id` 查询/写入隔离 |
| `Exceptions/Handler.php` | 异常处理：`api/*` 异常统一渲染为 JSON 响应 |
| `Exceptions/BizException.php` | 业务异常：Service 抛出，默认 `code=1` |
| `Support/Result.php` | 统一响应：`success/page/fail/unauthorized/forbidden/notFound/validateError` |
| `Support/Auth.php` | 当前登录用户：`Auth::userId()` / `Auth::username()` |
| `Helpers/helpers.php` | 公共函数：驼峰转换、文件处理、字符串等 21 个（composer autoload.files） |
### service/ 服务层清单
### Services 横切服务清单
服务层提供跨模块复用的无状态能力，按单一职责拆分：
跨模块复用的无状态能力（业务 Service 之外）：
| 服务 | 文件 | 说明 |
|------|------|------|
| JWT 认证 | `JwtService.php` | 登录、刷新、解析 Token |
| 密码加密 | `PasswordService.php` | bcrypt 双重加盐 |
| 字典服务 | `DictService.php` | 字典缓存与查询（两级缓存） |
| 系统参数 | `ParamService.php` | 系统参数服务（两级缓存） |
| 验证码 | `CaptchaService.php` | 图片验证码生成与校验 |
| 请求信息 | `RequestInfoService.php` | 客户端 IP、UA、归属地解析 |
| 注解读取 | `AttributeService.php` | PHP 8 注解反射读取 + 缓存 |
| JWT 认证 | `JwtService.php` | 登录、刷新、解析、踢下线（Redis 有状态） |
| 密码加密 | `PasswordService.php` | bcrypt（成本因子 12） |
| 字典服务 | `DictCacheService.php` | 字典缓存与查询（两级缓存） |
| 验证码 | `CaptchaService.php` | 图片验证码生成与校验（IP 限流） |
| 请求信息 | `RequestInfoService.php` | 客户端 IP、UA、归属地解析（ip2region） |
| 代码生成 | `GeneratorService.php` | 根据数据库表生成 CRUD 代码 |
| 数据库迁移 | `DbMigrateService.php` | 跨数据库迁移引擎 |
| DDL 生成 | `DbSchemaBuilder.php` | 跨库类型映射的 DDL 生成器 |
| Excel | `ExcelService.php` | 导入导出（支持大数据量分批） |
| 数据库迁移 | `DbMigrateService.php` | 跨数据库迁移引擎（五驱动） |
| DDL 生成 | `DbSchemaBuilder.php` | 跨库类型映射的 DDL 生成器（Oracle 序列/触发器） |
| Excel | `ExcelService.php` | 导入导出（表头映射、分批） |
| 配置管理 | `ConfigService.php` | 系统配置读写与缓存 |
| 字典管理 | `DictService.php` | 字典/字典项管理 |
### middleware/ 中间件清单
### Middleware 中间件清单
| 中间件 | 文件 | 作用域 | 说明 |
|--------|------|--------|------|
| 跨域 | `CorsMiddleware.php` | 全局 | CORS 头设置 |
| 认证权限 | `AuthMiddleware.php` | 路由级 | JWT 校验 + 权限校验 |
| 租户上下文 | `TenantMiddleware.php` | 路由级 | 解析注入 tenantId |
| 演示环境 | `DemoMiddleware.php` | 路由级 | 演示环境写操作拦截 |
| 操作日志 | `LogMiddleware.php` | 路由级 | 基于注解记录操作日志 |
| 中间件 | 文件 | 别名 | 作用域 | 说明 |
|--------|------|------|--------|------|
| 真实 IP | `ProxyMiddleware.php` | proxy | 全局（api prepend） | 受信代理 `X-Forwarded-For` 解析 |
| 跨域 | `Cors.php` | cors | 全局 | CORS 头设置（`config/cors.php`） |
| 强制 JSON | `ForceJsonResponse.php` | force.json | 全局 | 规范化 Accept 头 |
| 认证权限 | `Authenticate.php` | auth.jwt | 路由组 | JWT 校验 + `#[Permission]` 鉴权 |
| 租户上下文 | `ResolveTenant.php` | tenant | 路由组 | 解析注入 tenantId |
| 操作日志 | `LogOperation.php` | log.operation | 路由组 | 基于 `#[OperationLog]` 采集，terminable 落库 |
| 演示环境 | `DemoMiddleware.php` | demo | 路由别名 | 写操作拦截，`#[DemoAllow]` 放行 |
### command/ 命令行清单
### Console 命令清单
| 命令 | 文件 | 说明 |
|------|------|------|
| 定时任务执行 | `JobRunCommand.php` | 执行一次定时任务 |
| 定时任务守护 | `JobDaemonCommand.php` | 常驻进程循环扫描执行 |
| 代码生成 | `GeneratorCommand.php` | CLI 方式生成 CRUD 代码 |
| 数据库迁移 | `DbMigrateCommand.php` | 跨数据库迁移 CLI 工具 |
| 命令 | 文件 | 签名 | 说明 |
|------|------|------|------|
| 代码生成 | `GeneratorCommand.php` | `generate:code` | CLI 方式生成 CRUD 代码 |
| 数据库迁移 | `DbMigrateCommand.php` | `db:migrate` | 跨数据库迁移 CLI 工具 |
| 定时任务执行 | `JobRunCommand.php` | `job:run` | 执行一次到期任务（配合系统 cron） |
| 定时任务守护 | `JobDaemonCommand.php` | `job:daemon` | 常驻进程循环扫描执行 |
| 字典缓存清理 | `ClearDictCache.php` | `dict:clear-cache` | 清除字典缓存 |
## 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 API 配置（驼峰转换开关）★
├── captcha.php 验证码配置 ★
├── cors.php 跨域配置 ★
├── file.php 文件上传配置（域名、大小限制）★
├── jwt.php JWT 配置（密钥、过期时间）★
├── middleware.php 中间件配置（受信代理）★
├── tenant.php 多租户配置 ★
├── generator.php 代码生成器配置
├── app.php / auth.php / cache.php / database.php / filesystems.php
├── logging.php / mail.php / queue.php / services.php / session.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） |
标 ★ 为本项目独立维护的配置文件（不与 Laravel 默认配置合并）。
## extend/ 扩展类库
存放不通过 Composer 管理的自定义类库，按 PSR-4 自动加载：
## routes/ 路由定义
```text
extend/
├── jwt/
│ └── Jwt.php JWT 工具类（封装 firebase/php-jwt）
├── response/
│ └── Result.php 统一响应类（success/fail/page 等）
└── (无自定义扩展类)
routes/
├── api.php 全部 API 路由（公开接口在中间件组外）
├── web.php 欢迎页
└── console.php 调度注册
```
使用方式：直接通过命名空间引用，如 `\response\Result::success()`、`\jwt\Jwt::getTokenFromHeader()`。
路由组织约定见 [3.7 路由注册](/zh/guide/route.html)。
## route/ 路由定义
## resources/templates/ 代码生成模板
```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/
resources/templates/
├── controller.php.tpl 控制器模板
├── logic.php.tpl 业务逻辑模板
├── service.php.tpl 服务层模板
├── model.php.tpl 模型模板
├── validate.php.tpl 验证器模板
├── ui/ 普通列表前端模板
├── request.php.tpl FormRequest 模板
├── ui/ 普通列表前端模板（6 个）
└── ui2/ 树形结构前端模板
```
由 `GeneratorService` 渲染，通过代码生成器 CLI 或 API 调用。
由 `GeneratorService` 渲染，通过 CLI（`generate:code`）或 Web 界面调用。
## 前端目录设计
@@ -211,28 +188,32 @@ ui/src/
├── views/ ← 页面视图（按业务域分组）
├── components/ ← 公共组件（跨页面复用）
├── store/ ← 状态管理（Pinia）
├── router/ ← 路由配置
├── router/ ← 路由配置（动态路由由后端菜单驱动）
├── hooks/ ← 组合式函数
├── directives/ ← 自定义指令
├── directives/ ← 自定义指令（v-perm 权限）
├── enums/ ← 枚举常量
├── styles/ ← 全局样式
├── utils/ ← 工具函数
├── utils/ ← 工具函数（http 封装）
├── layout/ ← 布局组件
├── plugins/ ← 插件
├── settings/ ← 项目配置
└── assets/ ← 静态资源
```
:::tip
前端工程位于本仓库 `ui/` 目录，代码生成器输出至 `ui/src/` 对应位置。详细结构见 [9.2 目录结构详解](/zh/frontend/directory.html)。
:::
## 前后端目录对应关系
| 后端 | 前端 | 说明 |
|------|------|------|
| `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/` | 字典 ↔ 枚举常量 |
| `Http/Controllers/Api/UserController.php` | `ui/src/api/system/user.ts` | API 接口函数 |
| `Services/UserService.php` | `src/views/system/user/` | 业务页面 |
| `Models/User.php` | — | 前端不直接操作模型 |
| `Http/Requests/UserRequest.php` | 表单组件校验 | 前端校验为体验层，后端 FormRequest 为最终防线 |
| `routes/api.php` | `ui/src/api/**/*.ts` | 路由 ↔ API 函数映射 |
| 字典数据（`dict` 表） | `src/enums/` | 字典 ↔ 枚举常量 |
## 设计原则
@@ -242,29 +223,29 @@ ui/src/
| 层 | 职责 | 不应该做 |
|----|------|----------|
| Controller | 参数获取、响应封装、注解标注 | 业务逻辑、数据库操作 |
| Logic | 业务编排、钩子处理、校验 | 直接 HTTP 交互 |
| Model | 表映射、关联关系、软删除 | 复杂业务判断 |
| Validate | 参数格式校验 | 业务规则校验 |
| Controller | 参数注入、响应封装、注解标注 | 业务逻辑、数据库操作 |
| Request | 参数**格式**校验 | 业务规则校验 |
| Service | 业务编排、钩子处理、业务规则校验 | 直接 HTTP 交互 |
| Model | 表映射、关联关系、软删除、审计 | 复杂业务判断 |
### 按模块分组
同一业务模块的 4 个文件（Controller / Logic / Model / Validate）分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：
同一业务模块的 4 个文件分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：
- 便于按职责查找（所有控制器在一起）
- 便于按职责查找（所有服务在一起）
- 便于代码生成器按模板批量生成
- 便于基类统一处理（如 BaseLogic 的属性驱动）
- 便于基类统一处理（BaseService 属性驱动 + Trait 占位覆盖）
### 文件命名规范
| 类型 | 规范 | 示例 |
|------|------|------|
| 控制器 | 大驼峰 + Controller | `ArticleController.php` |
| 逻辑层 | 大驼峰 + Logic | `ArticleLogic.php` |
| 请求 | 大驼峰 + Request | `ArticleRequest.php` |
| 服务 | 大驼峰 + Service | `ArticleService.php` |
| 模型 | 大驼峰（表名） | `Article.php` |
| 验证器 | 大驼峰 + Validate | `ArticleValidate.php` |
| 服务 | 大驼峰 + Service | `DictService.php` |
| 中间件 | 大驼峰 + Middleware | `AuthMiddleware.php` |
| 注解 | 大驼峰 | `Log.php`、`Permission.php` |
| 命令 | 大驼峰 + Command | `GeneratorCommand.php` |
| 中间件 | 大驼峰（动词+名词） | `Authenticate.php` / `ResolveTenant.php` |
| 注解 | 大驼峰 | `Permission.php`、`OperationLog.php` |
| 命令 | 大驼峰 + Command（或动词开头） | `GeneratorCommand.php`、`ClearDictCache.php` |
| 任务 | 大驼峰 + Task | `SendSmsTask.php` |
| Trait | 动词开头 + Has/By | `HasCrudOperations.php`、`SoftDeletesByFlag.php` |