4.5 目录结构设计

概述

目录结构遵循"按职责分层、按模块分组"的原则。后端以 app/ 为核心，按 Controller → Logic → Model → Validate 四层组织；前端以 src/ 为核心，按 API → Views → Store 分层。两侧通过路由和 API 接口对接。

后端整体结构

text

项目根目录/
├── app/                    ← 应用代码（核心）
├── config/                 ← 配置文件
├── extend/                 ← 扩展类库（非 Composer）
├── public/                 ← Web 入口 + 静态资源
├── route/                  ← 路由定义
├── templates/              ← 代码生成器模板
├── runtime/                ← 运行时缓存（自动生成）
├── vendor/                 ← Composer 依赖
├── wiki/                   ← 文档站点（VitePress）
├── document/               ← 开发参考手册（txt）
├── .env                    ← 环境变量配置
└── think                   ← ThinkPHP 命令行入口

app/ 目录详解

text

app/
├── BaseController.php        控制器基类
├── BaseModel.php             模型基类
├── BaseLogic.php             业务逻辑基类（系统共享模块）
├── BaseTenantLogic.php       租户逻辑基类（租户隔离模块）
├── ExceptionHandle.php       统一异常处理（JSON 响应）
├── Request.php               请求类扩展
├── common.php                公共函数库
├── event.php                 事件定义
├── middleware.php             全局中间件注册
│
├── controller/               控制器层（28 个）
├── logic/                    业务逻辑层（26 个）
├── model/                    数据模型层（25 个）
├── validate/                 验证器（21 个）
├── service/                  通用服务层（11 个）
├── middleware/               中间件（5 个）
├── attribute/                注解定义（3 个）
├── command/                  命令行命令（4 个）
└── task/                     定时任务处理器（3 个）

各目录职责与命名规范

目录	职责	命名规则	数量	说明
`controller/`	HTTP 请求入口	`{Module}Controller.php`	28	一个模块一个文件，注解标注权限和日志
`logic/`	业务逻辑	`{Module}Logic.php`	26	属性配置 + 生命周期钩子，核心业务层
`model/`	数据库映射	`{TableName}.php`（大驼峰）	25	继承 BaseModel，获软删除 + 审计字段
`validate/`	参数校验	`{Module}Validate.php`	21	定义规则 + 场景，Logic 层自动调用
`service/`	通用服务	`{Name}Service.php`	11	跨模块复用的无状态工具类
`middleware/`	中间件	`{Name}Middleware.php`	5	请求拦截：认证、租户、日志等
`attribute/`	注解类	`{Name}.php`	3	PHP 8 注解：Log、Permission、DemoAllow
`command/`	命令行	`{Name}Command.php`	4	CLI 命令：定时任务、代码生成、迁移
`task/`	任务处理器	`{Name}Task.php`	3	定时任务的具体执行逻辑

模块文件对应关系

以"用户管理"模块为例，一个完整模块包含 4 个文件：

text

app/
├── controller/UserController.php    ← HTTP 入口（路由指向这里）
├── logic/UserLogic.php              ← 业务逻辑（属性配置 + 钩子）
├── model/User.php                   ← 数据模型（表映射）
└── validate/UserValidate.php        ← 参数校验（规则 + 场景）

请求流转：Controller → Logic → Model → 数据库

基类与公共文件

文件	说明
`BaseController.php`	控制器基类：统一响应、参数获取、通用 CRUD 快捷方法
`BaseLogic.php`	逻辑基类：声明式 CRUD、生命周期钩子、自动参数校验、文件/富文本/枚举/权限/租户处理
`BaseTenantLogic.php`	租户逻辑基类：继承 BaseLogic，自动启用 `tenant_id` 隔离
`BaseModel.php`	模型基类：软删除（`is_delete`）、审计字段自动写入
`ExceptionHandle.php`	异常处理：所有异常统一渲染为 JSON 响应
`common.php`	公共函数：字符串处理、加密、文件操作、驼峰转换等
`event.php`	事件定义：全局事件监听
`middleware.php`	全局中间件注册：CORS 等

