3分钟上手！MyBatis-Plus多表查询神器安装指南（附版本适配全表）

你是否还在为MyBatis-Plus多表联查写复杂SQL？是否因版本冲突浪费数小时调试依赖？本文将带你3分钟完成MyBatis-Plus-Join（MPJ）的环境搭建，从仓库获取到项目集成全流程覆盖，让多表查询代码量减少60%。

读完本文你将获得：

• 3种安装方式的详细对比（Maven/Gradle/源码编译）
• 版本匹配速查表（覆盖MP 3.2.0~3.5.10+所有版本）
• 避坑指南：解决90%的依赖冲突问题
• 一键验证安装的测试代码模板

关于MyBatis-Plus-Join

MyBatis-Plus-Join是MyBatis-Plus（MP）的增强插件，通过注解驱动和链式API实现零SQL的多表查询。核心优势包括：

• 无侵入设计：扩展MP构造器而非修改源码，原有代码无需改造
• 极简依赖：仅需Lombok（多数项目已集成）
• 双模式API：支持Lambda表达式（类型安全）和字符串（灵活）两种查询方式
• 代码生成：2.0+版本支持APT自动生成链式查询类

// 典型多表查询示例（左连接+条件过滤）
List<UsersVo> list = Joins.of(Users.class)
    .leftJoin(UsersAge.class, UsersAge::getAgeId, Users::getAgeId)
    .eq(UsersAge::getAgeName, "成年人")
    .select(Users::getUserName, UsersAge::getAgeDoc)
    .list(UsersVo.class);

环境准备清单

环境要求	版本范围	验证命令
JDK	8-17	java -version
MyBatis-Plus	3.2.0+	`mvn dependency:tree
Maven	3.5+	mvn -v
Gradle	5.0+	gradle -v

安装方式对比

方式1：Maven中央仓库（推荐）

最新稳定版（适配MP 3.5.10+）

<dependency>
    <groupId>icu.mhb</groupId>
    <artifactId>mybatis-plus-join-boot-starter</artifactId>
    <version>2.1.2</version>
</dependency>

处理器依赖（2.0+链式API必需）

<dependency>
    <groupId>icu.mhb</groupId>
    <artifactId>mybatis-plus-join-processor</artifactId>
    <version>2.1.2</version>
    <optional>true</optional>
</dependency>

方式2：源码编译安装

当需要使用最新开发版或定制功能时：

# 克隆仓库
git clone https://gitcode.com/mahuibo123/mybatis-plus-join.git
cd mybatis-plus-join

# 编译安装到本地仓库（-DskipTests跳过测试加速）
mvn clean install -DskipTests

# Gradle项目编译
./gradlew clean build publishToMavenLocal

方式3：手动导入JAR包

适合无网络环境或特殊部署场景：

1. 从Release页面下载对应版本JAR
2. 放入项目lib目录（以Spring Boot为例）：

<dependency>
    <groupId>icu.mhb</groupId>
    <artifactId>mybatis-plus-join-boot-starter</artifactId>
    <version>2.1.2</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/mybatis-plus-join-boot-starter-2.1.2.jar</systemPath>
</dependency>

版本匹配速查表

警告：版本不匹配会导致NoSuchMethodError或ClassCastException

MyBatis-Plus版本	推荐MPJ版本	特性支持
3.2.0	1.2.0	基础联查
3.3.1-3.4.2	1.3.4.1	左/右连接+条件构造
3.4.3.4-3.5.2	1.3.6	子查询+分页
3.5.3-3.5.10	2.1.1	链式API+APT生成
3.5.10+	2.1.2	动态表名+多租户支持

timeline
    title MPJ版本演进
    2021-06 : v1.0.0 基础功能
    2022-03 : v1.3.0 子查询支持
    2023-07 : v2.0.0 APT代码生成
    2024-01 : v2.1.0 动态表名
    2024-06 : v2.1.2 MP 3.5.10+适配

快速验证安装

创建测试类验证环境是否配置成功：

@SpringBootTest
public class MPJInstallTest {

    @Autowired
    private UserMapper userMapper; // 你的Mapper接口

    @Test
    public void testJoinQuery() {
        // 链式查询示例（需2.0+版本）
        UserChain userChain = UserChain.create();
        DeptChain deptChain = DeptChain.create();
        
        List<UserDeptVO> result = Joins.chain(userChain)
            .selectAs(() -> userChain.username().createTime()
                      .to(deptChain).deptName().deptId())
            .leftJoin(deptChain._deptId(), userChain._deptId())
            .eq(userChain.status(), 1)
            .list(UserDeptVO.class);
            
        System.out.println("查询结果条数：" + result.size());
        Assert.assertTrue(result.size() >= 0);
    }
}

常见问题解决

1. 依赖冲突（最常见）

症状：ClassNotFoundException或方法签名不匹配
解决：执行mvn dependency:tree检查冲突，排除低版本依赖：

<dependency>
    <groupId>icu.mhb</groupId>
    <artifactId>mybatis-plus-join-boot-starter</artifactId>
    <version>2.1.2</version>
    <exclusions>
        <exclusion>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-extension</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 注解处理器不生效

症状：未生成XXXChain类
解决：确认processor依赖已添加，IDE开启注解处理：

• IDEA：Settings > Build > Compiler > Annotation Processors > 勾选Enable annotation processing
• Maven编译：添加编译插件配置

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>icu.mhb</groupId>
                <artifactId>mybatis-plus-join-processor</artifactId>
                <version>2.1.2</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

下一步学习路径

1. 基础查询：单表条件构造 → 官方文档
2. 高级联查：多表嵌套查询 → 示例代码
3. 性能优化：索引设计与查询缓存 → 性能指南

提示：项目实战建议先查看Joins工具类的JavaDoc，其中包含所有API的使用示例。

结语

MyBatis-Plus-Join通过标准化的多表查询API，解决了MP原生不支持复杂联查的痛点。正确的版本选择和依赖管理是成功集成的关键，建议收藏本文版本对照表以备后续升级参考。

如果安装过程中遇到问题，可通过以下方式获取支持：

• GitHub Issues：https://gitcode.com/mahuibo123/mybatis-plus-join/issues
• 技术交流群：搜索微信小程序"马汇博的博客"获取入群方式

祝你的多表查询代码从此变得优雅简洁！