290 lines
17 KiB
Markdown
290 lines
17 KiB
Markdown
# 1.3 目录结构
|
||
|
||
## 目录说明
|
||
|
||
在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。
|
||
|
||
```text
|
||
1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。
|
||
2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。
|
||
3. 分层架构：Controller（HTTP）、Logic（业务）、Model（数据）分离，职责清晰。
|
||
4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。
|
||
```
|
||
|
||
## 项目根目录
|
||
|
||
```text
|
||
├── app/ // 后端源码
|
||
├── ui/ // 前端源码（Vue3 + NaiveUI）
|
||
├── config/ // 配置文件
|
||
├── document/ // 项目文档（SQL脚本、开发手册等）
|
||
├── extend/ // 扩展类库
|
||
├── public/ // 公共资源（入口文件、上传目录）
|
||
├── route/ // 路由定义
|
||
├── templates/ // 代码生成模板
|
||
├── vendor/ // Composer 依赖（不提交到版本控制）
|
||
├── runtime/ // 运行时缓存（不提交到版本控制）
|
||
├── .env.example // 环境变量模板
|
||
├── .env // 环境变量（不提交到版本控制）
|
||
├── composer.json // PHP 依赖清单
|
||
├── composer.lock // 依赖锁定文件
|
||
├── think // ThinkPHP 命令行入口
|
||
└── README.md // 项目说明
|
||
```
|
||
|
||
## 后端目录 (app/)
|
||
|
||
```text
|
||
app/
|
||
├── BaseController.php // 控制器基类（统一响应、参数获取、通用CRUD）
|
||
├── BaseLogic.php // 逻辑基类（属性配置、生命周期钩子、横切处理）
|
||
├── BaseTenantLogic.php // 租户逻辑基类（继承BaseLogic，自动租户隔离）
|
||
├── BaseModel.php // 模型基类（软删除、审计字段自动写入）
|
||
├── ExceptionHandle.php // 统一异常处理（所有异常渲染为JSON）
|
||
├── common.php // 公共函数库（加密、文件处理、驼峰转换）
|
||
├── event.php // 事件定义
|
||
├── middleware.php // 全局中间件注册
|
||
├── attribute/ // PHP 8 注解
|
||
│ ├── Log.php // 操作日志注解（40种操作类型）
|
||
│ ├── Permission.php // 权限校验注解
|
||
│ └── DemoAllow.php // 演示环境放行注解
|
||
├── command/ // 命令行命令
|
||
│ ├── JobRunCommand.php // 定时任务一次性执行（配合系统 cron）
|
||
│ ├── JobDaemonCommand.php // 定时任务常驻进程（配合 supervisor）
|
||
│ ├── GeneratorCommand.php // 代码生成器 CLI
|
||
│ └── DbMigrateCommand.php // 数据库迁移工具
|
||
├── controller/ // 控制器层（HTTP 入口）
|
||
│ ├── UserController.php // 用户管理
|
||
│ ├── RoleController.php // 角色管理
|
||
│ ├── MenuController.php // 菜单管理
|
||
│ ├── DeptController.php // 部门管理
|
||
│ ├── PositionController.php // 岗位管理
|
||
│ ├── LevelController.php // 职级管理
|
||
│ ├── ArticleController.php // 文章管理
|
||
│ ├── DictController.php // 字典管理
|
||
│ ├── ConfigController.php // 配置管理
|
||
│ ├── JobController.php // 定时任务
|
||
│ ├── TenantController.php // 租户管理
|
||
│ ├── GeneratorController.php // 代码生成器
|
||
│ └── ... // 其他模块
|
||
├── logic/ // 业务逻辑层
|
||
│ ├── UserLogic.php // 用户业务逻辑
|
||
│ ├── RoleLogic.php // 角色业务逻辑
|
||
│ ├── ArticleLogic.php // 文章业务逻辑
|
||
│ ├── GeneratorLogic.php // 代码生成逻辑
|
||
│ ├── LoginLogic.php // 登录业务逻辑
|
||
│ ├── LoginLogLogic.php // 登录日志逻辑
|
||
│ ├── OperLogLogic.php // 操作日志逻辑
|
||
│ ├── IndexLogic.php // 首页/仪表盘逻辑
|
||
│ └── ... // 其他模块
|
||
├── model/ // 数据模型层
|
||
│ ├── User.php // 用户模型
|
||
│ ├── Role.php // 角色模型
|
||
│ ├── Menu.php // 菜单模型
|
||
│ ├── UserRole.php // 用户角色关联
|
||
│ ├── RoleMenu.php // 角色菜单关联
|
||
│ └── ... // 其他模型
|
||
├── validate/ // 验证器
|
||
│ ├── UserValidate.php // 用户验证
|
||
│ └── ... // 其他验证器
|
||
├── task/ // 定时任务处理器
|
||
│ ├── BaseTask.php // 任务处理器基类
|
||
│ ├── HelloWorldTask.php // 测试任务（验证 daemon 调度器）
|
||
│ └── SendSmsTask.php // 示例任务
|
||
└── service/ // 服务层（通用能力）
|
||
├── JwtService.php // JWT 认证（登录/刷新/解析）
|
||
├── PasswordService.php // 密码加密（bcrypt 双重加盐）
|
||
├── DictService.php // 字典服务（两级缓存）
|
||
├── ParamService.php // 系统参数服务
|
||
├── CaptchaService.php // 验证码服务
|
||
├── RequestInfoService.php // 请求信息解析
|
||
├── AttributeService.php // 注解读取（反射+缓存）
|
||
├── GeneratorService.php // 代码生成服务
|
||
├── ExcelService.php // Excel 导入导出
|
||
├── DbSchemaBuilder.php // 跨数据库 DDL 生成器
|
||
└── DbMigrateService.php // 跨数据库数据迁移
|
||
```
|
||
|
||
## 后端模块内部结构
|
||
|
||
每个业务模块遵循统一的文件结构：
|
||
|
||
```text
|
||
app/controller/{Name}Controller.php // HTTP 入口（注解 + 异常处理）
|
||
app/logic/{Name}Logic.php // 业务逻辑（属性配置 + 钩子）
|
||
app/model/{Name}.php // 数据模型（表映射）
|
||
app/validate/{Name}Validate.php // 验证器（字段校验规则）
|
||
```
|
||
|
||
| 文件 | 职责 | 基类 |
|
||
|------|------|------|
|
||
| Controller | 接收请求、调用 Logic、返回响应 | BaseController |
|
||
| Logic | 业务逻辑、属性配置、钩子处理 | BaseLogic / BaseTenantLogic |
|
||
| Model | 数据库表映射、关联关系 | BaseModel |
|
||
| Validate | 参数校验规则 | ThinkPHP Validate |
|
||
|
||
## 配置目录 (config/)
|
||
|
||
```text
|
||
config/
|
||
├── api.php // API 配置（驼峰转换开关）
|
||
├── app.php // 应用配置（时区/调试模式/演示模式）
|
||
├── cache.php // 缓存配置（支持 file / redis）
|
||
├── console.php // 命令行配置
|
||
├── cookie.php // Cookie 配置
|
||
├── cors.php // 跨域配置（允许来源/方法/头）
|
||
├── database.php // 数据库配置（5种数据库）
|
||
├── file.php // 文件上传配置（目录/域名/大小限制）
|
||
├── filesystem.php // 文件系统配置
|
||
├── jwt.php // JWT 配置（密钥/有效期/算法）
|
||
├── lang.php // 多语言配置
|
||
├── log.php // 日志配置
|
||
├── middleware.php // 中间件排除列表
|
||
├── route.php // 路由配置
|
||
├── session.php // Session 配置
|
||
├── tenant.php // 多租户配置（默认租户ID）
|
||
├── trace.php // 调试追踪配置
|
||
└── view.php // 视图配置
|
||
```
|
||
|
||
## 扩展目录 (extend/)
|
||
|
||
```text
|
||
extend/
|
||
├── jwt/
|
||
│ └── Jwt.php // JWT 工具类（签发/解析/刷新）
|
||
├── response/
|
||
│ └── Result.php // 统一响应类（code/ok/msg/data）
|
||
└── (无自定义扩展类)
|
||
```
|
||
|
||
## 代码生成模板 (templates/)
|
||
|
||
```text
|
||
templates/
|
||
├── controller.php.tpl // 控制器模板
|
||
├── logic.php.tpl // 业务逻辑模板
|
||
├── model.php.tpl // 模型模板
|
||
├── validate.php.tpl // 验证器模板
|
||
├── ui/ // 普通列表模板（前端文件）
|
||
│ ├── index.vue.tpl // 列表页模板
|
||
│ ├── edit.vue.tpl // 编辑弹窗模板
|
||
│ ├── detail.vue.tpl // 详情弹窗模板
|
||
│ ├── api.ts.tpl // API 接口模板
|
||
│ ├── columns.ts.tpl // 表格列定义模板
|
||
│ └── querySchemas.ts.tpl // 查询条件模板
|
||
└── ui2/ // 树形结构模板（前端文件）
|
||
```
|
||
|
||
## 前端目录 (ui/src/)
|
||
|
||
```text
|
||
ui/src/
|
||
├── main.ts // 入口文件（注册插件、挂载应用）
|
||
├── App.vue // 根组件
|
||
├── api/ // API 接口定义（按业务分组）
|
||
│ ├── system/ // 系统管理接口（user.ts / role.ts / menu.ts 等）
|
||
│ ├── content/ // 内容管理接口
|
||
│ ├── data/ // 数据管理接口
|
||
│ ├── monitor/ // 监控管理接口
|
||
│ ├── tool/ // 工具接口（example.ts / generator.ts）
|
||
│ ├── file/ // 文件接口
|
||
│ ├── region/ // 地区接口
|
||
│ ├── setting/ // 设置接口
|
||
│ ├── dashboard/ // 仪表盘接口
|
||
│ └── common/ // 公共接口（login / menu / user）
|
||
├── views/ // 页面视图（按业务分组）
|
||
│ ├── login/ // 登录页
|
||
│ ├── dashboard/ // 控制台
|
||
│ ├── system/ // 系统管理页面（user / role / menu / dept / position / level / tenant）
|
||
│ ├── content/ // 内容管理页面（article / category / link）
|
||
│ ├── data/ // 数据管理页面（dict / config / notice / param / city）
|
||
│ ├── monitor/ // 监控管理页面（job）
|
||
│ ├── file/ // 文件管理页面（fileTemplate）
|
||
│ ├── tool/ // 工具页面（generator / example）
|
||
│ ├── setting/ // 设置页面（profile / configWeb）
|
||
│ ├── iframe/ // 内嵌 iframe 页面
|
||
│ ├── redirect/ // 重定向页面
|
||
│ ├── exception/ // 异常页面（403 / 404 / 500）
|
||
│ └── about/ // 关于页面
|
||
├── components/ // 公共组件
|
||
│ ├── Table/ // BasicTable 表格组件
|
||
│ ├── Form/ // BasicForm 表单组件
|
||
│ ├── Modal/ // Modal 弹窗组件
|
||
│ ├── Page/ // PageWrapper 页面容器
|
||
│ ├── Upload/ // 文件上传组件
|
||
│ ├── Editor/ // 富文本编辑器（TinyMce）
|
||
│ ├── Cropper/ // 图片裁剪组件
|
||
│ ├── Qrcode/ // 二维码组件
|
||
│ ├── Excel/ // Excel 导入导出组件
|
||
│ ├── ChinaArea/ // 省市区联动组件
|
||
│ ├── Region/ // 区域选择组件
|
||
│ ├── Password/ // 密码强度组件
|
||
│ ├── Authority/ // 权限组件
|
||
│ ├── icon/ // 图标组件
|
||
│ └── ... // 其他组件
|
||
├── hooks/ // 组合式函数
|
||
│ ├── index.ts // hooks 统一导出
|
||
│ ├── useTime.ts // 时间 hook
|
||
│ ├── useDomWidth.ts // DOM 宽度 hook
|
||
│ ├── useOnline.ts // 网络状态 hook
|
||
│ ├── useBattery.ts // 电量 hook
|
||
│ ├── use-async.ts // 异步操作 hook
|
||
│ ├── core/ // 核心 hooks
|
||
│ ├── event/ // 事件 hooks
|
||
│ ├── setting/ // 配置 hooks
|
||
│ └── web/ // Web hooks（含权限判断）
|
||
├── store/ // Pinia 状态管理
|
||
│ └── modules/
|
||
│ ├── user.ts // 用户 Store（Token/用户信息/权限）
|
||
│ ├── asyncRoute.ts // 动态路由 Store（菜单/keep-alive）
|
||
│ ├── projectSetting.ts // 项目配置 Store
|
||
│ ├── tabsView.ts // 标签页 Store
|
||
│ ├── designSetting.ts // 设计/主题配置 Store
|
||
│ ├── lockscreen.ts // 锁屏 Store
|
||
│ └── ossConfig.ts // 云存储配置 Store
|
||
├── router/ // 路由配置
|
||
│ ├── index.ts // 路由实例
|
||
│ ├── base.ts // 静态路由（登录/404）
|
||
│ ├── generator-routers.ts // 动态路由生成（后端菜单→Vue Router）
|
||
│ ├── router-guards.ts // 路由守卫（登录校验/菜单加载）
|
||
│ └── router-icons.ts // 路由图标映射
|
||
├── utils/ // 工具函数
|
||
│ ├── http/ // HTTP 请求封装（Axios 拦截器）
|
||
│ └── Storage.ts // 本地存储封装
|
||
├── layout/ // 布局组件（侧边栏/顶栏/内容区）
|
||
├── plugins/ // 插件注册
|
||
├── settings/ // 项目配置（标题/主题/布局）
|
||
├── directives/ // 自定义指令（v-perm 权限指令）
|
||
├── styles/ // 全局样式（Tailwind CSS / 主题变量）
|
||
├── enums/ // 枚举定义（HTTP / 页面）
|
||
└── assets/ // 静态资源（图标/图片）
|
||
```
|
||
|
||
## 关键配置文件
|
||
|
||
| 文件 | 作用 |
|
||
|------|------|
|
||
| `.env` | 数据库连接、JWT 密钥、文件上传路径等环境变量 |
|
||
| `config/database.php` | 数据库配置（支持 5 种数据库） |
|
||
| `config/jwt.php` | JWT 配置（密钥/有效期/算法） |
|
||
| `config/file.php` | 文件上传配置（目录/域名/大小限制） |
|
||
| `config/cors.php` | 跨域配置（允许来源/方法/头） |
|
||
| `config/middleware.php` | 中间件排除列表 |
|
||
| `config/api.php` | API 配置（驼峰/下划线转换开关） |
|
||
| `config/cache.php` | 缓存配置（file/redis 驱动） |
|
||
| `config/tenant.php` | 多租户配置（默认租户ID） |
|
||
| `ui/.env.development` | 前端开发环境配置（API 代理地址） |
|
||
| `ui/vite.config.ts` | Vite 构建配置 |
|
||
| `ui/package.json` | 前端依赖和脚本命令 |
|
||
|
||
:::tip 注意事项
|
||
+ 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。
|
||
+ 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。
|
||
+ 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。
|
||
+ 版本控制：使用 `Git` 等版本控制工具，并在 `.gitignore` 文件中配置不需要跟踪的目录和文件。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 Controller → Logic → Model，前端 api → views → components），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。 |