1c96ef4f6f
All checks were successful
continuous-integration/drone/push Build is passing
将 doc/ 目录重组为更标准的结构： 目录变更： - doc/ → docs/ (文档目录，只包含 .md 文件) - doc/sql/ → database/ (数据库脚本目录) - database/bladex/ (BladeX 框架数据库) - database/flowable/ (Flowable 工作流数据库) - database/martial-db/ (武术系统业务数据库) - database/upgrade/ (数据库升级脚本) - doc/script/ → scripts/ (部署和运维脚本) - scripts/docker/ (Docker 部署脚本) - scripts/fatjar/ (Fat JAR 启动脚本) 优势： - 符合标准项目结构规范 - 文档、数据库、脚本分离更清晰 - 便于维护和查找 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
411 lines
12 KiB
Markdown
411 lines
12 KiB
Markdown
# 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》，学习如何在这个架构下高效开发。
|