service/ 服务层清单

服务层提供跨模块复用的无状态能力，按单一职责拆分：

服务	文件	说明
JWT 认证	`JwtService.php`	登录、刷新、解析 Token
密码加密	`PasswordService.php`	bcrypt 双重加盐
字典服务	`DictService.php`	字典缓存与查询（两级缓存）
系统参数	`ParamService.php`	系统参数服务（两级缓存）
验证码	`CaptchaService.php`	图片验证码生成与校验
请求信息	`RequestInfoService.php`	客户端 IP、UA、归属地解析
注解读取	`AttributeService.php`	PHP 8 注解反射读取 + 缓存
代码生成	`GeneratorService.php`	根据数据库表生成 CRUD 代码
数据库迁移	`DbMigrateService.php`	跨数据库迁移引擎
DDL 生成	`DbSchemaBuilder.php`	跨库类型映射的 DDL 生成器
Excel	`ExcelService.php`	导入导出（支持大数据量分批）

middleware/ 中间件清单

中间件	文件	作用域	说明
跨域	`CorsMiddleware.php`	全局	CORS 头设置
认证权限	`AuthMiddleware.php`	路由级	JWT 校验 + 权限校验
租户上下文	`TenantMiddleware.php`	路由级	解析注入 tenantId
演示环境	`DemoMiddleware.php`	路由级	演示环境写操作拦截
操作日志	`LogMiddleware.php`	路由级	基于注解记录操作日志

command/ 命令行清单

命令	文件	说明
定时任务执行	`JobRunCommand.php`	执行一次定时任务
定时任务守护	`JobDaemonCommand.php`	常驻进程循环扫描执行
代码生成	`GeneratorCommand.php`	CLI 方式生成 CRUD 代码
数据库迁移	`DbMigrateCommand.php`	跨数据库迁移 CLI 工具

config/ 配置文件

text

config/
├── api.php                   API 配置（驼峰转换开关）
├── app.php                   应用配置（调试模式、异常处理）
├── cache.php                 缓存配置（支持 Redis）
├── console.php               命令行配置
├── cors.php                  跨域配置
├── database.php              数据库配置
├── file.php                  文件上传配置（域名、大小限制）
├── jwt.php                   JWT 配置（密钥、过期时间）
├── middleware.php            中间件排除列表
└── route.php                 路由配置

配置文件	关键配置项	说明
`api.php`	`camel_snake_convert`	驼峰/下划线自动转换开关
`database.php`	`type` / `hostname` / `database`	数据库连接（支持 MySQL/PG/SqlServer/Oracle/SQLite）
`file.php`	`domain_url` / `max_size`	文件上传域名和大小限制
`jwt.php`	`secret` / `access_ttl` / `refresh_ttl`	JWT 密钥和令牌有效期
`cache.php`	`type` / `host`	缓存驱动（file/redis）

extend/ 扩展类库

存放不通过 Composer 管理的自定义类库，按 PSR-4 自动加载：

text

extend/
├── jwt/
│   └── Jwt.php               JWT 工具类（封装 firebase/php-jwt）
├── response/
│   └── Result.php            统一响应类（success/fail/page 等）
└── (无自定义扩展类)

使用方式：直接通过命名空间引用，如 \response\Result::success()、\jwt\Jwt::getTokenFromHeader()。

route/ 路由定义

text

route/
└── app.php                   应用路由定义（所有 API 路由）

路由按模块分组，示例：

php

// 公开接口（无需认证）
Route::group('login', function () {
    Route::post('login', 'LoginController/login');
    Route::get('captcha', 'LoginController/captcha');
});

// 需认证接口（AuthMiddleware）
Route::group('article', function () {
    Route::get('page', 'ArticleController/page');
    Route::post('add', 'ArticleController/add');
    Route::put('update', 'ArticleController/update');
    Route::delete('delete/:id', 'ArticleController/delete');
})->middleware(AuthMiddleware::class);

