Dromara 新晋开源项目 MPE ，MybatisPlus 能力拓展增强包
借用 MybatisPlus 的口号：为简化开发工作、提高生产率而生
尽管 MybatisPlus （后文简称 MP）相比较 Mybatis 丝滑了很多，但是日常使用中，是否偶尔仍会怀念 JPA（Hibernate）的那种纵享丝滑的感受，更好的一心投入业务开发中，如果你也是如此，那么恭喜你发现了 MybatisPlusExt（后文简称 MPE）。
MPE 对 MP 做了进一步的拓展封装，即保留 MP 原功能，又添加更多有用便捷的功能。同样坚持 MP 的原则，只做增强不做改变，所以，即便是在使用 MPE 的情况下，也可以百分百的只使用 MP 的方式，因此 MP 能做的，MPE 不仅能做还能做的更多。
增强功能具体体现在几个方面：免手写Mapper、自动建表、数据自动填充（类似JPA中的审计）、关联查询（类似sql中的join）、冗余数据自动更新、动态查询条件。
开始
一、引入 jar 包
<!-- spring boot2.* -->
<dependency>
<groupId>com.tangzc</groupId>
<artifactId>mybatis-plus-ext-spring-boot-starter</artifactId>
<version>{maven仓库搜索最新版}</version>
</dependency>
<!-- spring boot3.* -->
<dependency>
<groupId>com.tangzc</groupId>
<artifactId>mybatis-plus-ext-spring-boot3-starter</artifactId>
<version>{maven仓库搜索最新版}</version>
</dependency>
二、代码预生成
痛点：
- 某个地方的代码想使用下实体字段的名称，但是又不想写死一个字符串（丑、编译期不可校验）。
- 手动为每个实体写一个 Mapper 类，但是 Mapper 类中都是空的。
这些交给 MPE 吧！！！
它在代码编译期前，自动预生成实体字段的定义、实体 Mapper 的接口定义、实体 Repository 类的定义（该类是进一步封装 Mapper 的）
// 标记生成表字段定义
@AutoDefine
// 标记生成Mapper和Repository
@AutoRepository
@Data
public class TestTable {
private String id;
private String name;
private int age;
}
效果如下：
<img src="https://cdn.nlark.com/yuque/0/2024/png/279660/1709718028160-1660d6a7-f0b6-4c23-aad1-249c3ab11898.png" alt="img" style="zoom:50%;" />
三、自动建表
MPE 自动建表依托于另一款自研框架 AutoTable，MPE 是基于 AutoTable 做了部分注解的拓展，同时做了 Mybatis-plus 的兼容处理。
此处做一个简单的使用介绍
@EnableAutoTable
@SpringBootApplication
public class DemoAutoTableApplication {
public static void main(String[] args) {
SpringApplication.run(DemoAutoTableApplication.class, args);
}
}
@Data
@Table
public class MyTable {
private Integer id;
private String userName；
}
上述代码就会自动把 MyTable 映射为 my_table 表，字段分别是 id:int、user_name:varchar(255)
PS：具体表名、字段名是否转下划线是根据 MybatisPlus 的配置来的
下面展示一个注解全面的例子：
@Data
@AutoDefine
// 指定表的编码
@MysqlCharset(value = "utf8mb4", collate = "utf8mb4_general_ci")
// 指定表的存储引擎
@MysqlEngine("myisam")
// 表头同样可以声明单个索引（此处只是举例，等价于username字段上的@Index）
@TableIndex(name = "username_index", fields = {MyTableDefine.username}, type = IndexTypeEnum.UNIQUE)
// 需要在表头声明多个索引的情况下，需要用@TableIndexes包裹起来
@TableIndexes({
// 声明普通联合索引
@TableIndex(name = "username_phone_index", fields = {MyTableDefine.username, MyTableDefine.phone}),
// 声明唯一联合索引，单独指定phone的索引排序方式，构建索引的时候indexFields中字段的顺序权重高于fields中的字段
@TableIndex(name = "username_phone_uni_index", fields = {MyTableDefine.username}, indexFields = {@IndexField(field = MyTableDefine.phone, sort = IndexSortTypeEnum.DESC)}, type = IndexTypeEnum.UNIQUE),
})
// 指定表名、表注释、数据源、忽略字段（不参与建表，等效于字段上的@Ignore）
@Table(value = "test_table", comment = "测试表", dsName = "my-mysql", excludeProperty={MyTableDefine.extra})
public class MyTable {
// 指定主键自增注释、类型（数据库数字类型可以跟java字符串类型相互转化）、长度
// 注意字段名称id会被自动认定为主键不需要再额外指定
@ColumnComment("id主键（因为我是独立注解，所以我是大哥，会覆盖下面的comment属性）")
@ColumnId(mode = IdType.AUTO, comment = "id主键", type = MysqlTypeConstant.BIGINT, length = 32)
private String id;
// 字段非NULL
@NotNull
// 字段默认值是空字符串
@ColumnDefault(type = DefaultValueEnum.EMPTY_STRING)
// 指定字段长度
@ColumnType(length = 100)
// 指定字段注释
@ColumnComment("用户名")
// 唯一索引
@Index(type = IndexTypeEnum.UNIQUE)
private String username;
// 设置默认值为0
@ColumnDefault("0")
@ColumnComment("年龄")
private Integer age;
@ColumnType(length = 20)
// 设置注释、默认值、不为空
@Column(comment = "电话", defaultValue = "+00 00000000", notNull = true)
// 唯一索引快捷方式
@UniqueIndex
private String phone;
// 设置注释、小数（等同于@ColumnType(length = 12, decimalLength = 6)）
@Column(comment = "资产", length = 12, decimalLength = 6)
private BigDecimal money;
// boolean值设置默认值
@ColumnDefault("true")
@Column(comment = "激活状态")
// 普通索引：指定索引名称、注释、索引方法
@Index(name = "active_index", comment = "激活状态索引")
private Boolean active;
// 单独设置字段类型
@ColumnType(MysqlTypeConstant.TEXT)
@ColumnComment("个人简介")
private String description;
// 设置默认值为当前时间
@ColumnDefault("CURRENT_TIMESTAMP")
@Column(comment = "注册时间")
private LocalDateTime registerTime;
// 忽略该字段，不参与建表
@Ignore
private String extra;
}
四、数据填充
可以在对数据库做插入或更新操作的时候，自动赋值数据操作人、操作时间、默认值等。
以文章发布为例，在发布 Artice 的时候，我们无需再去关心过多的与业务无关的字段值，最终只需要关心 title、content 两个核心数据即可，其他的数据均会被框架处理。
其中分别涉及了数据插入、数据更新、数据插入及更新三个处理时机，其中每个时机均可以插入系统时间及自定义用户信息。
定义文章实体
@Data
@Table(comment = "文章")
public class Article {
// 字符串类型的ID，默认也是雪花算法的一串数字（MP的默认功能）
@ColumnComment("主键")
private String id;
@ColumnComment("标题")
private String title;
@ColumnComment("内容")
private String content;
// 默认值用法：文章默认激活状态，ACTIVE为ActicleStatusEnum[ACTIVE, INACTIVE]的枚举名称字符串
@DefaultValue("ACTIVE")
@ColumnComment("内容")
private ActicleStatusEnum status;
@ColumnComment("发布时间")
// 【插入】数据时候会自动获取系统当前时间赋值，支持多种数据类型，具体可参考@FillTime注解详细介绍（注意，这里的时间是MP执行insert的操作的时候的时间，并不是对象构建时候的时间）
@InsertFillTime
private Date publishedTime;
@ColumnComment("发布人")
// 【插入】的时候，自动填充用户id，UserIdAutoFillHandler看下面代码
@InsertFillData(UserIdAutoFillHandler.class)
private String publishedUserId;
@ColumnComment("发布人名字")
// 【插入】的时候，自动填充用户名字，UsernameAutoFillHandler看下面代码
@InsertFillData(UsernameAutoFillHandler.class)
private String publishedUsername;
@ColumnComment("最后更新时间")
// 【插入和更新】数据时候会自动获取系统当前时间赋值，支持多种数据类型，具体可参考@FillTime注解详细介绍
@InsertUpdateFillTime
private Date publishedTime;
@ColumnComment("最后更新人")
// 【更新】的时候，自动填充用户id，UserIdAutoFillHandler看下面代码
// @UpdateFillData(UserIdAutoFillHandler.class)
// 【插入和更新】的时候，自动填充用户id，UserIdAutoFillHandler看下面代码
@InsertUpdateFillData(UserIdAutoFillHandler.class)
private String publishedUserId;
@ColumnComment("最后更新人名字")
// 【更新】的时候，自动填充用户名字，UsernameAutoFillHandler看下面代码
// @UpdateFillData(UsernameAutoFillHandler.class)
// 【插入和更新】的时候，自动填充用户名字，UsernameAutoFillHandler看下面代码
@InsertUpdateFillData(UsernameAutoFillHandler.class)
private String publishedUsername;
}
实现动态填充【用户 id】的接口
/**
* 全局获取用户ID
* 此处实现IOptionByAutoFillHandler接口和AutoFillHandler接口均可，
* 实现IOptionByAutoFillHandler接口，可以兼容框架内的BaseEntity。
* BaseEntity默认需要IOptionByAutoFillHandler的实现。BaseEntity的使用请查看官网。
*/
@Component
public class UserIdAutoFillHandler implements IOptionByAutoFillHandler<String> {
/**
* @param object 当前操作的数据对象
* @param clazz 当前操作的数据对象的class
* @param field 当前操作的数据对象上的字段
* @retur
*/
@Override
public String getVal(Object object, Class<?> clazz, Field field) {
RequestAttributes requestAttributes = RequestContextHolder.currentRequestAttributes();
HttpServletRequest request = ((ServletRequestAttributes)requestAttributes).getRequest();
// 配合网关或者过滤器，token校验成功后就把用户信息塞到header中
return request.getHeader("user-id");
}
}
实现动态填充【用户名】的接口
/**
* 全局获取用户名
*/
@Component
public class UsernameAutoFillHandler implements AutoFillHandler<String> {
/**
* @param object 当前操作的数据对象
* @param clazz 当前操作的数据对象的class
* @param field 当前操作的数据对象上的字段
* @return 当前登录用户id
*/
@Override
public String getVal(Object object, Class<?> clazz, Field field) {
RequestAttributes requestAttributes = RequestContextHolder.currentRequestAttributes();
HttpServletRequest request = ((ServletRequestAttributes)requestAttributes).getRequest();
// 配合网关或者过滤器，token校验成功后就把用户信息塞到header中
return request.getHeader("user-name");
}
}
五、关联查询
类似 JPA 的数据关联查询解决方案，替代 sql 中的 join 方式（或者内存组装数据的方式），通过注解关联多表之间的关系，查询某实体的时候，自动带出其关联性的数据。
以用户与文章之间的关系来举例
定义实体
@Data
@AutoDefine
@Table(comment = "文章")
public class Article {
@ColumnComment("主键")
private String id;
@ColumnComment("标题")
private String title;
@Column(comment = "内容", type = MySqlTypeConstant.MEDIUMTEXT)
private String content;
@ColumnComment("发布人")
private String publishedUserId;
@ColumnComment("审核: 0 不通过、1 通过")
private int audit;
@ColumnComment("发布时间（时间戳）")
private Long publishedTime;
}
@Data
@AutoDefine
@Table(comment = "用户信息")
public class User {
@ColumnComment("主键")
private String id;
@ColumnComment("用户名")
private String username;
@ColumnComment("密码")
private String password;
// 关联该用户发布的所有文章（"audit = 1" 表示的是Article下的audit为1的情况，customCondition的值只能是被关联表下的字段值，且会以and的形式添加在查询条件末尾。）
@BindEntity(conditions = @JoinCondition(selfField = UserDefine.id, joinField = ArticleDefine.publishedUserId), customCondition = "audit = 1", orderBy = @JoinOrderBy(field = ArticleDefine.publishedTime, isAsc = false))
private List<Article> articles;
}
需求：获取用户信息的同时只想获取用户已通过审核的发布记录，并且根据发布时间倒序排序。（通过自定义 SQL 条件）
【写法一】
// 获取到需要的user集合
User user = userMapper.getByUsername(name);
// 【推荐】用法一、指定属性关联。
Binder.bindOn(user, User::getArticles);
// 【不推荐】用法二、全关联。此种用法关联user下所有声明需要绑定的属性。
// Binder.bind(user);
【写法二】
// 本框架拓展的lambda查询器lambdaQueryPlus，增加了bindOne、bindList、bindPage
// 显然这是一种更加简便的查询方式，但是如果存在多级深度的关联关系，此种方法就不适用了，还需要借助Binder
User user = userRepository.lambdaQueryPlus()
.eq(User::getUsername, name)
// 【推荐】用法一、指定属性关联，只关联文章这个字段。
.bindList(User::getArticles);
// 【不推荐】用法二、全关联。此种用法关联user下所有声明需要绑定的属性。
// .bindList();
* 如果你打开 sql 打印，会看到 2 条 sql 语句，第一条根据 name 去 user 查询信息，第二条根据 userId 去 article 中查询关联的所有数据。
篇幅有限，更多用法（中间表查询、多对多查询等），请移步官方文档
注意：
为了解决数据库兼容支持的问题，关联查询底层原理是基于 MybatisPlus 的 BaseMapper<T> 实现的，所以要求所有关联的实体必须要对应的 Mapper 且继承自 MybatisPlus 的 BaseMapper<T>，包括中间表的实体，在使用中间表关联查询的情况下，也需要遵循此约束。
MPE 相当于把实体对应的 Mapper 视为数据访问窗口了，所以但凡需要从数据库查询数据的行为均需要通过对应的 Mapper 完成。
六、数据冗余
为了避免高频的数据关联查询，一种方案是做数据冗余，将其他表的部分字段冗余到当前表。但是这个方案牵扯一个数据修改后如何同步的问题，本功能就是为了解决这个问题而生的。
假设用户评论的场景，评论上需要冗余用户名和头像，如果用户的名字和头像有改动，则需要同步新的改动，代码如下：
@Data
@AutoDefine
@Table(comment = "用户信息")
public class User {
@ColumnComment("主键")
private String id;
@ColumnComment("用户名")
private String username;
@ColumnComment("头像")
private String icon;
// 省略其他属性
......
}
@Data
@AutoDefine
@Table(comment = "评论")
public class Comment {
@ColumnComment("主键")
private String id;
@ColumnComment("评论内容")
private String content;
@ColumnComment("评论人id")
private String userId;
// source指定了数据来源的Entity，同样可以使用sourceName来指定全路径的方式，field指定了映射哪个字段
// conditions中隐含了一个joinField字段，该字段默认是“id”，即@Condition(selfField = "userId", joinField = "id")等同于示例中的写法
@DataSource(source = User.class, field = UserDefine.username, conditions = @Condition(selfField = UserDefine.userId))
@ColumnComment("评论人名称")
private String userName;
// 如上，同理
@DataSource(source = User.class, field = UserDefine.icon, condition = @Condition(selfField = UserDefine.userId))
@ColumnComment("评论人头像")
private String userIcon;
}
基于 @DataSource 注解，框架会自动为指定字段注册监听 EntityUpdateEvent 事件（MPE 内置事件，可手动发起），所有 MP 的 Mapper 的 updateById 和 updateBatchById 两个方法执行的时候会自动发布 EntityUpdateEvent 事件。如果使用其他数据更新方式（比如手动写 sql 的形式）不会自动触发数据自动更新，如果想触发，需要用户自己抛出 EntityUpdateEvent 事件，即可完成数据自动更新。
具体用法及讲解，请移步官方文档
七、动态条件
根据预先设置的条件函数，对数据的更新、删除、查询做动态的筛选。常用于数据权限方面。
比如根据不同权限获取不同数据，用户只能看到自己的数据，管理员能看到所有人的数据，我们通常需要在每一个查询、更新、删除的 sql 操作上都追加上某个条件，这种操作比较机械化，而且某些情况下很容易忘记，可以抽象成注解直接配置到 Entity 上，就省去了每个数据操作关心这个特殊条件了。
/**
* congfig中注册动态条件拦截器【1.3.0之前的版本（不包括1.3.0）可以忽略，不注册该Bean】
*/
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
// 添加动态条件，若同时添加了其他的拦截器，继续添加即可
interceptor.addInnerInterceptor(new DynamicConditionInterceptor());
// 如果使用了分页，请放在DynamicConditionInterceptor之后
interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
return interceptor;
}
@Data
@Table(comment = "文章")
public class Article {
@ColumnComment("主键")
private String id;
@ColumnComment("标题")
private String title;
@ColumnComment("内容")
private String content;
@ColumnComment("发布人")
// 添加了该注解后，针对文章的查询、修改、删除操作，均会被自动带上 published_user_id=?或者published_user_id in (?)的条件，?值来自于CurrentUserDynamicConditionHandler的values()返回值
@DynamicCondition(CurrentUserDynamicConditionHandler.class)
private String publishedUserId;
// 省略其他字段
......
}
@Component
public class CurrentUserDynamicConditionHandler implements IDynamicConditionHandler {
@Resource
private HttpServletRequest request;
@Override
public List<Object> values() {
// 只有当enable()返回true的时候 本动态条件才生效。
// 返回空集合或者null的时候，sql上体现的是 [column] is null，只返回一个值的时候sql上体现的是 [column]=***，
// 返回集合的时候，sql上体现的是 [column] in (***)
String userId = request.getHeader("USER_ID");
return Collections.singletonList(userId);
}
@Override
public boolean enable() {
// 简单例子：header中取用户权限，如果是非管理员则执行该过滤条件，如果是管理员默认查全部，返回false，本动态条件失效
String userRule = request.getHeader("USER_ROLE");
return !"ADMIN".equals(userRule);
}
}
具体用法及讲解，请移步官方文档
八、字段序列化与反序列化
数据存储的时候自动序列化字段上的复杂数据类型为字符串（类 json 格式），数据读取的时候自动反序列化回来，无需额外编写转化的 Handler（MP 官方的方案，需要手动为每一个复杂数据类型指定一个 BaseTypeHandler）。
该方案存在一定的局限性，实际是借鉴了 Redisson 的一种数据序列化方案，将数据本身的特征（类全名称）在序列化的时候，一并记录下来，用于反序列的依据，所以序列化之后的字符串并不是一个标准的 json。这种方案的缺点很明显，就是类的全名称（包名 + 类名）不能随意更改，因为一旦更改，会导致找不到 class 的问题，进而无法正常的反序列化已经存在的数据。
@Data
@TableName(autoResultMap = true) // 必须
@Table(comment = "用户")
public class Users {
@ColumnComment("ID")
private Long id;
@Serializable // 必须
@ColumnComment("爱好")
private List<Like> likes;
}
@Data
public class Like {
private String id;
private String name;
}
感谢
感谢 dromara.org 开源社区提供的机会
感谢支持的小伙伴
作者介绍
90 年，男，已婚，前后端均有涉猎，毕业后一直在济南这座城市，如果有同地区的小伙伴随时可约
