Become a sponsor
目录结构设计
本章详细说明项目目录结构设计，包括后端 src/ 和前端 ui/src/ 的完整目录树及各目录的设计意图。
设计原则
目录结构遵循「按功能分组、按职责分层」的原则。后端 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/ | 公共组件对应后端工具 |
目录规范
目录命名规范
- 后端：目录名使用小写下划线（snake_case），与 Python 模块命名一致
- 前端：目录名使用小写 kebab-case 或 camelCase，与 Vue 生态习惯一致
- 模块文件：每个模块固定包含
handlers.py/schemas.py/service.py/repository.py/models.py五个文件 - 路由文件：每个模块在
api/v1/下对应一个路由文件，导出routes列表
总结
目录结构是项目可维护性的基础。后端按技术层次（config / core / common / api / modules）组织，前端按功能领域（api / views / components / store）组织。每个目录有明确的边界和单一职责，模块内部遵循固定的文件结构（handlers + schemas + service + repository + models）。这种设计使得新开发者能快速定位代码，新模块能按既定模式快速创建。