# 1.3 目录结构 ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 ```text 1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。 2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。 3. 分层架构：Controller（HTTP）、Logic（业务）、Model（数据）分离，职责清晰。 4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。 ``` ## 项目根目录 ```text ├── app/ // 后端源码 ├── ui/ // 前端源码（Vue3 + ElementPlus） ├── config/ // 配置文件 ├── document/ // 项目文档（SQL脚本、开发手册等） ├── extend/ // 扩展类库 ├── public/ // 公共资源（入口文件、上传目录） ├── route/ // 路由定义 ├── templates/ // 代码生成模板 ├── wiki/ // VitePress 文档站点 ├── 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），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。