martial/martial-master
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

优化后端配置和数据库结构

Browse Source 
1. 修复Swagger配置，添加武术模块API分组
   - 在SwaggerConfiguration中新增martialApi()方法
   - 使武术模块的66个接口能在Knife4j界面正常显示

2. 优化项目依赖配置
   - 添加spring-boot-starter-actuator用于健康检查
   - 暂时注释flowable工作流依赖以简化项目

3. 更新数据库结构
   - 优化martial_db.sql，精简表结构从123张减少到53张
   - 保留核心BladeX系统表和15张武术业务表
   - 更新测试数据：2场比赛、10名运动员、9个项目

4. 补充项目文档
   - 添加架构说明、开发指南等中文文档

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
n72595987@gmail.com
2025-11-29 16:30:20 +08:00
parent 9c77fcb4ac
commit 38472ee832
7 changed files with 7502 additions and 7331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
doc/README.md Normal file
View File

@@ -0,0 +1,142 @@
# 项目文档索引
## 📚 开发文档
### 1. [前后端架构说明.md](./前后端架构说明.md) 🆕
**理解 BladeX 完整系统架构和前后端分离**
- BladeX 完整系统架构（后端 + 前端 Saber）
- Saber 前端管理系统介绍
- 前后端交互流程
- 如何在没有前端的情况下开发
- 单体架构 vs 微服务架构
- 模块启动管理说明
**适合阅读时机**：
- ✅ 想了解完整的系统架构时
- ✅ 疑惑"管理界面在哪里"时
- ✅ 需要配置前后端联调时
- ✅ 想了解如何获取前端源码时
---
### 2. [架构说明.md](./架构说明.md)
**理解 BladeX 后端框架的架构设计**
- 为什么这个项目的结构看起来"乱"？
- BladeX 架构 vs 传统 Spring Boot 架构对比
- common、modules、job 目录的职责划分
- 架构设计理念分析
- 与标准架构的映射关系
**适合阅读时机**：
- ✅ 刚接触项目，对后端架构感到困惑时
- ✅ 想理解为什么要这样设计时
- ✅ 需要向团队解释项目结构时
---
### 3. [开发指南.md](./开发指南.md)
**在 BladeX 框架下高效开发的实用指南**
包含内容：
- 📖 快速开始：环境准备、核心目录
- 🔧 标准开发流程：完整的功能开发步骤（从数据库到API）
- 📝 代码规范：命名、注解、包结构
- 💡 常见场景：查询、分页、关联、事务等实战示例
- ✅ 最佳实践：Service、Controller、异常处理、缓存
- 🐛 调试技巧：VS Code 调试、日志、SQL 调试
- ❓ 常见问题：继承选择、Mapper 配置、分页等
**适合阅读时机**：
- ✅ 准备开始开发新功能时
- ✅ 遇到具体技术问题时
- ✅ 需要参考代码示例时
---
## 🎯 快速导航
### 我想...
| 需求 | 推荐文档 | 章节 |
|------|---------|------|
| 了解完整系统架构（前端+后端） | [前后端架构说明.md](./前后端架构说明.md) | 一、BladeX 完整系统架构 |
| 管理界面在哪里？ | [前后端架构说明.md](./前后端架构说明.md) | 二、前端管理系统 - Saber |
| 如何获取/配置前端 | [前后端架构说明.md](./前后端架构说明.md) | 四、当前项目的使用方式 |
| 理解后端架构设计 | [架构说明.md](./架构说明.md) | 二、目录结构对比 |
| 理解为什么架构"乱" | [架构说明.md](./架构说明.md) | 三、架构特点分析 |
| 知道代码应该放哪里 | [架构说明.md](./架构说明.md) | 八、实际开发时如何思考 |
| 开发一个新功能 | [开发指南.md](./开发指南.md) | 二、标准开发流程 |
| 学习代码规范 | [开发指南.md](./开发指南.md) | 三、代码规范 |
| 查看查询示例 | [开发指南.md](./开发指南.md) | 四、常见开发场景 |
| 学习最佳实践 | [开发指南.md](./开发指南.md) | 五、最佳实践 |
| 调试代码 | [开发指南.md](./开发指南.md) | 六、调试技巧 |
| 解决常见问题 | [开发指南.md](./开发指南.md) | 七、常见问题 |
---
## 📋 其他文档
### 项目配置与说明
- [CLAUDE.md](../CLAUDE.md) - 项目整体说明、技术栈、构建命令
- [.vscode/DEBUG_GUIDE.md](../.vscode/DEBUG_GUIDE.md) - VS Code 调试配置指南
### 数据库文档
- [sql/mysql/martial-competition-tables.sql](./sql/mysql/martial-competition-tables.sql) - 武术比赛表结构
- [sql/mysql/martial-competition-menu.sql](./sql/mysql/martial-competition-menu.sql) - 菜单权限配置
---
## 🚀 新人入门路径
### 第一天：环境准备
1. 阅读 [CLAUDE.md](../CLAUDE.md) 了解项目概况
2. 配置开发环境（JDK、Maven、MySQL、Redis）
3. 启动项目，访问 http://localhost:8123/doc.html
### 第二天：理解架构
1. 阅读 [前后端架构说明.md](./前后端架构说明.md) 了解完整系统
2. 阅读 [架构说明.md](./架构说明.md) 理解后端设计
3. 浏览项目目录结构
4. 查看现有代码示例（`modules/system/`）
### 第三天：动手开发
1. 阅读 [开发指南.md](./开发指南.md)
2. 按照"标准开发流程"完成一个简单的 CRUD 功能
3. 测试接口
### 第四天：深入学习
1. 学习复杂查询、关联查询
2. 掌握调试技巧
3. 解决遇到的问题
---
## 💡 学习建议
### 对于初学者
- 先看 **开发指南** 的"快速开始"和"标准开发流程"
- 边看边实践，动手写一个 CRUD 功能
- 遇到问题查看"常见问题"章节
### 对于有经验的开发者
- 快速浏览 **架构说明**，理解 BladeX 的特点
- 重点关注 **开发指南** 的"最佳实践"
- 参考"常见场景"进行复杂功能开发
### 对于团队 Leader
- 使用 **架构说明** 向团队解释项目结构
- 制定基于 **开发指南** 的团队规范
- 组织 Code Review 时参考"代码规范"
---
## 🔄 文档更新
本文档会根据项目实际情况持续更新。如有问题或建议，请及时反馈。
**最后更新**：2025-11-29
**维护者**：开发团队

