# 1.3 目录结构 ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 ```text 1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。 2. 分层架构：Controller（HTTP）、Service（业务）、Model（数据）分离，职责清晰。 3. Trait 组合复用：通用能力集中在 BaseService 与 6 个 Concerns Trait，子类只声明差异。 4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。 ``` ## 项目根目录 ```text RXThinkCMF_Laravel13_EleVue/ ├── app/ // 后端源码（见下方详解） ├── bootstrap/ // 应用引导（app.php 注册中间件别名与健康检查路由） ├── config/ // 配置文件（18 个） ├── database/ │ ├── migrations/ // 数据库迁移（本项目为空，建表以 SQL 脚本为准） │ ├── seeders/ // 种子数据（DatabaseSeeder：租户/部门/角色/菜单/用户/字典） │ └── factories/ // 模型工厂（测试数据） ├── docker/ // Docker 部署文件（Dockerfile / nginx.conf / .env.docker） ├── document/ // 项目资料（五种数据库初始化脚本，按类型分组） ├── docs/ // 专项文档（定时任务调度说明） ├── public/ // Web 公开目录（入口 index.php、静态资源） ├── resources/ │ ├── templates/ // ★ 代码生成器模板（*.tpl + ui/ + ui2/） │ ├── views/ // Blade 视图（欢迎页等少量页面） │ ├── css/ js/ // Vite 资源入口（TailwindCSS） ├── routes/ │ ├── api.php // ★ 全部 API 路由（公开接口在中间件组外） │ ├── console.php // 命令调度注册 │ └── web.php // 欢迎页路由 ├── storage/ // 运行时产物（日志/缓存/会话/编译视图，需可写） ├── tests/ // PHPUnit 测试（Feature / Unit） ├── ui/ // ★ 前端 EleVue 管理后台（Vue3 + ElementPlus，见第 9 章） ├── uploads/ // 上传文件目录 ├── vendor/ // Composer 依赖（不提交到版本控制） ├── artisan // Artisan 命令行入口 ├── composer.json // PHP 依赖清单（含 setup / dev / test 脚本） ├── package.json // 后端资源构建依赖（Vite + TailwindCSS，前端依赖见 ui/package.json） ├── vite.config.js // Vite 构建配置 ├── docker-compose.yml // Docker 容器编排 ├── .env.example // 环境变量模板 ├── .env // 环境变量（不提交到版本控制） └── README.md // 项目说明 ``` :::tip 前端代码位置 本仓库包含**后端服务**与 `ui/` 目录内的前端 EleVue 管理后台（Vue3 + ElementPlus）；代码生成器会把生成的前端页面输出到 `ui/src/` 对应位置（见 [10.6 自定义模板开发](/zh/generator/templates.html)）。前端工程结构详见 [第 9 章 前端开发](/zh/frontend/overview.html)。 ::: ## 后端目录 (app/) ```text app/ ├── Attributes/ // PHP 8 注解 │ ├── Permission.php // 权限校验注解（#[Permission('sys:user:add')]） │ ├── OperationLog.php // 操作日志注解（类型 + 模板，40 种操作类型） │ └── DemoAllow.php // 演示环境放行注解 ├── Console/Commands/ // 5 个 Artisan 命令 │ ├── GeneratorCommand.php // generate:code 代码生成器 CLI │ ├── DbMigrateCommand.php // db:migrate 跨库数据迁移 │ ├── JobRunCommand.php // job:run 定时任务一次性执行（配合系统 cron） │ ├── JobDaemonCommand.php // job:daemon 定时任务常驻进程（配合 supervisor） │ └── ClearDictCache.php // dict:clear-cache 清除字典缓存 ├── Exceptions/ // 统一异常处理 │ ├── BizException.php // 业务异常（Service 层抛出，默认 code=1） │ └── Handler.php // 全局异常渲染（异常 → 统一 JSON） ├── Helpers/helpers.php // 21 个全局辅助函数（composer autoload.files 加载） ├── Http/ │ ├── Controllers/ │ │ ├── Controller.php // 控制器基类（统一响应 + _page/_add 等通用 CRUD） │ │ └── Api/ // 28 个业务控制器 │ │ ├── AuthController.php // 登录认证（JWT 双令牌 / OAuth2） │ │ ├── UserController.php // 用户管理 │ │ ├── RoleController.php // 角色管理 │ │ ├── MenuController.php // 菜单管理 │ │ ├── ExampleController.php // 案例演示（标准 CRUD 参考模板） │ │ ├── GeneratorController.php // 代码生成器 │ │ └── ... // 其他模块 │ ├── Middleware/ // 7 个中间件 │ │ ├── ProxyMiddleware.php // 真实 IP 提取（受信代理） │ │ ├── Cors.php // 跨域处理 │ │ ├── ForceJsonResponse.php // 强制 JSON 响应 │ │ ├── Authenticate.php // JWT 认证 + #[Permission] 鉴权（auth.jwt） │ │ ├── ResolveTenant.php // 租户上下文解析（tenant） │ │ ├── LogOperation.php // 操作日志采集（log.operation，terminable 落库） │ │ └── DemoMiddleware.php // 演示模式写操作拦截 │ └── Requests/ // 24 个 FormRequest（统一继承 BaseRequest） │ ├── BaseRequest.php // 基类：授权放行 + 失败统一 JSON │ ├── ExampleRequest.php // 示例请求验证 │ └── ... // 其他模块请求验证 ├── Models/ // Eloquent 模型（25 个） │ ├── Concerns/ // 3 个模型 Trait │ │ ├── SoftDeletesByFlag.php // is_delete 软删除 │ │ ├── SoftDeleteFlagScope.php// 全局软删除范围 │ │ └── HasAuditColumns.php // 审计字段自动填充 │ ├── User.php // 用户模型（$table = 'user'，前缀由 DB_PREFIX 决定） │ ├── Example.php // 案例模型 │ └── ... // 其他模型 ├── Observers/ // 模型观察者（数据变更 → 缓存失效） │ ├── DictItemObserver.php // 字典项变更 → 清除字典缓存 │ ├── MenuObserver.php // 菜单变更 → 清除菜单/权限缓存 │ └── RoleMenuObserver.php // 角色菜单变更 → 清除角色权限缓存 ├── Providers/ │ └── AppServiceProvider.php // 启动校验（JWT_SECRET fail-close）+ Observer 注册 ├── Services/ // ★ 业务逻辑层（36 个） │ ├── BaseService.php // 核心基类（全部声明式属性集中于此） │ ├── BaseTenantService.php // 租户版基类（tenant_id 查询/写入双隔离） │ ├── Concerns/ // 7 个 Service Trait（只放方法） │ │ ├── HasCrudOperations.php // add/update/delete + 生命周期钩子 + 事务 │ │ ├── HasQueryScopes.php // buildQuery / 排序白名单 │ │ ├── HasFileProcessing.php // 文件字段自动处理（临时→正式、域名补全） │ │ ├── HasDataScope.php // 数据权限 + 租户隔离 │ │ ├── HasSerializeMaps.php // 字典翻译（DictCacheService 批量优化） │ │ ├── HasUniqueCheck.php // 唯一性校验 │ │ └── HasConfigValueProcessing.php // 配置项 value 按类型处理（文件迁移 / valueList） │ ├── ExampleService.php // 案例演示服务（标准 CRUD 参考模板） │ ├── JwtService.php // JWT 签发 / 刷新 / 解析 │ ├── DictCacheService.php // 字典服务（两级缓存） │ ├── GeneratorService.php // 代码生成服务 │ ├── ExcelService.php // Excel 导入导出 │ ├── DbMigrateService.php // 跨数据库数据迁移 │ └── ... // 其他业务/横切服务 ├── Support/ // 基础支撑 │ ├── Auth.php // 当前登录用户（Auth::userId() 等） │ └── Result.php // 统一响应类（success/page/fail/...） └── Task/ // 定时任务处理器 ├── BaseTask.php // 任务基类 ├── HelloWorldTask.php // 测试任务（验证 daemon 调度） └── SendSmsTask.php // 示例任务 ``` ## 后端模块内部结构 每个业务模块遵循统一的文件结构： ```text app/Http/Controllers/Api/{Name}Controller.php // HTTP 入口（注解 + 调用快捷方法） app/Http/Requests/{Name}Request.php // 参数格式验证（FormRequest） app/Services/{Name}Service.php // 业务逻辑（属性配置 + 钩子） app/Models/{Name}.php // 数据模型（表映射 + 关联） ``` | 文件 | 职责 | 基类 | |------|------|------| | Controller | 接收请求、调用 Service、返回统一响应 | `App\Http\Controllers\Controller` | | Request | 参数格式验证（必填、类型、格式） | `BaseRequest` | | Service | 业务逻辑、属性声明、生命周期钩子 | `BaseService` / `BaseTenantService` | | Model | 数据库表映射、关联关系、软删除、审计字段 | Eloquent Model + Concerns Trait | ## 配置目录 (config/) ```text config/ ├── api.php // API 配置（驼峰/下划线自动转换开关）★ 独立配置 ├── captcha.php // 验证码配置（长度/字符集/有效期/万能码）★ 独立配置 ├── cors.php // 跨域配置（允许来源/方法/头）★ 独立配置 ├── file.php // 文件上传配置（目录/域名/大小/后缀白名单）★ 独立配置 ├── jwt.php // JWT 配置（密钥/有效期/签发者）★ 独立配置 ├── middleware.php // 中间件配置（受信代理等）★ 独立配置 ├── tenant.php // 多租户配置（默认租户 ID）★ 独立配置 ├── generator.php // 代码生成器配置（父菜单 ID、应用名） ├── app.php // 应用配置（名称/时区/调试模式） ├── auth.php // 认证配置 ├── cache.php // 缓存配置（redis 驱动） ├── database.php // 数据库配置（mysql/pgsql/sqlsrv/sqlite + redis） ├── filesystems.php // 文件系统配置 ├── logging.php // 日志配置 ├── mail.php // 邮件配置 ├── queue.php // 队列配置 ├── services.php // 第三方服务配置 └── session.php // 会话配置 ``` :::tip 独立配置约定 标 ★ 的 7 个配置文件为本项目**独立维护**（不与 Laravel 默认配置合并），通过 `config('jwt.secret')`、`config('file.domain_url')` 等方式读取。完整配置项见 [附录 C 配置项速查](/zh/appendix/config-reference.html)。 ::: ## 数据库目录 (database/) ```text database/ ├── migrations/ // 迁移目录（本项目为空，建表以 SQL 导出为准） ├── seeders/ │ └── DatabaseSeeder.php // 初始数据：租户、部门、角色、菜单、用户、字典 └── factories/ // 模型工厂 ``` :::warning 注意 本项目**未使用 Laravel 迁移建表**，数据库结构以 `document/<数据库类型>/rxthinkcmf.laravel13.elevue.sql` 脚本为准（25 张业务表，`laravel_` 前缀，五种数据库各有专用脚本）。`composer setup` 中的 `migrate --force` 仅初始化迁移记录表，不会创建业务表。详见 [2.5 数据库初始化](/zh/quickstart/database-init.html)。 ::: ## 代码生成模板 (resources/templates/) ```text resources/templates/ ├── controller.php.tpl // 控制器模板 ├── service.php.tpl // 服务层模板 ├── model.php.tpl // 模型模板 ├── request.php.tpl // FormRequest 模板 ├── ui/ // 普通列表模板（前端文件） │ ├── index.vue.tpl // 列表页模板 │ ├── edit.vue.tpl // 编辑弹窗模板 │ ├── detail.vue.tpl // 详情弹窗模板 │ ├── api.ts.tpl // API 接口模板 │ ├── columns.ts.tpl // 表格列定义模板 │ └── querySchemas.ts.tpl // 查询条件模板 └── ui2/ // 树形结构模板（前端文件） ``` ## 路由目录 (routes/) ```text routes/ ├── api.php // ★ 全部 API 路由（约 165 条） │ // 公开接口（login/captcha/refresh/oauth2）在中间件组外 │ // 认证接口在 ['auth.jwt','tenant','log.operation'] 组内 ├── console.php // Artisan 调度注册 └── web.php // 欢迎页路由（/up 健康检查由 bootstrap/app.php 注册） ``` ## Docker 目录 (docker/) ```text docker-compose.yml // 四容器编排（Nginx + PHP-FPM + MySQL + Redis） docker/ ├── Dockerfile // PHP 8.3-fpm 应用镜像（扩展 + Composer 依赖） ├── nginx.conf // Nginx 站点配置（Laravel 路由重写 + 安全规则） └── .env.docker // 容器环境变量（密码、端口、JWT 密钥） ``` ## 资料目录 (document/) ```text document/ ├── .gitignore // 忽略规则（脚本等大文件不进版本库） ├── mysql/ │ └── rxthinkcmf.laravel13.elevue.sql // ★ MySQL 初始化脚本（约 226MB，25 张业务表 + 初始数据） ├── postgresql/ │ └── rxthinkcmf.laravel13.elevue.sql // PostgreSQL 初始化脚本 ├── sqlserver/ │ └── rxthinkcmf.laravel13.elevue.sql // SQL Server 初始化脚本 ├── oracle/ │ └── rxthinkcmf.laravel13.elevue.sql // Oracle 初始化脚本 └── sqlite/ └── rxthinkcmf.laravel13.elevue.sql // SQLite 初始化脚本 ``` :::tip 五种数据库脚本按类型分组，已做对应 SQL 语法适配，直接导入即可（见 [2.5 数据库初始化](/zh/quickstart/database-init.html)）。Docker 首次启动自动导入 `document/mysql/` 下的脚本。 ::: ## 关键配置文件 | 文件 | 作用 | |------|------| | `.env` | 数据库连接、JWT 密钥、Redis 密码、文件上传等环境变量 | | `config/database.php` | 数据库配置（4 种关系库 + Redis 连接） | | `config/jwt.php` | JWT 配置（密钥 / access·refresh 有效期 / 签发者） | | `config/file.php` | 文件上传配置（目录 / 域名 / 大小 / 后缀白名单） | | `config/cors.php` | 跨域配置（允许来源 / 方法 / 头） | | `config/app.php` | 应用配置（名称 / 时区 / 调试模式、受信代理 `trusted_proxies`） | | `config/api.php` | 响应驼峰/下划线自动转换开关 | | `config/tenant.php` | 多租户配置（默认租户 ID） | | `config/generator.php` | 代码生成器配置（父菜单 ID、应用名） | | `composer.json` | 依赖清单 + `setup` / `dev` / `test` 脚本 | | `bootstrap/app.php` | 中间件别名注册、全局中间件组、`/up` 健康检查 | :::tip 注意事项 + 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。 + 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。 + 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。 + 版本控制：使用 `Git` 等版本控制工具，并在 `.gitignore` 文件中配置不需要跟踪的目录和文件（`vendor/`、`storage/`、`.env` 等）。 ::: ## 总结 软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。本项目采用分层的目录结构（后端 Controller → Service → Model，Trait 组合复用横切能力），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。