236 lines
15 KiB
Markdown
236 lines
15 KiB
Markdown
## 目录说明
|
||
|
||
在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。
|
||
|
||
```
|
||
1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。
|
||
2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。
|
||
3. 分层架构：HTTP 层、业务层、数据层分离，职责清晰。
|
||
4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。
|
||
```
|
||
|
||
## 项目根目录
|
||
|
||
```
|
||
├── src/ // 后端源码
|
||
├── ui/ // 前端源码（Vue3 + ElementPlus）
|
||
├── config/ // 配置文件（base / database / redis / auth）
|
||
├── docker/ // Docker 部署配置（Dockerfile / docker-compose.yml）
|
||
├── document/ // 项目文档（SQL脚本、迁移日志等）
|
||
├── migrations/ // Alembic 数据库迁移脚本
|
||
├── scripts/ // 脚本工具（setup_db / migrate_db 等）
|
||
├── tests/ // 测试代码（contract / unit / integration）
|
||
├── wiki/ // VitePress 文档站点
|
||
├── static/ // 静态资源（验证码字体等）
|
||
├── uploads/ // 上传文件存储目录
|
||
├── app.py // 后端启动入口
|
||
├── gunicorn.conf.py // Gunicorn 生产环境配置
|
||
├── generator.py // 代码生成器 CLI 入口
|
||
├── config.json // 代码生成器配置
|
||
├── .env.example // 环境变量模板
|
||
├── .env // 环境变量（不提交到版本控制）
|
||
├── Makefile // 快捷命令（db-init、migrate-*、db-migrate）
|
||
├── pyproject.toml // 项目元数据与工具配置
|
||
├── requirements.txt // Python 依赖清单
|
||
├── requirements-dev.txt // 开发依赖清单
|
||
├── .flake8 // Flake8 代码检查配置
|
||
├── .pre-commit-config.yaml // Pre-commit 钩子配置
|
||
├── .dockerignore // Docker 构建忽略规则
|
||
└── README.md // 项目说明
|
||
```
|
||
|
||
## 后端目录 (src/)
|
||
|
||
```
|
||
src/
|
||
├── app.py // 应用工厂（create_app()）
|
||
├── extensions.py // Flask 扩展注册
|
||
├── models_registry.py // 模型注册中心（Flask-Migrate 全量识别）
|
||
├── core/ // 核心基础设施（与业务无关）
|
||
│ ├── database.py // SQLAlchemy 引擎 / db 实例
|
||
│ ├── redis_client.py // Redis 同步客户端
|
||
│ ├── jwt.py // JWT 签发 / 解析 / 刷新 / 黑名单
|
||
│ ├── password.py // bcrypt 密码加密 / 校验
|
||
│ ├── response.py // R.ok() / R.failed() 统一响应
|
||
│ ├── exceptions.py // BizError 业务异常
|
||
│ ├── security.py // get_user_id() / get_username() / get_realname()
|
||
│ ├── permission.py // @check_permission 装饰器
|
||
│ ├── scheduler.py // 定时任务调度器管理
|
||
│ └── mail.py // 邮件发送
|
||
├── common/ // 公共组件
|
||
│ ├── base_model.py // ORM 基类（id / create_time / is_delete 等公共字段）
|
||
│ ├── base_db.py // save() / save_all() 方法（flush 不 commit）
|
||
│ ├── base_repository.py // 通用 Repository 基类（CRUD / 分页 / 软删过滤）
|
||
│ ├── base_service.py // 通用 Service 基类（模板方法 + 覆写钩子）
|
||
│ ├── forms/ // 表单校验
|
||
│ │ ├── base_form.py // BaseForm（WTForms 基类，含 ArrayField 处理）
|
||
│ │ └── fields.py // 自定义字段（ArrayField）
|
||
│ ├── constants/ // 常量定义
|
||
│ │ └── common.py // PAGE_SIZE / DEFAULT_PASSWORD 等
|
||
│ └── utils/ // 工具函数
|
||
│ ├── request.py // parse_request_body / parse_batch_ids / parse_batch_ids
|
||
│ ├── captcha.py // 验证码生成（Pillow）
|
||
│ ├── file.py // 文件工具
|
||
│ ├── ip.py // IP 地址获取
|
||
│ ├── ip2region.py // IP 地理位置解析
|
||
│ ├── user_agent.py // User-Agent 解析
|
||
│ ├── rich_text.py // 富文本 XSS 过滤 + 文件迁移
|
||
│ ├── case_converter.py // camelCase <-> snake_case 转换
|
||
│ ├── model_utils.py // model_to_dict / models_to_list
|
||
│ ├── regular.py // WTForms 错误提取
|
||
│ ├── json.py // 自定义 JSON 编码器
|
||
│ ├── excel_utils.py // Excel 导入导出工具
|
||
│ └── time_utils.py // 时间工具
|
||
├── middleware/ // 中间件
|
||
│ ├── __init__.py // 统一导出
|
||
│ ├── auth.py // 登录校验 + 白名单
|
||
│ ├── demo.py // 演示模式（@check_demo）
|
||
│ ├── transaction.py // AOP 事务拦截器
|
||
│ ├── operation_log.py // 操作日志自动记录
|
||
│ └── errors.py // 异常处理器
|
||
├── routes/ // 路由注册
|
||
│ └── v1.py // API v1 路由注册中心（BLUEPRINTS 列表）
|
||
└── modules/ // 业务模块（可插拔）
|
||
├── auth/ // 认证模块（登录/登出/验证码/刷新Token）
|
||
├── system/ // 系统管理
|
||
│ ├── user/ // 用户（models / schema / repository / service / router）
|
||
│ ├── role/ // 角色
|
||
│ ├── menu/ // 菜单
|
||
│ ├── dept/ // 部门
|
||
│ ├── position/ // 岗位
|
||
│ └── level/ // 职级
|
||
├── association/ // 关联表模块
|
||
│ ├── user_role/ // 用户-角色关联
|
||
│ └── role_menu/ // 角色-菜单关联
|
||
├── dictionary/ // 数据字典（dict / dict_item / dict_utils）
|
||
├── configuration/ // 系统配置（config / config_item）
|
||
├── cms/ // 内容管理
|
||
│ ├── article/ // 文章管理
|
||
│ ├── category/ // 分类管理
|
||
│ └── link/ // 友情链接
|
||
├── city/ // 行政区划
|
||
├── job/ // 定时任务（含 scheduler_service / executor）
|
||
├── job_log/ // 任务执行日志
|
||
├── notice/ // 通知公告
|
||
├── param/ // 参数管理
|
||
├── file_template/ // 文件模板
|
||
├── upload/ // 文件上传
|
||
├── login_log/ // 登录日志
|
||
├── operation_log/ // 操作日志
|
||
├── example/ // 示例模块
|
||
└── generator/ // 代码生成器
|
||
```
|
||
|
||
## 前端目录 (ui/src/)
|
||
|
||
```
|
||
ui/src/
|
||
├── main.ts // 入口文件（注册插件、挂载应用）
|
||
├── App.vue // 根组件
|
||
├── api/ // API 接口定义（按业务分组）
|
||
│ ├── system/ // 系统管理接口（user.ts / role.ts / menu.ts 等）
|
||
│ ├── content/ // 内容管理接口
|
||
│ ├── data/ // 数据管理接口
|
||
│ ├── monitor/ // 监控管理接口
|
||
│ ├── tool/ // 工具接口
|
||
│ ├── file/ // 文件接口
|
||
│ ├── region/ // 地区接口
|
||
│ ├── setting/ // 设置接口
|
||
│ ├── dashboard/ // 仪表盘接口
|
||
│ └── common/ // 公共接口
|
||
├── views/ // 页面视图（按业务分组）
|
||
│ ├── login/ // 登录页
|
||
│ ├── dashboard/ // 控制台
|
||
│ ├── system/ // 系统管理页面（user / role / menu / dept / position / level）
|
||
│ ├── content/ // 内容管理页面（article / category / link）
|
||
│ ├── data/ // 数据管理页面（dict / config / notice / param / city）
|
||
│ ├── monitor/ // 监控管理页面（job / job/log）
|
||
│ ├── file/ // 文件管理页面（fileTemplate）
|
||
│ ├── tool/ // 工具页面（generator / example）
|
||
│ ├── setting/ // 设置页面（profile / configWeb）
|
||
│ ├── exception/ // 异常页面（404 / 500）
|
||
│ ├── about/ // 关于页面
|
||
│ ├── iframe/ // 内嵌页面
|
||
│ └── redirect/ // 重定向页面
|
||
├── components/ // 公共组件
|
||
│ ├── Table/ // BasicTable 表格组件
|
||
│ ├── Form/ // BasicForm 表单组件
|
||
│ ├── Modal/ // Modal 弹窗组件
|
||
│ ├── Page/ // PageWrapper 页面容器
|
||
│ ├── Upload/ // 文件上传组件
|
||
│ ├── Editor/ // 富文本编辑器
|
||
│ ├── Cropper/ // 图片裁剪组件
|
||
│ ├── Qrcode/ // 二维码组件
|
||
│ ├── Excel/ // Excel 导入导出组件
|
||
│ ├── ChinaArea/ // 省市区联动组件
|
||
│ ├── TableSelect/ // 表格选择器组件
|
||
│ ├── Select/ // 下拉选择组件
|
||
│ ├── CountTo/ // 数字动画组件
|
||
│ ├── Authority/ // 权限组件
|
||
│ ├── CheckToken/ // Token 检查组件
|
||
│ ├── Application/ // 应用组件
|
||
│ ├── Websocket/ // WebSocket 组件
|
||
│ ├── 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/ // Pinia 状态管理
|
||
│ ├── index.ts // Store 入口
|
||
│ ├── modules/ // Store 模块（user / perm / dict / tabs / app）
|
||
│ ├── plugins/ // Store 插件
|
||
│ └── types.ts // 类型定义
|
||
├── router/ // 路由配置
|
||
│ ├── index.ts // 路由实例
|
||
│ ├── base.ts // 静态路由（登录 / 404）
|
||
│ ├── constant.ts // 常量路由
|
||
│ ├── generator-routers.ts // 动态路由生成（后端菜单 → Vue Router）
|
||
│ ├── router-guards.ts // 路由守卫（登录校验 / 菜单加载）
|
||
│ ├── router-icons.ts // 路由图标映射
|
||
│ ├── menus/ // 菜单配置
|
||
│ └── types.ts // 类型定义
|
||
├── utils/ // 工具函数
|
||
│ ├── http/ // HTTP 请求封装（Axios 拦截器）
|
||
│ ├── auth.ts // Token 管理 / 消息提示 / 确认对话框
|
||
│ ├── dateUtil.ts // 日期格式化
|
||
│ ├── downloadFile.ts // 文件下载
|
||
│ ├── validate.ts // 表单校验
|
||
│ ├── env.ts // 环境变量
|
||
│ ├── color.ts // 颜色工具
|
||
│ ├── wartermark.ts // 水印
|
||
│ ├── useLockFn.ts // 防重复提交
|
||
│ └── Storage.ts // 本地存储
|
||
├── directives/ // 自定义指令（v-perm 权限指令）
|
||
├── plugins/ // 插件注册（ElementPlus / 自定义组件 / 指令）
|
||
├── styles/ // 全局样式（Tailwind CSS / ElementPlus 主题覆盖）
|
||
├── enums/ // 枚举定义
|
||
└── assets/ // 静态资源
|
||
├── icons/ // 图标
|
||
└── images/ // 图片
|
||
```
|
||
|
||
:::tip 注意事项
|
||
+ 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。
|
||
+ 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。
|
||
+ 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。
|
||
+ 版本控制：使用 `Git` 等版本控制工具，并在 `.gitignore` 文件中配置不需要跟踪的目录和文件。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 router → service → repository，前端 api → views → components），结合模块化管理，是一个有效的解决方案。每个业务模块包含 models.py（模型）、schema.py（表单校验）、repository.py（数据访问）、service.py（业务逻辑）、router.py（路由控制）五个文件，职责清晰，便于维护。
|