12660
doc/sql/martial-db/martial_db.sql
View File

File diff suppressed because one or more lines are too long

432
doc/前后端架构说明.md Normal file
View File

@@ -0,0 +1,432 @@
# BladeX 完整架构说明
## 一、BladeX 完整系统架构
BladeX 是一个**前后端分离**的企业级微服务架构，完整的系统包含多个项目：
```
BladeX 完整架构
├── 后端项目（当前）
│ ├── martial-master # Spring Boot 后端 API（当前项目）
│ └── martial-tool # BladeX 框架核心（依赖库）
│
├── 前端项目（独立仓库）
│ ├── Saber (推荐) # Vue 3 + Element Plus 管理后台 ⭐
│ └── Sword (旧版) # Vue 2 + Avue 管理后台（已不推荐）
│
└── 可选组件
├── BladeX-Auth # 独立认证中心（微服务版）
├── BladeX-Gateway # 网关服务（微服务版）
└── BladeX-Register # 注册中心（Nacos）
```
### 当前项目状态
根据 `CLAUDE.md` 的说明：
```
"The frontend is a separate Vue.js project (not in this repository)"
```
**当前您手上只有后端项目** `martial-master`，前端管理系统是独立的项目。
---
## 二、前端管理系统 - Saber
### 2.1 Saber 是什么？
**Saber** 是 BladeX 官方的 Vue 3 管理后台系统，提供可视化的管理界面。
**主要功能**：
- 🏠 **仪表盘**：数据统计、图表展示
- 👥 **用户管理**：用户增删改查、角色分配
- 🔐 **权限管理**：角色管理、菜单管理、权限分配
- 🏢 **组织架构**：部门管理、岗位管理
- 📋 **系统管理**：字典管理、参数配置、日志查看
- 🗂️ **资源管理**：文件上传、OSS 配置
- ⚙️ **开发工具**：代码生成器、数据源管理
- 🥋 **业务功能**：武术比赛管理（根据菜单配置）
### 2.2 Saber 技术栈
```
前端框架：Vue 3
UI 组件：Element Plus
状态管理：Pinia
路由：Vue Router 4
构建工具：Vite
HTTP 库：Axios
```
### 2.3 Saber 项目地址
**官方仓库**（需要授权访问）：
```
Gitee: https://gitee.com/smallc/Saber
GitHub: https://github.com/chillzhuang/Saber
```
**注意**：BladeX 是商业框架，完整源码需要购买授权。
### 2.4 Saber 运行端口
根据配置文件中的线索：
```yaml
# application-dev.yml
blade:
token:
domain: http://127.0.0.1:1888 # 前端地址
```
**默认端口**：`1888`（开发环境）
---
## 三、前后端交互流程
```
┌─────────────────────────────────────────────────────────────┐
│ 用户浏览器 │
└──────────────┬──────────────────────────────────────────────┘
│
│ http://localhost:1888
▼
┌──────────────────────────────────────────────────────────────┐
│ Saber 前端 (Vue 3) │
│ - 登录页面 │
│ - 仪表盘 │
│ - 用户管理 │
│ - 权限管理 │
│ - 武术比赛管理（调用后端 API） │
└──────────────┬───────────────────────────────────────────────┘
│
│ HTTP 请求（JSON）
│ POST /blade-auth/token
│ GET /blade-system/user/list
│ GET /api/martial/competition/list
▼
┌──────────────────────────────────────────────────────────────┐
│ martial-master 后端 (Spring Boot) │
│ http://localhost:8123 │
│ │
│ ├── /blade-auth/** → 认证模块 │
│ ├── /blade-system/** → 系统管理 │
│ ├── /blade-desk/** → 仪表盘 │
│ ├── /blade-resource/** → 资源管理 │
│ ├── /blade-develop/** → 开发工具 │
│ └── /api/martial/** → 武术比赛（您的业务） │
└──────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ MySQL │
│ Redis │
└──────────────┘
```
---
## 四、当前项目的使用方式
### 方式一：仅使用 API（当前可用）✅
**适合场景**：
- 前端单独开发
- 移动端开发
- API 集成测试
**访问方式**：
```
Knife4j API 文档：http://localhost:8123/doc.html
直接调用 API：
POST http://localhost:8123/blade-auth/token
GET http://localhost:8123/api/martial/competition/list
```
**优点**：
- ✅ 无需前端，可以直接测试 API
- ✅ 适合后端开发和调试
**缺点**：
- ❌ 没有可视化界面
- ❌ 需要手动构造 HTTP 请求
---
### 方式二：搭配 Saber 前端（需要获取源码）
**步骤 1：获取 Saber 源码**
如果您有 BladeX 授权，可以从官方获取 Saber 源码：
```bash
# Gitee
git clone https://gitee.com/smallc/Saber.git
# GitHub
git clone https://github.com/chillzhuang/Saber.git
```
**步骤 2：配置后端地址**
```javascript
// Saber/src/config/website.js
export default {
// 后端 API 地址
apiUrl: 'http://localhost:8123',
// Token 存储键
tokenHeader: 'Blade-Auth',
// 其他配置...
}
```
**步骤 3：安装依赖并启动**
```bash
cd Saber
# 安装依赖
npm install
# 或
yarn install
# 启动开发服务器
npm run dev
# 或
yarn dev
```
**步骤 4：访问**
```
浏览器访问：http://localhost:1888
默认账号：
用户名：admin
密码：admin
```
**步骤 5：使用管理后台**
登录后，您可以在 Saber 管理后台中：
- 📊 查看仪表盘数据
- 👥 管理用户和角色
- 📋 配置菜单权限
- 🥋 使用武术比赛管理功能（需要先配置菜单）
---
### 方式三：使用第三方 API 工具（临时方案）
如果暂时没有 Saber 源码，可以使用：
**Postman / Apifox / Insomnia**
```
1. 先调用登录接口获取 Token：
POST http://localhost:8123/blade-auth/token
Body: {
"tenantId": "000000",
"username": "admin",
"password": "admin",
"grant_type": "captcha",
"scope": "all"
}
2. 复制返回的 access_token
3. 在后续请求中添加 Header：
Blade-Auth: bearer <access_token>
4. 调用业务接口：
GET http://localhost:8123/api/martial/competition/list
```
**VS Code REST Client 扩展**
```http
### 1. 登录获取 Token
POST http://localhost:8123/blade-auth/token
Content-Type: application/json
{
"tenantId": "000000",
"username": "admin",
"password": "admin",
"grant_type": "captcha",
"scope": "all"
}
### 2. 调用业务接口
GET http://localhost:8123/api/martial/competition/list
Blade-Auth: bearer {{token}}
```
---
## 五、模块启动管理
### 5.1 单体架构（当前项目）
**当前项目是单体应用**，所有模块在一个进程中运行：
```
java -jar blade-api.jar
启动后，所有模块同时可用：
✅ auth 模块
✅ system 模块
✅ resource 模块
✅ desk 模块
✅ develop 模块
✅ martial 模块
✅ job 模块
```
**没有独立的模块启动管理**，因为不是微服务架构。
---
### 5.2 微服务架构（可选升级）
如果升级到微服务版本，架构会变成：
```
BladeX 微服务架构
├── BladeX-Register (Nacos) # 注册中心，管理所有服务
├── BladeX-Gateway # 网关服务
├── BladeX-Auth # 认证服务
├── BladeX-System # 系统服务
├── BladeX-Resource # 资源服务
├── BladeX-Desk # 工作台服务
└── Martial-Service # 武术比赛服务（您的业务）
```
**此时会有管理界面**：
**Nacos 控制台**：
```
地址：http://localhost:8848/nacos
功能：
- 查看所有注册的服务
- 服务健康检查
- 配置管理
- 服务上下线
```
**Sentinel 控制台**（可选）：
```
地址：http://localhost:8858
功能：
- 流量控制
- 熔断降级
- 系统负载保护
```
**Spring Boot Admin**（可选）：
```
地址：http://localhost:7002
功能：
- 监控所有 Spring Boot 应用
- 查看日志
- 查看 JVM 信息
- 健康检查
```
---
## 六、常见疑问解答
### Q1: 为什么没有找到管理界面？
**A**: 当前项目是**纯后端 API 项目**，前端管理系统（Saber）是独立的项目，需要单独获取和部署。
### Q2: 如何获取 Saber 前端源码？
**A**:
- 如果您有 BladeX 授权，从官方仓库获取
- 如果是开源版本，部分功能可能不可用
- 可以联系 BladeX 官方获取试用版
### Q3: 没有 Saber 可以开发吗？
**A**: 可以！
- 使用 Knife4j API 文档测试：http://localhost:8123/doc.html
- 使用 Postman/Apifox 调用 API
- 自己开发前端（任何技术栈都可以）
### Q4: 如何查看系统运行状态？
**A**:
- 查看日志：`tail -f application.log`
- 健康检查：http://localhost:8123/actuator/health
- Druid 监控：http://localhost:8123/druid
- Knife4j 文档：http://localhost:8123/doc.html
### Q5: 这个项目是微服务吗？
**A**: 当前是**单体应用**（Monolithic），但使用了模块化设计。如果需要，可以升级为微服务架构。
---
## 七、推荐的开发方式
### 当前阶段（无 Saber）
```
1. 后端开发：
- 在 VS Code 中开发业务逻辑
- 使用 F5 调试运行
2. 接口测试：
- 使用 Knife4j：http://localhost:8123/doc.html
- 使用 Postman/Apifox
3. 数据库操作：
- 使用 Navicat/DBeaver 连接 MySQL
- 执行 SQL 查看数据
```
### 有 Saber 前端时
```
1. 启动后端：
cd martial-master
mvn spring-boot:run
2. 启动前端：
cd Saber
npm run dev
3. 访问管理后台：
http://localhost:1888
4. 全栈开发：
- 后端改代码 → 前端调用 API
- 前端页面 → 调用后端接口
```
---
## 八、总结
| 组件 | 状态 | 地址 | 说明 |
|------|------|------|------|
| **后端 API** | ✅ 有 | http://localhost:8123 | 当前项目 |
| **API 文档** | ✅ 有 | http://localhost:8123/doc.html | Knife4j |
| **Druid 监控** | ✅ 有 | http://localhost:8123/druid | 数据库监控 |
| **前端管理系统** | ❌ 无 | http://localhost:1888 | Saber（需单独获取） |
| **模块管理界面** | ❌ 无 | - | 单体应用，无需管理 |
**关键点**：
- ✅ 后端可以独立运行和开发
- ✅ 使用 Knife4j 可以完成所有测试
- ❌ 如需可视化管理界面，需要部署 Saber 前端
- ❌ 单体架构下没有"模块启动管理"的概念
---
**建议**：
1. 现阶段专注后端 API 开发
2. 使用 Knife4j 测试接口
3. 如需前端，可以自己用 Vue/React 开发，或等待获取 Saber 源码

1171
doc/开发指南.md Normal file
View File

File diff suppressed because it is too large Load Diff

410
doc/架构说明.md Normal file
View File

@@ -0,0 +1,410 @@
# 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》，学习如何在这个架构下高效开发。