# RuoYi-MPJ-BootX

**Repository Path**: LukewarmMe/RuoYi-MPJ-BootX

## Basic Information

- **Project Name**: RuoYi-MPJ-BootX
- **Description**: MPJ-BootX 是一个基于若依框架设计的 Spring Boot 3 快速开发脚手架，在若依框架的优秀基础上，集成了 MyBatis Plus Join（MPJ）作为核心 ORM 框架，并结合个人开发经验进行了优化设计。项目旨在为开发者提供开箱即用的后端开发环境，通过 MPJ 的强大关联查询能力和创新的数据权限控制机制，让开发者能够更专注于业务逻辑实现，大幅提升开发效率。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MPJ-BootX

[![Java](https://img.shields.io/badge/java-17-blue.svg?style=flat-square)](https://www.oracle.com/java/technologies/javase-jdk17-downloads.html)
[![Spring Boot](https://img.shields.io/badge/spring--boot-3.5.8-brightgreen.svg?style=flat-square)](https://spring.io/projects/spring-boot)
[![Maven](https://img.shields.io/badge/maven-3.6%2B-brightgreen.svg?style=flat-square)](https://maven.apache.org/)
[![Sa-Token](https://img.shields.io/badge/sa--token-1.44.0-blue.svg?style=flat-square)](https://sa-token.cc/)
[![X-File-Storage](https://img.shields.io/badge/x--file--storage-2.3.0-orange.svg?style=flat-square)](https://gitee.com/dromara/x-file-storage)

基于若依框架设计的 Spring Boot 3 快速开发脚手架，集成 MyBatis Plus Join（MPJ）作为核心 ORM 框架，提供更优雅的数据库操作体验。

## 📋 项目简介

MPJ-BootX 是一个基于若依框架设计的 Spring Boot 3 快速开发脚手架，在若依框架的优秀基础上，集成了 MyBatis Plus Join（MPJ）作为核心 ORM 框架，并结合个人开发经验进行了优化设计。项目旨在为开发者提供开箱即用的后端开发环境，通过 MPJ 的强大关联查询能力和创新的数据权限控制机制，让开发者能够更专注于业务逻辑实现，大幅提升开发效率。

### 🎯 设计理念

- **传承与创新**：继承若依框架的优秀设计理念，结合 MPJ 框架进行创新优化
- **模块化设计**：清晰的分层结构，便于扩展和维护
- **最佳实践**：集成主流技术栈，遵循行业最佳实践
- **开箱即用**：提供完整的权限管理、工作流、文件管理等核心功能
- **灵活扩展**：保留若依框架的扩展性，同时优化 MPJ 的使用体验

## ✨ 核心特性

### 🔐 权限认证
- 基于 **Sa-Token** 的权限认证系统
- 支持路由拦截、权限校验、角色管理
- Token 认证，支持并发登录控制

### 👥 用户权限管理
- 完整的用户、角色、菜单、部门管理体系
- 灵活的权限分配机制
- **基于 MPJ 的数据权限控制**：支持 5 种数据权限场景

### 📝 工作流引擎
- 集成 **Flowable 7.2.0** 工作流引擎
- 支持流程设计、审批流转
- 提供流程历史查询、待办已办管理

### 📁 文件管理
- 支持本地存储和 **MinIO** 对象存储
- 文件上传下载、分片上传
- 基于 **X-File-Storage** 的存储抽象

### 📊 字典管理
- 系统字典和类型字典管理
- 字典数据缓存，提升查询性能
- 支持字典数据导入导出

### 📄 代码生成器
- 基于 **MyBatis Plus Generator** 的代码生成器
- 支持自定义 FreeMarker 模板
- 一键生成 Controller、Service、Mapper、QueryWrapper 等代码

### 📖 API 文档
- 集成 **Knife4j 4.5.0**，自动生成接口文档
- 支持在线测试接口
- 中文界面，使用便捷

### 🎨 验证码
- 支持文字验证码和滑块验证码
- 验证码图片缓存预热
- 防止恶意攻击

### 💾 缓存预热
- 启动时自动预热字典、配置等缓存数据
- 支持异步预热，不阻塞应用启动
- 可配置预热超时时间

### 📝 操作日志
- 自动记录用户操作日志
- 支持日志查询和导出
- 基于 AOP 实现，使用简单

### 🔍 多条件查询
- 基于 **MyBatis Plus Join（MPJ）** 的关联查询封装
- 支持复杂条件组合查询和多表关联查询
- 通过 MPJLambdaWrapper 简化关联查询操作

### 📊 Excel 导入导出
- 基于 **EasyPoi** 的 Excel 处理
- 支持复杂模板导出
- 支持多 Sheet 导出

## 🛠️ 技术栈

### 核心框架
- **Spring Boot** 3.5.8 - 基础框架
- **Java** 17 - 开发语言
- **Maven** 3.6+ - 项目管理

### 数据层
- **MyBatis Plus Join** 1.5.5 - 核心 ORM 框架
- **MyBatis Plus** 3.5.15 - ORM 基础框架
- **Druid** 1.2.25 - 数据库连接池
- **数据库支持**：MySQL、PostgreSQL、Oracle、达梦、人大金仓、南大通用等

### 缓存与安全
- **Redis** - 缓存数据库
- **Sa-Token** 1.44.0 - 权限认证框架

### 工作流与文档
- **Flowable** 7.2.0 - 工作流引擎
- **Knife4j** 4.5.0 - API 文档工具

### 文件处理
- **X-File-Storage** 2.3.0 - 文件存储抽象
- **MinIO** 8.6.0 - 对象存储
- **EasyPoi** 4.5.0 - Excel 导入导出

### 工具类库
- **Hutool** 5.8.41 - Java 工具类库
- **Fastjson2** 2.0.58 - JSON 处理
- **Lombok** - 简化代码
- **Aviator** 5.4.3 - 表达式计算引擎

## 🎯 设计亮点

### 1. 若依框架与 MPJ 的融合设计
- 在若依框架的基础上，平滑集成 MPJ 框架，保持原有代码结构的同时增强查询能力
- 优化了若依框架的查询封装，使用 MPJLambdaWrapper 提供更优雅的关联查询体验
- 保持若依框架的权限体系，同时扩展了基于 MPJ 的数据权限控制

### 2. 创新的数据权限控制
- 在 BaseQueryWrapper 中基于 MPJ 实现数据权限控制
- 支持 5 种数据权限场景：
  - 全部数据权限
  - 自定义数据权限
  - 本部门数据权限
  - 本部门及以下数据权限
  - 仅本人数据权限
- 在多表关联查询场景下也能实现数据权限过滤

### 3. 数据库兼容性设计
- 支持主流数据库和国产数据库，完美适配信创要求
- 基于 MPJ 的查询封装，降低数据库切换成本
- 支持多种数据库方言，无需大量修改代码即可切换数据库

### 4. 模块化设计与清晰的项目结构
- 继承若依框架的分层架构设计，职责分明
- 通用组件与业务逻辑分离，便于扩展和维护
- 遵循 Spring Boot 最佳实践，代码结构清晰易读

### 5. 丰富的工具类库
- 字典缓存工具（DictCacheUtil）
- 配置缓存工具（ConfigCacheUtil）
- Redis 工具类（RedisUtil）
- Excel 工具类（EasyPoiUtil）
- 验证码工具类等

## 📁 项目结构

```
MPJ-BootX/
├── src/main/java/com/mpj/
│   ├── common/                    # 通用组件
│   │   ├── annotation/           # 自定义注解
│   │   ├── aspect/               # AOP 切面
│   │   ├── bean/                 # 通用 Bean
│   │   ├── config/               # 配置类
│   │   ├── constant/             # 常量定义
│   │   ├── context/              # 上下文
│   │   ├── enums/                # 枚举类
│   │   ├── exception/            # 异常处理
│   │   ├── filter/               # 过滤器
│   │   ├── handler/              # 处理器
│   │   ├── listener/             # 监听器
│   │   └── utils/                # 工具类
│   ├── controller/               # 控制器层
│   ├── service/                  # 服务层
│   │   └── impl/                 # 服务实现
│   ├── mapper/                   # Mapper 接口
│   ├── pojo/                     # 实体类
│   │   ├── dto/                  # 数据传输对象
│   │   ├── entity/               # 实体类
│   │   └── vo/                   # 视图对象
│   ├── wrapper/                  # 查询包装器
│   ├── flowable/                 # 工作流相关
│   ├── Generator.java            # 代码生成器
│   └── MPJBootXApplication.java  # 启动类
├── src/main/resources/
│   ├── processes/                # 工作流流程定义
│   ├── static/                   # 静态资源
│   ├── template/                 # 模板文件
│   ├── templates/                # 代码生成模板
│   ├── application.yml           # 主配置文件
│   ├── application-dev.yml       # 开发环境配置
│   └── logback-spring.xml        # 日志配置
├── .gitignore                    # Git 忽略文件
├── Dockerfile                    # Docker 配置
├── README.md                     # 项目文档
└── pom.xml                       # Maven 配置
```

## 🚀 快速开始

### 环境要求

- **Java** 17+
- **Maven** 3.6+
- **MySQL** 5.7+ 或其他支持的数据库
- **Redis** 6.0+（可选，用于缓存和会话管理）
- **MinIO**（可选，用于对象存储）

### 安装

1. 克隆项目

```bash
git clone https://github.com/mpj-bootx/mpj-bootx.git
cd mpj-bootx
```

2. 配置数据库

创建数据库并导入初始化脚本（mpj_bootx.sql）：

```sql
CREATE DATABASE mpj_bootx DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE mpj_bootx;
SOURCE src/mpj_bootx.sql;
```

3. 配置环境变量

修改 `src/main/resources/application-dev.yml` 文件，配置数据库、Redis 等：

```yaml
# 数据库配置
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mpj_bootx?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

# Redis 配置
  redis:
    host: localhost
    port: 6379
    password:
    database: 0

# 服务器配置
server:
  port: 8081
  servlet:
    context-path: /
```

### 启动项目

1. 使用 Maven 构建项目

```bash
mvn clean install -DskipTests
```

2. 启动项目

```bash
java -jar target/MPJ-BootX-1.0.0.jar
```

或直接在 IDE 中运行 `MPJBootXApplication.java` 类。

### 访问项目

- 项目地址：http://localhost:8081
- API 文档：http://localhost:8081/doc.html

## 📝 使用说明

### 代码生成器

项目内置代码生成器，可快速生成完整的 CRUD 代码：

1. 配置数据库连接和表名

修改 `Generator.java` 文件中的数据库配置和要生成的表名：

```java
// 数据源配置
DataSourceConfig.Builder dataSourceConfig = new DataSourceConfig.Builder(
    "jdbc:mysql://localhost:3306/mpj_bootx?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai",
    "root",
    "root"
);

// 生成策略配置
StrategyConfig.Builder strategyConfig = new StrategyConfig.Builder()
    .addInclude("your_table_name")  // 设置需要生成的表名
    .build();
```

2. 运行代码生成器

运行 `Generator.main()` 方法，自动生成以下代码：

- Entity 实体类
- Mapper 接口（继承 MPJBaseMapper）
- Service 接口和实现类
- Controller 控制器
- QueryWrapper 查询包装器

生成的代码遵循项目规范，开箱即用。

### API 文档

项目集成 Knife4j，自动生成 API 文档：

- 访问地址：http://localhost:8081/doc.html
- 支持在线测试接口
- 中文界面，使用便捷

### 数据权限控制

1. 配置数据权限

在角色管理中配置数据权限范围：

- 全部数据权限
- 自定义数据权限（选择部门）
- 本部门数据权限
- 本部门及以下数据权限
- 仅本人数据权限

2. 使用数据权限

在 Service 层使用对应的 QueryWrapper 时，调用 `buildDataScope()` 方法：

```java
public class UserQueryWrapper extends BaseQueryWrapper {
    public MPJLambdaWrapper<User> commonConvert(User user) {
        /**
         * buildDataScope 通用无表别名数据权限过滤（查询数据表为主表时使用）
         *
         * @param clazz        实体类类型
         * @param deptColumnGetter dept字段的 getter 方法引用（如 User::getDeptId）
         * @param userColumnGetter user字段的 getter 方法引用（如 User::getUserId）
         * @param <E>          实体类型
         * @return MPJLambdaWrapper
         */
        MPJLambdaWrapper<User> queryWrapper = buildDataScope(User.class, User::getDeptId, User::getUserId);
        return queryWrapper;
    }
}
```

## 📚 功能模块详情

### 用户权限管理

- **用户管理**：用户信息 CRUD、启用禁用、重置密码
- **角色管理**：角色信息 CRUD、权限分配
- **菜单管理**：菜单信息 CRUD、权限配置
- **部门管理**：组织架构管理

### 工作流引擎

- **流程设计**：基于 Flowable 设计审批流程
- **流程实例**：发起流程、流程查询
- **待办管理**：待办任务、已办任务
- **流程历史**：流程流转记录查询

### 文件管理

- **文件上传**：单文件上传、多文件上传、分片上传
- **文件下载**：文件下载、预览
- **存储支持**：本地存储、MinIO 对象存储
- **文件管理**：文件信息查询、删除

### 字典管理

- **字典类型管理**：字典类型 CRUD
- **字典数据管理**：字典数据 CRUD、缓存
- **导入导出**：字典数据导入导出

### 系统配置

- **配置管理**：系统参数配置
- **配置缓存**：配置数据缓存，提升性能

### 操作日志

- **自动记录**：基于 AOP 自动记录用户操作
- **日志查询**：操作日志查询
- **日志导出**：日志数据导出

## 🤝 贡献指南

欢迎大家贡献代码、提出建议和反馈问题！

### 贡献流程

1. Fork 项目
2. 创建功能分支（`git checkout -b feature/AmazingFeature`）
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）
4. 推送到分支（`git push origin feature/AmazingFeature`）
5. 提交 Pull Request