templates/ 代码生成模板

text

templates/
├── controller.php.tpl        控制器模板
├── logic.php.tpl             业务逻辑模板
├── model.php.tpl             模型模板
├── validate.php.tpl          验证器模板
├── ui/                       普通列表前端模板
└── ui2/                      树形结构前端模板

由 GeneratorService 渲染，通过代码生成器 CLI 或 API 调用。

前端目录设计

text

ui/src/
├── api/            ← API 接口（按业务域分组）
├── views/          ← 页面视图（按业务域分组）
├── components/     ← 公共组件（跨页面复用）
├── store/          ← 状态管理（Pinia）
├── router/         ← 路由配置
├── hooks/          ← 组合式函数
├── directives/     ← 自定义指令
├── enums/          ← 枚举常量
├── styles/         ← 全局样式
├── utils/          ← 工具函数
├── layout/         ← 布局组件
├── plugins/        ← 插件
├── settings/       ← 项目配置
└── assets/         ← 静态资源

前后端目录对应关系

后端	前端	说明
`app/controller/UserController.php`	`src/api/system/user.ts`	API 接口函数
`app/logic/UserLogic.php`	`src/views/system/user/`	业务页面
`app/model/User.php`	—	前端不直接操作模型
`app/validate/UserValidate.php`	—	前端校验由表单组件处理
`route/app.php`	`src/api/*/.ts`	路由 ↔ API 函数映射
`config/dict*.php`	`src/enums/`	字典 ↔ 枚举常量

设计原则

按职责分层

每层只做一件事，层间通过方法调用串联：

层	职责	不应该做
Controller	参数获取、响应封装、注解标注	业务逻辑、数据库操作
Logic	业务编排、钩子处理、校验	直接 HTTP 交互
Model	表映射、关联关系、软删除	复杂业务判断
Validate	参数格式校验	业务规则校验

按模块分组

同一业务模块的 4 个文件（Controller / Logic / Model / Validate）分散在各自目录中，通过命名前缀关联。这种"水平分层 + 垂直命名"的方式：

便于按职责查找（所有控制器在一起）
便于代码生成器按模板批量生成
便于基类统一处理（如 BaseLogic 的属性驱动）

文件命名规范

类型	规范	示例
控制器	大驼峰 + Controller	`ArticleController.php`
逻辑层	大驼峰 + Logic	`ArticleLogic.php`
模型	大驼峰（表名）	`Article.php`
验证器	大驼峰 + Validate	`ArticleValidate.php`
服务	大驼峰 + Service	`DictService.php`
中间件	大驼峰 + Middleware	`AuthMiddleware.php`
注解	大驼峰	`Log.php`、`Permission.php`
命令	大驼峰 + Command	`GeneratorCommand.php`
任务	大驼峰 + Task	`SendSmsTask.php`

Become a sponsor

企业级中台解决方案

企业级中台解决方案

4.5 目录结构设计 ​

后端整体结构 ​

app/ 目录详解 ​

各目录职责与命名规范 ​

模块文件对应关系 ​

基类与公共文件 ​

service/ 服务层清单 ​

middleware/ 中间件清单 ​

command/ 命令行清单 ​

config/ 配置文件 ​

extend/ 扩展类库 ​

route/ 路由定义 ​

templates/ 代码生成模板 ​

前端目录设计 ​

前后端目录对应关系 ​

设计原则 ​

按职责分层 ​

按模块分组 ​

文件命名规范 ​

4.5 目录结构设计

后端整体结构

app/ 目录详解

各目录职责与命名规范

模块文件对应关系

基类与公共文件

service/ 服务层清单

middleware/ 中间件清单

command/ 命令行清单

config/ 配置文件

extend/ 扩展类库

route/ 路由定义

templates/ 代码生成模板

前端目录设计

前后端目录对应关系

设计原则

按职责分层

按模块分组

文件命名规范