# BladeX 框架架构说明 ## 一、架构概览 本项目基于 **BladeX 4.0.1 企业级框架**，采用混合式架构设计，包含： - 分层架构（common 通用层） - 模块化架构（modules 业务模块） - DDD 思想（pojo/entity/dto/vo 分离） ## 二、目录结构对比 ### 传统 Spring Boot 项目（清晰简单） ``` src/main/java/com/company/project/ ├── controller/ # 所有控制器 ├── service/ # 所有服务 │ └── impl/ ├── mapper/dao/ # 所有数据访问 ├── entity/model/ # 所有实体 ├── dto/ # 所有DTO ├── vo/ # 所有VO ├── config/ # 配置类 ├── util/ # 工具类 └── constant/ # 常量 ``` **特点**：按技术层级分包，结构扁平，一目了然 --- ### BladeX 项目（复杂混合） ``` src/main/java/org/springblade/ ├── Application.java # 主启动类 │ ├── common/ # 通用层（横向关注点） │ ├── cache/ # 缓存工具（UserCache、DictCache等） │ ├── config/ # 全局配置（Swagger、Blade核心配置等） │ ├── constant/ # 全局常量（CommonConstant、DictConstant等） │ ├── enums/ # 通用枚举 │ ├── event/ # 事件监听器（日志监听等） │ ├── filter/ # 全局过滤器 │ ├── handler/ # 全局处理器 │ ├── launch/ # 启动相关 │ └── utils/ # 通用工具类 │ ├── job/ # 定时任务模块（独立） │ ├── controller/ # 任务管理API │ ├── mapper/ # 任务数据访问 │ ├── pojo/ # 任务数据对象 │ │ ├── entity/ # JobInfo, JobServer │ │ ├── dto/ │ │ └── vo/ │ ├── processor/ # 任务处理器（实际执行逻辑） │ └── service/ # 任务业务逻辑 │ └── modules/ # 业务模块（核心业务） ├── auth/ # 认证授权模块 │ ├── config/ # 认证配置 │ ├── constant/ # 认证常量 │ ├── granter/ # Token授权器（多种登录方式） │ ├── handler/ # 认证处理器 │ ├── provider/ # 认证提供者 │ ├── service/ # 认证服务 │ └── utils/ # 认证工具 │ ├── system/ # 系统管理模块 │ ├── controller/ # 用户、角色、菜单、部门等API │ ├── mapper/ # 数据访问层 │ ├── pojo/ │ │ ├── entity/ # 系统实体（User、Role、Menu等） │ │ ├── dto/ # 数据传输对象 │ │ └── vo/ # 视图对象 │ ├── service/ # 系统业务逻辑 │ ├── excel/ # Excel导入导出 │ ├── rule/ # 业务规则 │ └── wrapper/ # 数据包装器 │ ├── resource/ # 资源管理模块 │ ├── controller/ # 附件、OSS、SMS API │ ├── mapper/ │ ├── pojo/ │ ├── service/ │ ├── builder/ # OSS构建器（支持多云存储） │ ├── config/ # 资源配置 │ ├── endpoint/ # 端点 │ ├── rule/ # 规则 │ └── utils/ # 资源工具 │ ├── desk/ # 工作台模块 │ ├── controller/ # 仪表盘、通知API │ ├── mapper/ │ ├── pojo/ │ ├── service/ │ └── wrapper/ │ ├── develop/ # 开发工具模块 │ ├── controller/ # 代码生成、数据源管理API │ ├── mapper/ │ ├── pojo/ │ └── service/ │ └── martial/ # 武术比赛模块（主业务）⭐ ├── controller/ # 比赛业务API ├── mapper/ # 数据访问层 ├── pojo/ │ ├── entity/ # 9个核心实体 │ │ ├── Competition.java # 赛事 │ │ ├── Athlete.java # 运动员 │ │ ├── Judge.java # 裁判 │ │ ├── Project.java # 项目 │ │ ├── Schedule.java # 赛程 │ │ ├── Venue.java # 场馆 │ │ ├── Score.java # 评分 │ │ ├── Result.java # 成绩 │ │ └── RegistrationOrder.java # 报名订单 │ ├── dto/ │ └── vo/ └── service/ ``` ## 三、架构特点分析 ### ✅ 优点 1. **功能全面** - 内置认证授权、权限管理、多租户、OSS、SMS等 - 开箱即用，快速开发 2. **模块独立** - 每个 module 相对独立，可单独开发 - 便于团队分工协作 3. **高度封装** - 框架提供大量基础功能 - 减少重复代码 ### ⚠️ 缺点（为什么感觉"乱"） #### 1. **职责边界模糊** ``` ❓ common 和 modules 的边界不清 - common/config vs modules/auth/config - common/utils vs modules/resource/utils 什么应该放 common？ ✅ 真正通用的、跨模块的（如：DateUtil、StringUtil） ❌ 某个模块专用的（应该放模块内部） ``` #### 2. **结构不统一** ``` ❓ modules 下各模块结构不一致 auth 模块： system 模块： ├── config/ ├── controller/ ├── granter/ ├── mapper/ ├── service/ ├── pojo/ └── utils/ │ ├── entity/ │ ├── dto/ martial 模块： │ └── vo/ ├── controller/ ├── service/ ├── mapper/ ├── excel/ ├── pojo/ └── wrapper/ │ ├── entity/ │ ├── dto/ │ └── vo/ └── service/ 为什么不统一？ - auth 没有 pojo 目录（因为它不直接操作数据库表） - system 有 excel/wrapper（因为需要导入导出） - martial 结构最标准（因为是典型CRUD业务） ``` #### 3. **多余层级** ``` ❓ 为什么要多一层 pojo？ 传统做法： modules/martial/entity/Competition.java modules/martial/dto/CompetitionDTO.java BladeX 做法： modules/martial/pojo/entity/Competition.java modules/martial/pojo/dto/CompetitionDTO.java 原因：DDD 思想中，pojo 代表"领域对象"的总称 但实际上增加了复杂度，没有明显好处 ``` #### 4. **job 模块孤立** ``` ❓ 为什么 job 不在 modules 里？ 既然有 modules，job 应该是： modules/job/ ├── controller/ └── ... 而不是单独拿出来，破坏了统一性 ``` ## 四、架构设计理念分析 BladeX 混合了多种架构理念： ### 1. 分层架构（Layered Architecture） ``` common 层 → 为所有模块提供通用功能 ``` **目的**：代码复用 **问题**：边界不清，什么都往 common 塞 ### 2. 模块化架构（Modular Architecture） ``` modules/ → 按业务领域划分模块 ``` **目的**：业务隔离，独立演进 **问题**：模块结构不统一 ### 3. DDD 思想（Domain-Driven Design） ``` pojo/entity/ → 实体 pojo/dto/ → 数据传输对象 pojo/vo/ → 视图对象 ``` **目的**：分离关注点，清晰职责 **问题**：层级过多，不够彻底（缺少聚合根、值对象等核心概念） ### 4. 微服务思想（部分） ``` 每个 module 独立：controller + service + mapper + pojo ``` **目的**：为将来拆分成微服务做准备 **问题**：单体架构下过度设计 ## 五、为什么会这样设计？ ### 商业框架的通病 BladeX 是一个**商业企业级框架**，它的设计目标是： 1. **功能全面** → 覆盖各种场景 2. **快速开发** → 内置大量模板代码 3. **灵活扩展** → 支持多种架构演进 但这导致： - ✅ 功能多 → ❌ 结构复杂 - ✅ 封装好 → ❌ 理解成本高 - ✅ 可扩展 → ❌ 过度设计 ### 类比：豪华汽车 vs 普通汽车 ``` 传统 Spring Boot 项目 = 普通家用车 - 结构简单，容易理解 - 功能够用，性价比高 - 维护方便 BladeX 框架 = 豪华商务车 - 功能丰富，配置复杂 - 适合企业场景 - 需要专业维护 ``` ## 六、如何理解这个架构？ ### 思维模型：三层金字塔 ``` ┌──────────────┐ │ modules │ 业务层（核心） │ 业务模块 │ - 专注业务逻辑 └──────────────┘ - 模块独立 ▲ │ ┌──────────────┐ │ job │ 功能层（辅助） │ 定时任务 │ - 定时调度 └──────────────┘ - 后台任务 ▲ │ ┌──────────────┐ │ common │ 基础层（通用） │ 通用工具 │ - 工具类 └──────────────┘ - 配置 - 常量 ``` ### 核心原则 1. **common** = 真正通用的、跨模块的 2. **modules** = 业务核心，模块独立 3. **job** = 定时任务的特殊模块 ## 七、与标准架构的映射 如果你熟悉传统架构，可以这样理解： | BladeX 架构 | 传统架构 | 说明 | |------------|---------|------| | `common/utils/` | `util/` | 工具类 | | `common/constant/` | `constant/` | 常量 | | `common/config/` | `config/` | 配置 | | `modules/martial/controller/` | `controller/` | 控制器 | | `modules/martial/service/` | `service/` | 服务 | | `modules/martial/mapper/` | `mapper/` | 数据访问 | | `modules/martial/pojo/entity/` | `entity/` | 实体（多了pojo层） | | `modules/martial/pojo/dto/` | `dto/` | DTO（多了pojo层） | | `modules/martial/pojo/vo/` | `vo/` | VO（多了pojo层） | **关键差异**： - ✅ 传统：一个 `entity/` 目录 - ❌ BladeX：`modules/martial/pojo/entity/`（多两层） ## 八、实际开发时如何思考？ ### 场景1：我要加个工具类 ```java ❓ 放哪里？ 问：这个工具类是给多个模块用的吗？ ✅ 是 → common/utils/XxxUtil.java ❌ 否 → modules/martial/utils/XxxUtil.java（在模块内部创建utils目录） ``` ### 场景2：我要加个实体类 ```java ❓ 放哪里？ 固定位置： modules/martial/pojo/entity/Xxx.java （虽然多了pojo层，但保持一致） ``` ### 场景3：我要加个配置类 ```java ❓ 放哪里？ 问：这个配置是全局的吗？ ✅ 是（如：Redis配置） → common/config/RedisConfig.java ❌ 否（如：武术评分规则） → modules/martial/config/ScoringConfig.java ``` ### 场景4：我要加个Controller ```java ❓ 放哪里？ 固定位置： modules/martial/controller/XxxController.java （不需要思考，统一放这里） ``` ## 九、总结 ### 现状 这是一个**混合式架构**的商业框架项目： - ✅ 功能全面，开箱即用 - ⚠️ 结构复杂，理解成本高 - ❌ 设计不够统一，有些"乱" ### 建议 1. **不要试图改造整体架构** - 成本太高 - 可能破坏框架功能 2. **理解规则，遵循规则** - 虽然不完美，但有规律可循 - 保持代码风格一致 3. **专注业务** - 核心工作在 `modules/martial/` - 不需要关心其他模块细节 4. **参考现有代码** - 看 `modules/system/` 的实现 - 模仿其结构和写法 ### 核心理念 **把它当作"带框架的项目"而不是"纯净的项目"** - 框架部分：auth, system, resource, desk, develop, common, job - 业务部分：modules/martial/ （这是你要关注的） --- **下一步**：查看《开发指南.md》，学习如何在这个架构下高效开发。