## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 ``` 1. 清晰的层次结构：按照功能模块划分目录，方便团队成员快速定位代码。 2. 模块化管理：通过多模块结构，实现功能模块的独立管理，提高系统的可维护性和扩展性。 3. 分层架构：HTTP 层、业务层、数据层分离，职责清晰。 4. 提升开发效率：清晰的目录结构和模块划分，减少查找代码的时间，提高开发效率。 ``` ## 项目根目录 ``` ├── src/ // 后端源码 ├── ui/ // 前端源码（Vue3 + AntDesign Vue） ├── document/ // 项目文档（SQL脚本、迁移日志等） ├── migrations/ // Alembic 数据库迁移脚本 ├── scripts/ // 脚本工具（init_db、migrate_db、seed 等） ├── tests/ // 测试代码（contract / unit / integration） ├── deploy/ // 部署配置（nginx.conf、supervisor.conf） ├── wiki/ // VitePress 文档站点 ├── static/ // 静态资源（验证码字体等） ├── .env.example // 环境变量模板 ├── .env // 环境变量（不提交到版本控制） ├── docker-compose.yml // Docker 编排配置 ├── Dockerfile // 后端镜像构建文件 ├── Makefile // 快捷命令（db-init、migrate-*、db-migrate） ├── requirements.txt // Python 依赖清单 ├── alembic.ini // Alembic 配置 └── README.md // 项目说明 ``` ## 后端目录 (src/) ``` src/ ├── main.py // 应用入口（uvicorn 启动） ├── core/ // 核心基础设施（与业务无关） │ ├── app.py // create_app 工厂函数 + lifespan │ ├── config/ // 配置模块 │ │ ├── __init__.py // 加载 .env，统一导出 │ │ ├── app.py // 应用配置（名称/版本/端口/调试模式） │ │ ├── database.py // 数据库配置（驱动/连接池/方言注册） │ │ ├── redis.py // Redis 配置 │ │ ├── auth.py // JWT 配密钥/过期时间 │ │ ├── captcha.py // 验证码配置 │ │ ├── email.py // 邮件配置 │ │ └── sms.py // 短信配置 │ ├── database.py // 引擎 / SessionLocal / contextvars / get_db_session() │ ├── redis_client.py // Redis 异步客户端 / get_redis() │ ├── jwt.py // JWT 签发 / 解析 / 刷新 / 黑名单 │ ├── password.py // bcrypt 密码加密 / 校验 │ ├── response.py // R.ok() / R.failed() 统一响应 │ ├── exceptions.py // BusinessException / AuthorizationException │ ├── security.py // get_user_id() / get_username() │ ├── access_decorators.py // @permission_required / @check_demo │ ├── logger.py // 结构化日志配置 │ ├── base_model.py // ORM 基类（id / create_time / is_delete 等公共字段） │ ├── base_db.py // save() / delete() 方法 │ ├── base_repository.py // 通用 Repository 基类（CRUD / 分页 / 软删过滤） │ ├── base_service.py // 通用 Service 基类（声明差异 + 覆盖钩子） │ └── base_schemas.py // 通用 Schema 基类（BaseForm 含 id 字段） ├── api/ // 路由层 │ ├── __init__.py // register_router：统一挂载路由到 /api/v1 │ ├── deps.py // login_required 认证依赖 │ └── v1/ │ ├── router.py // 路由注册中心（include_router + prefix + tags） │ └── endpoints/ // 各模块 Endpoint（HTTP 层） │ ├── user.py // 用户管理 │ ├── role.py // 角色管理 │ ├── menu.py // 菜单管理 │ ├── position.py // 岗位管理 │ ├── level.py // 职级管理 │ ├── dept.py // 部门管理 │ ├── article.py // 文章管理 │ ├── notice.py // 公告管理 │ ├── job.py // 定时任务 │ ├── upload.py // 文件上传 │ └── ... // 其他模块 ├── modules/ // 业务模块（可插拔） │ ├── auth/ // 认证模块（登录/登出/验证码/刷新Token） │ ├── system/ // 系统管理 │ │ ├── user/ // 用户（models / schemas / repository / service） │ │ ├── role/ // 角色 │ │ ├── menu/ // 菜单 │ │ ├── dept/ // 部门 │ │ ├── position/ // 岗位 │ │ ├── level/ // 职级 │ │ ├── user_role/ // 用户-角色关联 │ │ └── role_menu/ // 角色-菜单关联 │ ├── dictionary/ // 数据字典（dict / dict_item） │ ├── configuration/ // 系统配置（config / config_item） │ ├── article/ // 文章管理 │ ├── category/ // 分类管理 │ ├── notice/ // 公告管理 │ ├── link/ // 友情链接 │ ├── city/ // 城市级联 │ ├── job/ // 定时任务（job / job_log / job_executor） │ ├── param/ // 参数管理 │ ├── upload/ // 文件上传 │ ├── login_log/ // 登录日志 │ ├── operation_log/ // 操作日志 │ └── generator/ // 代码生成器（含 templates/ui、templates/ui2 模板） ├── middleware/ // 中间件 │ ├── cors.py // CORS 跨域处理 │ ├── rate_limit.py // Redis 滑动窗口限流 │ ├── db_session.py // 请求级 DB Session（自动 commit/rollback） │ ├── operation_log.py // 操作日志自动记录 │ ├── upload_size_limit.py // 上传文件大小限制 │ └── logger.py // 请求日志钩子 ├── utils/ // 工具函数 │ ├── request.py // parse_batch_ids / like_escape / parse_id_list │ ├── captcha.py // 验证码生成（Pillow） │ ├── file.py // 文件工具 │ ├── ip2region.py // IP 地理位置解析 │ ├── ip2region.xdb // 离线 IP 数据库 │ ├── ua.py // User-Agent 解析 │ ├── rich_text.py // 富文本 XSS 过滤 │ ├── dict_util.py // 数据字典进程内缓存 │ ├── perm_cache.py // 权限列表 Redis 缓存 │ ├── string.py // 字符串工具 │ └── response_body.py // 响应体工具 └── constants/ // 常量与枚举 ├── constants.py // PAGE_SIZE / DEFAULT_PASSWORD / SERIALIZE_EXCLUDE_FIELDS └── pagination.py // 分页参数 ``` ## 前端目录 (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/ // 关于页面 ├── components/ // 公共组件 │ ├── Table/ // BasicTable 表格组件 │ ├── Form/ // BasicForm 表单组件 │ ├── Modal/ // Modal 弹窗组件 │ ├── Page/ // PageWrapper 页面容器 │ ├── 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/ // 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/ // 插件注册（AntDesign Vue / 自定义组件 / 指令） ├── styles/ // 全局样式（Tailwind CSS / AntDesign Vue 主题覆盖） ├── enums/ // 枚举定义 └── assets/ // 静态资源 ├── icons/ // 图标 └── images/ // 图片 ``` :::tip 注意事项 + 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。 + 合理划分模块：根据项目的实际需求，合理划分功能模块，避免过度模块化。 + 文档记录：在项目文档中详细说明目录结构和各模块的功能，便于新成员快速上手。 + 版本控制：使用 `Git` 等版本控制工具，并在 `.gitignore` 文件中配置不需要跟踪的目录和文件。 ::: ## 总结 软件架构的目录结构是项目开发和维护的基础，直接影响到项目的可维护性、可扩展性和开发效率。采用分层的目录结构（后端 endpoint → service → repository，前端 api → views → components），结合模块化管理，是一个有效的解决方案。通过合理规划和遵循最佳实践，可以确保项目的结构清晰、功能明确，为团队开发和长期维护打下坚实的基础。