MyBatis-Plus-Join 多表插件技术文档

1. 项目概述

MyBatis-Plus-Join 是 MyBatis Plus 的一个多表关联插件，通过扩展 MP 的构造器实现多表查询功能。该插件具有以下特点：

• 学习成本低（10分钟即可掌握）
• 仅依赖 Lombok
• 完全兼容现有 MyBatis-Plus 项目
• 支持链式调用和 Lambda 表达式

2. 安装指南

2.1 Maven 依赖

根据您的 MyBatis-Plus 版本选择对应依赖：

MyBatis Plus 3.2.0 版本

<dependency>
  <groupId>icu.mhb</groupId>
  <artifactId>mybatis-plus-join</artifactId>
  <version>1.2.0</version>
</dependency>

最新版本（推荐）

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

APT 处理器（2.0+版本）

<dependency>
  <groupId>icu.mhb</groupId>
  <artifactId>mybatis-plus-join-processor</artifactId>
  <version>2.1.0</version>
</dependency>

2.2 版本兼容性

MyBatis-Plus 版本	支持的 MyBatis-Plus-Join 版本
3.2.0	1.2.0
3.3.1 - 3.42	1.0.2、1.3.4.1
3.4.3.4 - 3.5.2	1.0.3 至 1.3.3
3.5.3 - 3.5.10	1.3.3.1 至 2.1.1
3.5.10+	2.1.2

3. 使用说明

3.1 基础使用

List<UsersVo> list = Joins.of(Users.class)
        .leftJoin(UsersAge.class, UsersAge::getAgeId, Users::getAgeId)
        .eq(UsersAge::getAgeName, 1)
        .end()
        .joinList(UsersVo.class);

3.2 链式调用（2.0+版本）

UsersVo users = new UsersVo();
users.setUserName("setUserName");
users.setAgeName("setAgeName");

UsersChain usersChain = UsersChain.create();
UsersAgeChain ageChain = UsersAgeChain.create();

return Joins.chain(usersChain)
        .selectAs(() -> {
            return usersChain.userId().userName().createTime()
                            .to(ageChain)
                            .ageDoc().ageName().id();
        })
        .leftJoin(ageChain._id(), usersChain._ageId())
        .joinAnd(ageChain, (w) -> w.eq(ageChain._id(1)))
        .eqIfNull(() -> {
            return usersChain.userName(users.getUserName())
                    .userId(users.getUserId())
                    .ageId(users.getAgeId())
                    .to(ageChain)
                    .ageName(users.getAgeName())
                    .ageDoc(users.getAgeDoc());
        }).joinList(UsersVo.class);

4. API 文档

4.1 核心类说明

Joins 类

• 提供静态方法创建多表查询
• 主要方法：
  • of(Class<?> clazz)：初始化主表
  • chain(Object chain)：链式调用入口

JoinWrapper 类

• 继承自 MP 的 QueryWrapper
• 提供多表关联方法：
  • leftJoin()/rightJoin()/innerJoin()：关联表
  • on()：关联条件
  • selectAs()：字段映射

4.2 常用方法

表关联方法

.leftJoin(Class<?> joinClass, SFunction<T, ?> joinColumn, SFunction<R, ?> mainColumn)

条件方法

.eq(SFunction<T, ?> column, Object val)  // 等于条件
.ne(SFunction<T, ?> column, Object val)  // 不等于条件
.like(SFunction<T, ?> column, Object val) // 模糊查询

结果映射方法

.joinList(Class<V> clazz)  // 返回列表
.joinOne(Class<V> clazz)   // 返回单条记录

5. 最佳实践

5.1 多表查询示例

// 查询用户及其年龄信息
List<UserAgeVo> result = Joins.of(User.class)
        .leftJoin(UserAge.class, UserAge::getId, User::getAgeId)
        .selectAs(() -> {
            return Arrays.asList(
                User::getId,
                User::getName,
                UserAge::getAgeName,
                UserAge::getAgeDesc
            );
        })
        .eq(User::getStatus, 1)
        .joinList(UserAgeVo.class);

5.2 复杂条件查询

Joins.of(Order.class)
        .leftJoin(User.class, User::getId, Order::getUserId)
        .leftJoin(Product.class, Product::getId, Order::getProductId)
        .selectAs(() -> {
            return Arrays.asList(
                Order::getId,
                Order::getOrderNo,
                User::getName.as("userName"),
                Product::getName.as("productName")
            );
        })
        .between(Order::getCreateTime, startDate, endDate)
        .eq(Order::getStatus, 1)
        .like(User::getName, "张")
        .joinList(OrderDetailVo.class);

6. 注意事项

1. 确保主表和关联表都有对应的实体类
2. 结果映射类需要包含所有查询字段
3. 链式调用需要先创建对应的 Chain 类
4. 复杂查询建议使用 selectAs 明确指定字段

7. 问题排查

1. SQL 语法错误：检查关联条件和字段名是否正确
2. 结果映射失败：确保 VO 类包含所有查询字段
3. 版本不兼容：检查 MyBatis-Plus 和插件的版本对应关系

如需进一步帮助，可通过 Issues 提交问题或联系作者。