308 lines
17 KiB
Markdown
308 lines
17 KiB
Markdown
# 目录结构设计
|
||
|
||
本章详细说明项目目录结构设计，包括后端 `src/` 和前端 `ui/src/` 的完整目录树及各目录的设计意图。
|
||
|
||
:::tip 设计原则
|
||
目录结构遵循「按功能分组、按职责分层」的原则。后端 `src/` 按技术层次组织（core / middleware / api / modules），前端 `ui/src/` 按功能领域组织（api / views / components / store）。每个目录有明确的边界和单一职责。
|
||
:::
|
||
|
||
## 后端目录结构
|
||
|
||
```
|
||
src/
|
||
├── main.py # 应用入口：uvicorn 启动，加载 create_app()
|
||
├── core/ # 核心基础设施层
|
||
│ ├── app.py # 应用工厂：create_app() 组装中间件、路由、异常处理
|
||
│ ├── config/ # 配置模块（从 .env 加载）
|
||
│ │ ├── __init__.py # 加载 .env，统一导出所有配置
|
||
│ │ ├── app.py # 应用配置：DEBUG、CORS、上传限制
|
||
│ │ ├── auth.py # JWT 配置：密钥、过期时间
|
||
│ │ ├── captcha.py # 验证码配置
|
||
│ │ ├── database.py # 数据库配置：连接 URL、驱动注册、连接池
|
||
│ │ ├── email.py # 邮件配置
|
||
│ │ ├── rate_limit.py # 限流配置：开关、阈值、窗口
|
||
│ │ ├── redis.py # Redis 配置：连接参数
|
||
│ │ └── sms.py # 短信配置
|
||
│ ├── database.py # 数据库引擎：SessionLocal / _db_ctx / get_db_session()
|
||
│ ├── redis_client.py # Redis 客户端：连接池、contextvars 注入、Lua 脚本
|
||
│ ├── jwt.py # JWT 工具：签发 / 解析 / 续签 / 黑名单
|
||
│ ├── password.py # 密码工具：bcrypt 哈希 + 盐值
|
||
│ ├── security.py # 安全工具：get_user_id / get_username / get_realname
|
||
│ ├── response.py # 统一响应：R.ok() / R.failed() / R.page()
|
||
│ ├── exceptions.py # 自定义异常：AuthorizationException / BusinessException
|
||
│ ├── access_decorators.py # 访问装饰器：permission_required / check_demo
|
||
│ ├── logger.py # 日志配置：结构化日志、文件输出
|
||
│ ├── base_model.py # 模型基类：通用字段 + to_dict() 序列化
|
||
│ ├── base_db.py # 数据库操作基类：save() 持久化方法
|
||
│ ├── base_repository.py # 仓库基类：通用 CRUD + 软删除 + 分页
|
||
│ ├── base_service.py # 服务基类：模板方法 CRUD + 差异点钩子
|
||
│ └── base_schemas.py # Schema 基类：BaseForm（含可选 id 字段）
|
||
│
|
||
├── middleware/ # HTTP 中间件层
|
||
│ ├── __init__.py # 统一导出
|
||
│ ├── cors.py # CORS 跨域中间件
|
||
│ ├── rate_limit.py # 滑动窗口限流中间件
|
||
│ ├── db_session.py # 数据库会话中间件（commit/rollback）
|
||
│ ├── operation_log.py # 操作日志中间件
|
||
│ ├── upload_size_limit.py # 上传体积限制中间件
|
||
│ └── logger.py # 请求日志钩子
|
||
│
|
||
├── api/ # 路由装配层
|
||
│ ├── __init__.py # register_router：挂载 auth（免认证）+ v1（login_required）
|
||
│ ├── deps.py # login_required 依赖：JWT 解析 + Token 黑名单检查
|
||
│ └── v1/ # API v1 版本
|
||
│ ├── router.py # 中央路由注册：所有模块路由统一挂载到 v1 实例
|
||
│ └── endpoints/ # HTTP 端点层（每个模块一个文件）
|
||
│ ├── auth.py # 登录/登出/验证码/Token 刷新
|
||
│ ├── position.py # 岗位管理
|
||
│ ├── level.py # 职级管理
|
||
│ ├── dept.py # 部门管理
|
||
│ ├── role.py # 角色管理
|
||
│ ├── role_menu.py # 角色菜单分配
|
||
│ ├── menu.py # 菜单管理
|
||
│ ├── user.py # 用户管理
|
||
│ ├── user_role.py # 用户角色分配
|
||
│ ├── city.py # 城市/行政区划
|
||
│ ├── notice.py # 通知公告
|
||
│ ├── param.py # 参数管理
|
||
│ ├── category.py # 文章分类
|
||
│ ├── article.py # 文章管理
|
||
│ ├── file_template.py # 文件模板
|
||
│ ├── link.py # 友链管理
|
||
│ ├── dict.py # 字典管理
|
||
│ ├── dict_item.py # 字典项管理
|
||
│ ├── config.py # 配置管理
|
||
│ ├── config_item.py # 配置项管理
|
||
│ ├── login_log.py # 登录日志
|
||
│ ├── operation_log.py # 操作日志
|
||
│ ├── job.py # 定时任务
|
||
│ ├── job_log.py # 任务日志
|
||
│ ├── upload.py # 文件上传
|
||
│ ├── generator.py # 代码生成器
|
||
│ ├── index.py # 系统主页
|
||
│ └── example.py # 案例演示
|
||
│
|
||
├── modules/ # 业务模块层（纯业务逻辑）
|
||
│ ├── auth/ # 认证模块
|
||
│ │ ├── models.py # 登录日志模型
|
||
│ │ ├── schemas.py # 登录表单校验
|
||
│ │ └── service.py # 登录/登出/验证码/锁定逻辑
|
||
│ ├── system/ # 系统管理模块组
|
||
│ │ ├── position/ # 岗位管理
|
||
│ │ │ ├── models.py # Position 模型
|
||
│ │ │ ├── repository.py # PositionRepository + 单例
|
||
│ │ │ ├── schemas.py # PositionForm / PositionStatusForm
|
||
│ │ │ └── service.py # PositionService + 单例
|
||
│ │ ├── level/ # 职级管理（同结构）
|
||
│ │ ├── dept/ # 部门管理（支持树形）
|
||
│ │ ├── role/ # 角色管理
|
||
│ │ ├── role_menu/ # 角色菜单关联
|
||
│ │ ├── menu/ # 菜单管理（支持树形）
|
||
│ │ ├── user/ # 用户管理（复杂模块）
|
||
│ │ └── user_role/ # 用户角色关联
|
||
│ ├── dictionary/ # 字典模块组
|
||
│ │ ├── dict/ # 字典
|
||
│ │ └── dict_item/ # 字典项
|
||
│ ├── configuration/ # 配置模块组
|
||
│ │ ├── config/ # 配置
|
||
│ │ └── config_item/ # 配置项
|
||
│ ├── article/ # 文章管理
|
||
│ ├── category/ # 文章分类
|
||
│ ├── city/ # 城市/行政区划
|
||
│ ├── file_template/ # 文件模板
|
||
│ ├── link/ # 友链管理
|
||
│ ├── notice/ # 通知公告
|
||
│ ├── param/ # 参数管理
|
||
│ ├── job/ # 定时任务（含调度器）
|
||
│ ├── job_log/ # 任务执行日志
|
||
│ ├── login_log/ # 登录日志
|
||
│ ├── operation_log/ # 操作日志
|
||
│ ├── upload/ # 文件上传
|
||
│ ├── generator/ # 代码生成器
|
||
│ └── example/ # 案例演示
|
||
│
|
||
├── constants/ # 常量与枚举
|
||
│ ├── __init__.py # 统一导出
|
||
│ ├── constants.py # 通用常量：PAGE_SIZE / DEFAULT_PASSWORD / SERIALIZE_EXCLUDE_FIELDS
|
||
│ └── pagination.py # 分页参数解析
|
||
│
|
||
├── utils/ # 工具函数
|
||
│ ├── __init__.py # 重导出 R / password（向后兼容）
|
||
│ ├── request.py # 请求工具：parse_batch_ids / like_contains / parse_pagination
|
||
│ ├── string.py # 字符串工具：驼峰/下划线互转
|
||
│ ├── dict_util.py # 数据字典工具：进程内缓存 + Redis 二级缓存
|
||
│ ├── ip.py # IP 工具：客户端 IP 提取
|
||
│ ├── ip2region.py # IP 地理位置解析
|
||
│ ├── ua.py # User-Agent 解析
|
||
│ ├── rich_text.py # 富文本处理：图片迁移 + XSS 清洗
|
||
│ ├── file.py # 文件工具
|
||
│ ├── response_body.py # 响应体读取/重建（中间件用）
|
||
│ ├── captcha/ # 验证码生成
|
||
│ └── perm_cache.py # 权限缓存工具
|
||
│
|
||
├── scripts/ # 运维脚本
|
||
│ ├── init_db.py # 数据库初始化（建库 + 建表 + 灌数据）
|
||
│ └── migrate_db.py # 跨库数据迁移工具
|
||
│
|
||
└── migrations/ # Alembic 迁移
|
||
├── env.py # 迁移环境配置
|
||
└── versions/ # 迁移版本文件
|
||
└── 0001_baseline.py # 基线迁移
|
||
```
|
||
|
||
### 目录设计意图
|
||
|
||
| 目录 | 设计意图 |
|
||
|:---|:---|
|
||
| `core/` | 基础设施层，提供所有模块共用的基类、工具和配置。不包含业务逻辑 |
|
||
| `core/config/` | 配置按功能拆分子模块，统一从 `.env` 加载，避免单一大文件 |
|
||
| `middleware/` | 中间件独立于 core，职责单一，便于按需注册和测试 |
|
||
| `api/` | 路由装配层，将所有模块的 HTTP 端点集中注册，便于查看全量 API |
|
||
| `api/v1/endpoints/` | HTTP 端点层，每个模块一个文件，只做请求转发 |
|
||
| `modules/` | 业务模块层，按功能域分组（system / dictionary / configuration），每个模块包含 models + repository + schemas + service |
|
||
| `modules/{group}/` | 模块组：将关联模块归组（如 system 下的 user / role / menu / dept） |
|
||
| `constants/` | 常量与枚举独立管理，避免硬编码散落各处 |
|
||
| `utils/` | 工具函数按功能拆分，提供请求解析、字符串处理、缓存等通用能力 |
|
||
| `scripts/` | 运维脚本独立于业务代码，便于部署和维护 |
|
||
|
||
## 前端目录结构
|
||
|
||
```
|
||
ui/src/
|
||
├── main.ts # 应用入口
|
||
├── App.vue # 根组件
|
||
├── api/ # API 接口层（按后端模块对应）
|
||
│ ├── system/ # 系统管理 API
|
||
│ │ ├── position.ts # 岗位管理 API
|
||
│ │ ├── level.ts # 职级管理 API
|
||
│ │ ├── dept.ts # 部门管理 API
|
||
│ │ ├── role.ts # 角色管理 API
|
||
│ │ ├── menu.ts # 菜单管理 API
|
||
│ │ └── user.ts # 用户管理 API
|
||
│ ├── content/ # 内容管理 API
|
||
│ │ ├── article.ts # 文章管理 API
|
||
│ │ ├── category.ts # 文章分类 API
|
||
│ │ ├── notice.ts # 通知公告 API
|
||
│ │ └── link.ts # 友链管理 API
|
||
│ ├── data/ # 数据管理 API
|
||
│ │ ├── dict.ts # 字典管理 API
|
||
│ │ ├── config.ts # 配置管理 API
|
||
│ │ └── param.ts # 参数管理 API
|
||
│ ├── common/ # 公共 API
|
||
│ │ └── index.ts # 登录/登出/验证码
|
||
│ ├── dashboard/ # 仪表盘 API
|
||
│ ├── file/ # 文件管理 API
|
||
│ ├── monitor/ # 监控 API
|
||
│ ├── region/ # 行政区划 API
|
||
│ ├── setting/ # 设置 API
|
||
│ └── tool/ # 工具 API
|
||
│
|
||
├── views/ # 页面视图（按功能域分组）
|
||
│ ├── login/ # 登录页
|
||
│ ├── dashboard/ # 仪表盘
|
||
│ ├── system/ # 系统管理页面
|
||
│ │ ├── position/ # 岗位管理页面
|
||
│ │ ├── level/ # 职级管理页面
|
||
│ │ ├── dept/ # 部门管理页面
|
||
│ │ ├── role/ # 角色管理页面
|
||
│ │ ├── menu/ # 菜单管理页面
|
||
│ │ └── user/ # 用户管理页面
|
||
│ ├── content/ # 内容管理页面
|
||
│ ├── data/ # 数据管理页面
|
||
│ ├── monitor/ # 监控页面
|
||
│ ├── setting/ # 设置页面
|
||
│ ├── tool/ # 工具页面
|
||
│ ├── file/ # 文件管理页面
|
||
│ ├── exception/ # 异常页面（404/403/500）
|
||
│ ├── about/ # 关于页面
|
||
│ ├── iframe/ # 内嵌页面
|
||
│ └── redirect/ # 重定向页面
|
||
│
|
||
├── components/ # 全局公共组件
|
||
│ ├── Table/ # 表格组件
|
||
│ ├── Form/ # 表单组件
|
||
│ ├── Modal/ # 弹窗组件
|
||
│ ├── Upload/ # 上传组件
|
||
│ ├── Editor/ # 富文本编辑器
|
||
│ ├── Excel/ # Excel 导入导出
|
||
│ ├── Select/ # 选择器组件
|
||
│ ├── Cropper/ # 图片裁剪
|
||
│ ├── Qrcode/ # 二维码
|
||
│ ├── Page/ # 分页组件
|
||
│ ├── Password/ # 密码组件
|
||
│ ├── Authority/ # 权限组件
|
||
│ ├── CheckToken/ # Token 检查
|
||
│ ├── ChinaArea/ # 中国行政区划
|
||
│ ├── Websocket/ # WebSocket 组件
|
||
│ ├── Lockscreen/ # 锁屏
|
||
│ ├── CountTo/ # 数字动画
|
||
│ ├── Render/ # 自定义渲染
|
||
│ ├── Application/ # 应用组件
|
||
│ ├── Region/ # 区域选择
|
||
│ ├── TableSelect/ # 表格选择
|
||
│ ├── icon/ # 图标组件
|
||
│ ├── importFile/ # 文件导入
|
||
│ ├── numberInput/ # 数字输入
|
||
│ └── pagination/ # 分页组件
|
||
│
|
||
├── store/ # Pinia 状态管理
|
||
│ └── modules/ # 状态模块
|
||
│ ├── user.ts # 用户状态（Token/用户信息/权限）
|
||
│ ├── app.ts # 应用状态（主题/布局/语言）
|
||
│ ├── permission.ts # 权限状态（动态路由）
|
||
│ ├── tabs.ts # 标签页状态
|
||
│ └── dict.ts # 字典缓存
|
||
│
|
||
├── router/ # Vue Router 路由
|
||
│ ├── index.ts # 路由配置入口
|
||
│ └── menus/ # 菜单路由
|
||
│
|
||
├── hooks/ # Composition API Hooks
|
||
│ ├── core/ # 核心 Hooks
|
||
│ ├── event/ # 事件 Hooks
|
||
│ ├── setting/ # 设置 Hooks
|
||
│ └── web/ # Web Hooks
|
||
│
|
||
├── layout/ # 布局组件
|
||
│ └── components/ # 布局子组件（侧边栏/头部/标签页）
|
||
│
|
||
├── directives/ # 自定义指令
|
||
├── enums/ # 前端枚举
|
||
├── plugins/ # 插件
|
||
├── settings/ # 应用设置
|
||
├── styles/ # 全局样式
|
||
│ ├── theme/ # 主题样式
|
||
│ └── transition/ # 过渡动画
|
||
├── utils/ # 工具函数
|
||
│ ├── http/ # Axios 封装
|
||
│ ├── file/ # 文件工具
|
||
│ ├── helper/ # 辅助函数
|
||
│ ├── is/ # 类型判断
|
||
│ └── lib/ # 第三方库封装
|
||
└── assets/ # 静态资源
|
||
├── icons/ # 图标
|
||
└── images/ # 图片
|
||
```
|
||
|
||
### 前后端目录对应关系
|
||
|
||
| 前端目录 | 后端目录 | 说明 |
|
||
|:---|:---|:---|
|
||
| `api/system/position.ts` | `api/v1/endpoints/position.py` | API 接口定义一一对应 |
|
||
| `views/system/position/` | `modules/system/position/` | 页面视图对应业务模块 |
|
||
| `store/modules/user.ts` | `modules/auth/service.py` | 用户状态对应认证服务 |
|
||
| `components/` | `utils/` + `core/` | 公共组件对应后端工具 |
|
||
|
||
## 目录规范
|
||
|
||
:::warning 目录命名规范
|
||
1. **后端**：目录名使用小写下划线（snake_case），与 Python 模块命名一致
|
||
2. **前端**：目录名使用小写 kebab-case 或 camelCase，与 Vue 生态习惯一致
|
||
3. **模块文件**：每个模块固定包含 `models.py` / `repository.py` / `schemas.py` / `service.py` 四个文件
|
||
4. **端点文件**：每个模块对应一个端点文件，文件名与模块名一致
|
||
:::
|
||
|
||
## 总结
|
||
|
||
目录结构是项目可维护性的基础。后端按技术层次（core / middleware / api / modules）组织，前端按功能领域（api / views / components / store）组织。每个目录有明确的边界和单一职责，模块内部遵循固定的文件结构（models + repository + schemas + service）。这种设计使得新开发者能快速定位代码，新模块能按既定模式快速创建。
|