# 目录结构设计 本章详细说明项目目录结构设计，包括后端 `src/` 和前端 `ui/src/` 的完整目录树及各目录的设计意图。 :::tip 设计原则 目录结构遵循「按功能分组、按职责分层」的原则。后端 `src/` 按技术层次组织（config / core / common / api / modules），前端 `ui/src/` 按功能领域组织（api / views / components / store）。每个目录有明确的边界和单一职责。 ::: ## 后端目录结构 ``` 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 // 用户路由 │ ├── role.py // 角色路由 │ ├── menu.py // 菜单路由 │ ├── dept.py // 部门路由 │ ├── position.py // 岗位路由 │ ├── level.py // 职级路由 │ ├── dict.py // 字典路由 │ ├── dict_item.py // 字典项路由 │ ├── config.py // 配置路由 │ ├── config_item.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 // 常量定义 ``` ### 目录设计意图 | 目录 | 设计意图 | |:---|:---| | `config/` | 配置按功能拆分子模块，统一从 `.env` 加载，避免单一大文件 | | `core/` | 基础设施层，提供所有模块共用的基类、工具和配置。不包含业务逻辑 | | `common/middleware/` | 中间件独立于 core，职责单一，便于按需注册和测试 | | `common/utils/` | 工具函数按功能拆分，提供密码、文件、缓存等通用能力 | | `api/v1/` | 路由装配层，将所有模块的 Handler 集中注册，便于查看全量 API | | `modules/` | 业务模块层，每个模块包含 handlers + schemas + service + repository + models | | `extensions/` | 扩展注册，导出 SQLAlchemy/Redis 等单例，供全项目使用 | | `constants/` | 常量独立管理，避免硬编码散落各处 | ## 前端目录结构 ``` 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/ // 弹窗组件 │ ├── Upload/ // 上传组件 │ ├── Editor/ // 富文本编辑器 │ ├── Excel/ // Excel 导入导出 │ ├── Select/ // 选择器组件 │ ├── Cropper/ // 图片裁剪 │ ├── Qrcode/ // 二维码 │ ├── Page/ // 分页组件 │ ├── Password/ // 密码组件 │ ├── Authority/ // 权限组件 │ ├── ChinaArea/ // 中国行政区划 │ ├── Lockscreen/ // 锁屏 │ ├── CountTo/ // 数字动画 │ ├── Render/ // 自定义渲染 │ ├── Region/ // 区域选择 │ ├── TableSelect/ // 表格选择 │ ├── icon/ // 图标组件 │ ├── importFile/ // 文件导入 │ ├── numberInput/ // 数字输入 │ └── pagination/ // 分页组件 ├── store/ // 状态管理 │ ├── index.ts // Store 入口 │ └── modules/ // 状态模块 ├── router/ // 路由配置 │ ├── index.ts // 路由实例 │ └── menus/ // 菜单路由 ├── hooks/ // 组合式函数 │ ├── core/ // 核心 hooks │ ├── event/ // 事件 hooks │ ├── setting/ // 设置 hooks │ └── web/ // Web hooks ├── layout/ // 布局组件 │ └── components/ // 布局子组件 ├── directives/ // 自定义指令 ├── enums/ // 前端枚举 ├── plugins/ // 插件注册 ├── settings/ // 应用设置 ├── styles/ // 全局样式 ├── utils/ // 工具函数 │ ├── http/ // Axios 封装 │ ├── auth.ts // Token 管理 │ ├── dateUtil.ts // 日期格式化 │ ├── downloadFile.ts // 文件下载 │ ├── validate.ts // 表单校验 │ └── Storage.ts // 本地存储 └── assets/ // 静态资源 ├── icons/ // 图标 └── images/ // 图片 ``` ### 前后端目录对应关系 | 前端目录 | 后端目录 | 说明 | |:---|:---|:---| | `api/system/position.ts` | `api/v1/position.py` | API 接口定义一一对应 | | `views/system/position/` | `modules/position/` | 页面视图对应业务模块 | | `store/modules/user.ts` | `modules/auth/service.py` | 用户状态对应认证服务 | | `components/` | `common/utils/` + `core/` | 公共组件对应后端工具 | ## 目录规范 :::warning 目录命名规范 1. **后端**：目录名使用小写下划线（snake_case），与 Python 模块命名一致 2. **前端**：目录名使用小写 kebab-case 或 camelCase，与 Vue 生态习惯一致 3. **模块文件**：每个模块固定包含 `handlers.py` / `schemas.py` / `service.py` / `repository.py` / `models.py` 五个文件 4. **路由文件**：每个模块在 `api/v1/` 下对应一个路由文件，导出 `routes` 列表 ::: ## 总结 目录结构是项目可维护性的基础。后端按技术层次（config / core / common / api / modules）组织，前端按功能领域（api / views / components / store）组织。每个目录有明确的边界和单一职责，模块内部遵循固定的文件结构（handlers + schemas + service + repository + models）。这种设计使得新开发者能快速定位代码，新模块能按既定模式快速创建。