277 lines
16 KiB
Markdown
277 lines
16 KiB
Markdown
## 目录说明
|
|
|
|
在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。
|
|
|
|
```
|
|
1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。
|
|
2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。
|
|
3. 分层架构：Handler 层、Service 层、Repository 层、Model 层分离，职责清晰。
|
|
4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。
|
|
```
|
|
|
|
## 项目根目录
|
|
|
|
```
|
|
├── src/ // 后端源码
|
|
├── ui/ // 前端源码
|
|
├── document/ // 项目文档
|
|
├── migrations/ // 数据库迁移脚本
|
|
├── scripts/ // 脚本工具
|
|
├── tests/ // 测试代码
|
|
├── wiki/ // 文档站点
|
|
├── static/ // 静态资源
|
|
├── uploads/ // 上传文件目录
|
|
├── logs/ // 运行日志目录
|
|
├── app.py // 启动入口
|
|
├── .env.example // 环境变量模板
|
|
├── .env // 环境变量
|
|
├── docker-compose.yml // Docker 编排配置
|
|
├── Dockerfile // 镜像构建文件
|
|
├── Makefile // 快捷命令
|
|
├── pyproject.toml // Poetry 依赖配置
|
|
├── poetry.lock // Poetry 依赖锁定
|
|
├── alembic.ini // Alembic 配置
|
|
├── requirements.txt // Python 依赖清单
|
|
└── README.md // 项目说明
|
|
```
|
|
|
|
## 后端目录 (src/)
|
|
|
|
```
|
|
src/
|
|
├── app.py // 应用工厂
|
|
├── bootstrap.py // 启动引导
|
|
│
|
|
├── config/ // 配置模块
|
|
│ ├── __init__.py
|
|
│ ├── app.py // 应用基础配置
|
|
│ ├── auth.py // JWT 与登录安全配置
|
|
│ ├── captcha.py // 验证码配置
|
|
│ ├── database.py // 数据库配置
|
|
│ ├── email.py // 邮件配置
|
|
│ ├── logging.py // 日志配置
|
|
│ └── redis.py // Redis 配置
|
|
│
|
|
├── core/ // 核心基础设施
|
|
│ ├── __init__.py
|
|
│ ├── base_handler.py // 请求处理器基类
|
|
│ ├── base_model.py // ORM 模型基类
|
|
│ ├── base_repository.py // 通用 Repository 基类
|
|
│ ├── base_service.py // 通用 Service 基类
|
|
│ ├── base_schema.py // 通用 Schema 基类
|
|
│ ├── context.py // 上下文变量
|
|
│ ├── database.py // 数据库引擎与会话管理
|
|
│ ├── exceptions.py // 异常体系
|
|
│ ├── jwt.py // JWT 令牌处理
|
|
│ ├── logger.py // 日志配置
|
|
│ ├── metrics.py // 性能指标
|
|
│ ├── password.py // 密码加密工具
|
|
│ ├── redis.py // Redis 客户端
|
|
│ ├── response.py // 统一响应封装
|
|
│ └── tracer.py // 链路追踪
|
|
│
|
|
├── common/ // 公共模块
|
|
│ ├── __init__.py
|
|
│ ├── permission.py // 权限解析
|
|
│ ├── middleware/ // 中间件
|
|
│ │ ├── __init__.py
|
|
│ │ ├── access_decorators.py // 访问控制装饰器
|
|
│ │ ├── authentication.py // 认证中间件
|
|
│ │ ├── cors.py // 跨域处理
|
|
│ │ ├── login_log.py // 登录日志装饰器
|
|
│ │ ├── metrics.py // 请求指标中间件
|
|
│ │ ├── operation_log.py // 操作日志装饰器
|
|
│ │ └── trace_id.py // 链路追踪中间件
|
|
│ └── utils/ // 工具函数
|
|
│ ├── __init__.py
|
|
│ ├── captcha.py // 验证码工具
|
|
│ ├── crypto.py // 密码加密工具
|
|
│ ├── dict_util.py // 数据字典工具
|
|
│ ├── file.py // 文件工具
|
|
│ ├── helpers.py // 通用工具函数
|
|
│ ├── ip2region.py // IP 地理位置解析
|
|
│ ├── rich_text.py // 富文本处理
|
|
│ └── validators.py // 校验工具
|
|
│
|
|
├── modules/ // 业务模块
|
|
│ ├── __init__.py
|
|
│ ├── auth/ // 认证模块
|
|
│ ├── user/ // 用户管理
|
|
│ ├── role/ // 角色管理
|
|
│ ├── menu/ // 菜单管理
|
|
│ ├── dept/ // 部门管理
|
|
│ ├── position/ // 岗位管理
|
|
│ ├── level/ // 职级管理
|
|
│ ├── dict/ // 字典管理
|
|
│ ├── dict_item/ // 字典项管理
|
|
│ ├── config/ // 系统配置
|
|
│ ├── config_item/ // 配置项管理
|
|
│ ├── notice/ // 通知公告
|
|
│ ├── link/ // 友情链接
|
|
│ ├── category/ // 分类管理
|
|
│ ├── article/ // 文章管理
|
|
│ ├── param/ // 参数管理
|
|
│ ├── city/ // 城市级联
|
|
│ ├── file_template/ // 文件模板
|
|
│ ├── job/ // 定时任务
|
|
│ ├── job_log/ // 任务日志
|
|
│ ├── upload/ // 文件上传
|
|
│ ├── login_log/ // 登录日志
|
|
│ ├── operation_log/ // 操作日志
|
|
│ ├── user_role/ // 用户角色关联
|
|
│ ├── role_menu/ // 角色菜单关联
|
|
│ ├── example/ // 示例模块
|
|
│ └── generator/ // 代码生成器
|
|
│
|
|
├── api/ // API 路由定义
|
|
│ ├── __init__.py
|
|
│ └── v1/ // v1 版本路由
|
|
│ ├── __init__.py
|
|
│ ├── router.py // 路由聚合
|
|
│ ├── auth.py // 认证路由
|
|
│ ├── index.py // 首页路由
|
|
│ ├── upload.py // 上传路由
|
|
│ ├── user.py // 用户路由
|
|
│ ├── user_role.py // 用户角色路由
|
|
│ ├── role.py // 角色路由
|
|
│ ├── role_menu.py // 角色菜单路由
|
|
│ ├── menu.py // 菜单路由
|
|
│ ├── dept.py // 部门路由
|
|
│ ├── dict.py // 字典路由
|
|
│ ├── dict_item.py // 字典项路由
|
|
│ ├── config.py // 配置路由
|
|
│ ├── config_item.py // 配置项路由
|
|
│ ├── level.py // 职级路由
|
|
│ ├── position.py // 岗位路由
|
|
│ ├── city.py // 城市路由
|
|
│ ├── notice.py // 公告路由
|
|
│ ├── link.py // 友链路由
|
|
│ ├── category.py // 分类路由
|
|
│ ├── article.py // 文章路由
|
|
│ ├── param.py // 参数路由
|
|
│ ├── file_template.py // 文件模板路由
|
|
│ ├── job.py // 定时任务路由
|
|
│ ├── job_log.py // 任务日志路由
|
|
│ ├── generator.py // 代码生成器路由
|
|
│ ├── operation_log.py // 操作日志路由
|
|
│ ├── login_log.py // 登录日志路由
|
|
│ └── example.py // 示例路由
|
|
│
|
|
├── extensions/ // 扩展注册
|
|
│ ├── __init__.py // 扩展初始化
|
|
│ ├── sqlalchemy.py // 数据库扩展
|
|
│ ├── redis.py // Redis 扩展
|
|
│ ├── swagger.py // Swagger 占位
|
|
│ └── sentry.py // Sentry 占位
|
|
│
|
|
└── constants/ // 常量定义
|
|
└── __init__.py // 常量定义
|
|
```
|
|
|
|
## 前端目录 (ui/src/)
|
|
|
|
```
|
|
ui/src/
|
|
├── main.ts // 入口文件
|
|
├── App.vue // 根组件
|
|
├── api/ // API 接口定义
|
|
│ ├── system/ // 系统管理接口
|
|
│ ├── content/ // 内容管理接口
|
|
│ ├── data/ // 数据管理接口
|
|
│ ├── monitor/ // 监控管理接口
|
|
│ ├── tool/ // 工具接口
|
|
│ ├── file/ // 文件接口
|
|
│ ├── region/ // 地区接口
|
|
│ ├── setting/ // 设置接口
|
|
│ ├── dashboard/ // 仪表盘接口
|
|
│ └── common/ // 公共接口
|
|
├── views/ // 页面视图
|
|
│ ├── login/ // 登录页
|
|
│ ├── dashboard/ // 控制台
|
|
│ ├── system/ // 系统管理页面
|
|
│ ├── content/ // 内容管理页面
|
|
│ ├── data/ // 数据管理页面
|
|
│ ├── monitor/ // 监控管理页面
|
|
│ ├── file/ // 文件管理页面
|
|
│ ├── tool/ // 工具页面
|
|
│ ├── setting/ // 设置页面
|
|
│ ├── exception/ // 异常页面
|
|
│ └── about/ // 关于页面
|
|
├── components/ // 公共组件
|
|
│ ├── Table/ // 表格组件
|
|
│ ├── Form/ // 表单组件
|
|
│ ├── Modal/ // 弹窗组件
|
|
│ ├── Page/ // 页面容器
|
|
│ ├── Upload/ // 上传组件
|
|
│ ├── Editor/ // 富文本编辑器
|
|
│ ├── Cropper/ // 图片裁剪组件
|
|
│ ├── Qrcode/ // 二维码组件
|
|
│ ├── Excel/ // Excel 导入导出组件
|
|
│ ├── ChinaArea/ // 省市区联动组件
|
|
│ ├── TableSelect/ // 表格选择器组件
|
|
│ ├── Select/ // 下拉选择组件
|
|
│ ├── CountTo/ // 数字动画组件
|
|
│ ├── Authority/ // 权限组件
|
|
│ ├── Lockscreen/ // 锁屏组件
|
|
│ ├── Password/ // 密码强度组件
|
|
│ ├── Region/ // 区域选择组件
|
|
│ ├── numberInput/ // 数字输入组件
|
|
│ ├── priceInput/ // 价格输入组件
|
|
│ ├── pagination/ // 分页组件
|
|
│ ├── Render/ // 渲染组件
|
|
│ ├── icon/ // 图标组件
|
|
│ └── importFile/ // 文件导入组件
|
|
├── hooks/ // 组合式函数
|
|
│ ├── core/ // 核心 hooks
|
|
│ ├── event/ // 事件 hooks
|
|
│ ├── setting/ // 配置 hooks
|
|
│ ├── web/ // Web hooks
|
|
│ ├── use-async.ts // 异步请求状态管理
|
|
│ ├── useBattery.ts // 电量监听
|
|
│ ├── useDomWidth.ts // DOM 宽度监听
|
|
│ ├── useOnline.ts // 网络状态监听
|
|
│ └── useTime.ts // 时间工具
|
|
├── store/ // 状态管理
|
|
│ ├── index.ts // Store 入口
|
|
│ ├── modules/ // Store 模块
|
|
│ ├── plugins/ // Store 插件
|
|
│ └── types.ts // 类型定义
|
|
├── router/ // 路由配置
|
|
│ ├── index.ts // 路由实例
|
|
│ ├── base.ts // 静态路由
|
|
│ ├── constant.ts // 常量路由
|
|
│ ├── generator-routers.ts // 动态路由生成
|
|
│ ├── router-guards.ts // 路由守卫
|
|
│ ├── router-icons.ts // 路由图标映射
|
|
│ ├── menus/ // 菜单配置
|
|
│ └── types.ts // 类型定义
|
|
├── utils/ // 工具函数
|
|
│ ├── http/ // HTTP 请求封装
|
|
│ ├── auth.ts // Token 管理
|
|
│ ├── dateUtil.ts // 日期格式化
|
|
│ ├── downloadFile.ts // 文件下载
|
|
│ ├── validate.ts // 表单校验
|
|
│ ├── env.ts // 环境变量
|
|
│ ├── color.ts // 颜色工具
|
|
│ ├── wartermark.ts // 水印
|
|
│ ├── useLockFn.ts // 防重复提交
|
|
│ └── Storage.ts // 本地存储
|
|
├── directives/ // 自定义指令
|
|
├── plugins/ // 插件注册
|
|
├── styles/ // 全局样式
|
|
├── enums/ // 枚举定义
|
|
└── assets/ // 静态资源
|
|
├── icons/ // 图标
|
|
└── images/ // 图片
|
|
```
|
|
|
|
:::tip 注意事项
|
|
+ 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。
|
|
+ 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。
|
|
+ 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。
|
|
+ 版本控制：使用 `Git` 等版本控制工具，并在 `.gitignore` 文件中配置不需要跟踪的目录和文件。
|
|
:::
|
|
|
|
## 总结
|
|
|
|
软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 handler → service → repository → model，前端 api → views → components），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。 |