# 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` |