martial-master/docs/架构说明.md

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：我要加个工具类

❓ 放哪里？

问：这个工具类是给多个模块用的吗？
✅ 是 → common/utils/XxxUtil.java
❌ 否 → modules/martial/utils/XxxUtil.java（在模块内部创建utils目录）

场景2：我要加个实体类

❓ 放哪里？

固定位置：
modules/martial/pojo/entity/Xxx.java

（虽然多了pojo层，但保持一致）

场景3：我要加个配置类

❓ 放哪里？

问：这个配置是全局的吗？
✅ 是（如：Redis配置） → common/config/RedisConfig.java
❌ 否（如：武术评分规则） → modules/martial/config/ScoringConfig.java

场景4：我要加个Controller

❓ 放哪里？

固定位置：
modules/martial/controller/XxxController.java

（不需要思考，统一放这里）

九、总结

现状

这是一个混合式架构的商业框架项目：

• ✅ 功能全面，开箱即用
• ⚠️ 结构复杂，理解成本高
• ❌ 设计不够统一，有些"乱"

建议

1. 不要试图改造整体架构

   • 成本太高
   • 可能破坏框架功能

2. 理解规则，遵循规则

   • 虽然不完美，但有规律可循
   • 保持代码风格一致

3. 专注业务

   • 核心工作在 modules/martial/
   • 不需要关心其他模块细节

4. 参考现有代码

   • 看 modules/system/ 的实现
   • 模仿其结构和写法

核心理念

把它当作"带框架的项目"而不是"纯净的项目"

• 框架部分：auth, system, resource, desk, develop, common, job
• 业务部分：modules/martial/ （这是你要关注的）

---

下一步：查看《开发指南.md》，学习如何在这个架构下高效开发。