12 KiB
12 KiB
4.5 目录结构设计
:::tip 概述
目录结构遵循"按职责分层、按模块分组"的原则。后端以 app/ 为核心，按 Controller → Request → Service → Model 四层组织；前端以 src/ 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。
:::
后端整体结构
项目根目录/
├── 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/ 目录详解
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 个文件：
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/ 配置文件
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/ 路由定义
routes/
├── api.php 全部 API 路由（公开接口在中间件组外）
├── web.php 欢迎页
└── console.php 调度注册
路由组织约定见 3.7 路由注册。
resources/templates/ 代码生成模板
resources/templates/
├── controller.php.tpl 控制器模板
├── service.php.tpl 服务层模板
├── model.php.tpl 模型模板
├── request.php.tpl FormRequest 模板
├── ui/ 普通列表前端模板（6 个）
└── ui2/ 树形结构前端模板
由 GeneratorService 渲染，通过 CLI（generate:code）或 Web 界面调用。
前端目录设计
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 目录结构详解。
:::
前后端目录对应关系
| 后端 | 前端 | 说明 |
|---|---|---|
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 |