252 lines
12 KiB
Markdown
252 lines
12 KiB
Markdown
# 4.5 目录结构设计
|
||
|
||
:::tip 概述
|
||
目录结构遵循"按职责分层、按模块分组"的原则。后端以 `app/` 为核心，按 Controller → Request → Service → Model 四层组织；前端以 `src/` 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
|
||
:::
|
||
|
||
## 后端整体结构
|
||
|
||
```text
|
||
项目根目录/
|
||
├── app/ ← 应用代码（核心）
|
||
├── bootstrap/ ← 应用引导（中间件别名/分组、健康检查路由）
|
||
├── config/ ← 配置文件（18 个，7 个独立业务配置）
|
||
├── database/ ← 迁移（空）/ 种子 / 工厂
|
||
├── docker/ ← Docker 部署文件
|
||
├── public/ ← Web 入口 + 静态资源
|
||
├── resources/ ← 生成器模板（templates/）+ Blade 视图 + Vite 资源
|
||
├── routes/ ← 路由定义（api / web / console）
|
||
├── storage/ ← 运行时产物（日志/缓存/会话，需可写）
|
||
├── tests/ ← PHPUnit 测试
|
||
├── uploads/ ← 上传文件目录
|
||
├── vendor/ ← Composer 依赖
|
||
├── document/ ← 五种数据库初始化脚本
|
||
├── artisan ← Artisan 命令行入口
|
||
└── .env ← 环境变量配置
|
||
```
|
||
|
||
## app/ 目录详解
|
||
|
||
```text
|
||
app/
|
||
├── 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 个）
|
||
```
|
||
|
||
### 各目录职责与命名规范
|
||
|
||
| 目录 | 职责 | 命名规则 | 数量 | 说明 |
|
||
|------|------|----------|------|------|
|
||
| `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 | 当前登录用户 / 统一响应 |
|
||
|
||
### 模块文件对应关系
|
||
|
||
以"用户管理"模块为例，一个完整模块包含 4 个文件：
|
||
|
||
```text
|
||
app/
|
||
├── Http/Controllers/Api/UserController.php ← HTTP 入口（路由指向这里）
|
||
├── Http/Requests/UserRequest.php ← 参数校验（规则 + 中文消息）
|
||
├── Services/UserService.php ← 业务逻辑（属性配置 + 钩子）
|
||
└── Models/User.php ← 数据模型（表映射 + Trait）
|
||
```
|
||
|
||
请求流转：`Controller → (FormRequest 校验) → Service → Model → 数据库`
|
||
|
||
### 基类与公共文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `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） |
|
||
|
||
### Services 横切服务清单
|
||
|
||
跨模块复用的无状态能力（业务 Service 之外）：
|
||
|
||
| 服务 | 文件 | 说明 |
|
||
|------|------|------|
|
||
| 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 生成器（Oracle 序列/触发器） |
|
||
| Excel | `ExcelService.php` | 导入导出（表头映射、分批） |
|
||
| 配置管理 | `ConfigService.php` | 系统配置读写与缓存 |
|
||
| 字典管理 | `DictService.php` | 字典/字典项管理 |
|
||
|
||
### Middleware 中间件清单
|
||
|
||
| 中间件 | 文件 | 别名 | 作用域 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| 真实 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]` 放行 |
|
||
|
||
### Console 命令清单
|
||
|
||
| 命令 | 文件 | 签名 | 说明 |
|
||
|------|------|------|------|
|
||
| 代码生成 | `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 配置（驼峰转换开关）★
|
||
├── 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
|
||
```
|
||
|
||
标 ★ 为本项目独立维护的配置文件（不与 Laravel 默认配置合并）。
|
||
|
||
## routes/ 路由定义
|
||
|
||
```text
|
||
routes/
|
||
├── api.php 全部 API 路由（公开接口在中间件组外）
|
||
├── web.php 欢迎页
|
||
└── console.php 调度注册
|
||
```
|
||
|
||
路由组织约定见 [3.7 路由注册](/zh/guide/route.html)。
|
||
|
||
## resources/templates/ 代码生成模板
|
||
|
||
```text
|
||
resources/templates/
|
||
├── controller.php.tpl 控制器模板
|
||
├── service.php.tpl 服务层模板
|
||
├── model.php.tpl 模型模板
|
||
├── request.php.tpl FormRequest 模板
|
||
├── ui/ 普通列表前端模板（6 个）
|
||
└── ui2/ 树形结构前端模板
|
||
```
|
||
|
||
由 `GeneratorService` 渲染，通过 CLI（`generate:code`）或 Web 界面调用。
|
||
|
||
## 前端目录设计
|
||
|
||
```text
|
||
ui/src/
|
||
├── api/ ← API 接口（按业务域分组）
|
||
├── views/ ← 页面视图（按业务域分组）
|
||
├── components/ ← 公共组件（跨页面复用）
|
||
├── store/ ← 状态管理（Pinia）
|
||
├── router/ ← 路由配置（动态路由由后端菜单驱动）
|
||
├── hooks/ ← 组合式函数
|
||
├── directives/ ← 自定义指令（v-perm 权限）
|
||
├── enums/ ← 枚举常量
|
||
├── styles/ ← 全局样式
|
||
├── utils/ ← 工具函数（http 封装）
|
||
├── layout/ ← 布局组件
|
||
├── plugins/ ← 插件
|
||
├── settings/ ← 项目配置
|
||
└── assets/ ← 静态资源
|
||
```
|
||
|
||
:::tip
|
||
前端工程位于本仓库 `ui/` 目录，代码生成器输出至 `ui/src/` 对应位置。详细结构见 [9.2 目录结构详解](/zh/frontend/directory.html)。
|
||
:::
|
||
|
||
## 前后端目录对应关系
|
||
|
||
| 后端 | 前端 | 说明 |
|
||
|------|------|------|
|
||
| `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/` | 字典 ↔ 枚举常量 |
|
||
|
||
## 设计原则
|
||
|
||
### 按职责分层
|
||
|
||
每层只做一件事，层间通过方法调用串联：
|
||
|
||
| 层 | 职责 | 不应该做 |
|
||
|----|------|----------|
|
||
| Controller | 参数注入、响应封装、注解标注 | 业务逻辑、数据库操作 |
|
||
| Request | 参数**格式**校验 | 业务规则校验 |
|
||
| Service | 业务编排、钩子处理、业务规则校验 | 直接 HTTP 交互 |
|
||
| Model | 表映射、关联关系、软删除、审计 | 复杂业务判断 |
|
||
|
||
### 按模块分组
|
||
|
||
同一业务模块的 4 个文件分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：
|
||
|
||
- 便于按职责查找（所有服务在一起）
|
||
- 便于代码生成器按模板批量生成
|
||
- 便于基类统一处理（BaseService 属性驱动 + Trait 占位覆盖）
|
||
|
||
### 文件命名规范
|
||
|
||
| 类型 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 控制器 | 大驼峰 + Controller | `ArticleController.php` |
|
||
| 请求 | 大驼峰 + Request | `ArticleRequest.php` |
|
||
| 服务 | 大驼峰 + Service | `ArticleService.php` |
|
||
| 模型 | 大驼峰（表名） | `Article.php` |
|
||
| 中间件 | 大驼峰（动词+名词） | `Authenticate.php` / `ResolveTenant.php` |
|
||
| 注解 | 大驼峰 | `Permission.php`、`OperationLog.php` |
|
||
| 命令 | 大驼峰 + Command（或动词开头） | `GeneratorCommand.php`、`ClearDictCache.php` |
|
||
| 任务 | 大驼峰 + Task | `SendSmsTask.php` |
|
||
| Trait | 动词开头 + Has/By | `HasCrudOperations.php`、`SoftDeletesByFlag.php` |
|