4.5 目录结构设计

概述

目录结构遵循"按职责分层、按模块分组"的原则。后端以 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 路由注册。

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 目录结构详解。

前后端目录对应关系

后端	前端	说明
`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`

Become a sponsor

企业级中台解决方案

企业级中台解决方案

4.5 目录结构设计 ​

后端整体结构 ​

app/ 目录详解 ​

各目录职责与命名规范 ​

模块文件对应关系 ​

基类与公共文件 ​

Services 横切服务清单 ​

Middleware 中间件清单 ​

Console 命令清单 ​

config/ 配置文件 ​

routes/ 路由定义 ​

resources/templates/ 代码生成模板 ​

前端目录设计 ​

前后端目录对应关系 ​

设计原则 ​

按职责分层 ​

按模块分组 ​

文件命名规范 ​

4.5 目录结构设计

后端整体结构

app/ 目录详解

各目录职责与命名规范

模块文件对应关系

基类与公共文件

Services 横切服务清单

Middleware 中间件清单

Console 命令清单

config/ 配置文件

routes/ 路由定义

resources/templates/ 代码生成模板

前端目录设计

前后端目录对应关系

设计原则

按职责分层

按模块分组

文件命名规范