MyBatis Plus 速查表
本文档提供 MyBatis Plus 常用 API 的快速参考。
依赖配置
Spring Boot 2.x：
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.5.15</version>
</dependency>
Spring Boot 3.x：
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-spring-boot3-starter</artifactId>
<version>3.5.15</version>
</dependency>
Spring Boot 4.x：
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-spring-boot4-starter</artifactId>
<version>3.5.15</version>
</dependency>
常用注解
@TableName("t_user") // 指定表名
@TableId(type = IdType.AUTO) // 主键策略：AUTO、INPUT、ASSIGN_ID、ASSIGN_UUID
@TableField("user_name") // 指定字段名
@TableField(exist = false) // 非数据库字段
@TableField(fill = FieldFill.INSERT) // 插入时自动填充
@TableField(fill = FieldFill.INSERT_UPDATE) // 插入和更新时自动填充
@TableLogic // 逻辑删除字段
@Version // 乐观锁字段
BaseMapper 方法
插入
int insert(T entity); // 插入一条记录
删除
int deleteById(Serializable id); // 根据 ID 删除
int deleteByMap(Map<String, Object> map); // 根据 map 条件删除
int delete(Wrapper<T> wrapper); // 根据条件删除
int deleteBatchIds(Collection<?> ids); // 根据 ID 批量删除
更新
int updateById(T entity); // 根据 ID 更新（只更新非 null 字段）
int update(T entity, Wrapper<T> wrapper); // 根据条件更新
查询
T selectById(Serializable id); // 根据 ID 查询
List<T> selectBatchIds(Collection<?> ids); // 根据 ID 批量查询
List<T> selectByMap(Map<String, Object> map); // 根据 map 条件查询
T selectOne(Wrapper<T> wrapper); // 根据条件查询一条（多条会抛异常）
List<T> selectList(Wrapper<T> wrapper); // 根据条件查询列表
Long selectCount(Wrapper<T> wrapper); // 根据条件查询总数（自 3.4.3.2 返回 Long）
List<Map<String, Object>> selectMaps(Wrapper<T> wrapper); // 查询返回 Map 列表
List<Object> selectObjs(Wrapper<T> wrapper); // 只返回第一个字段的值
IPage<T> selectPage(IPage<T> page, Wrapper<T> wrapper); // 分页查询
IPage<Map<String, Object>> selectMapsPage(IPage<T> page, Wrapper<T> wrapper); // 分页返回 Map
IService 方法
保存
boolean save(T entity); // 插入一条
boolean saveBatch(Collection<T> list); // 批量插入
boolean saveBatch(Collection<T> list, int batchSize); // 批量插入（指定批次大小）
boolean saveOrUpdate(T entity); // 存在更新，不存在插入
boolean saveOrUpdateBatch(Collection<T> list); // 批量存在更新，不存在插入
删除
boolean removeById(Serializable id); // 根据 ID 删除
boolean removeByIds(Collection<?> ids); // 根据 ID 批量删除
boolean removeByMap(Map<String, Object> map); // 根据 map 条件删除
boolean remove(Wrapper<T> wrapper); // 根据条件删除
更新
boolean updateById(T entity); // 根据 ID 更新
boolean update(T entity, Wrapper<T> wrapper); // 根据条件更新
boolean updateBatchById(Collection<T> list); // 批量更新
boolean updateBatchById(Collection<T> list, int batchSize); // 批量更新（指定批次大小）
查询
T getById(Serializable id); // 根据 ID 查询
List<T> listByIds(Collection<?> ids); // 根据 ID 批量查询
List<T> listByMap(Map<String, Object> map); // 根据 map 条件查询
T getOne(Wrapper<T> wrapper); // 根据条件查询一条（多条会抛异常）
T getOne(Wrapper<T> wrapper, boolean throwEx); // throwEx=false 时返回第一条
Map<String, Object> getMap(Wrapper<T> wrapper); // 查询返回 Map
List<T> list(); // 查询所有
List<T> list(Wrapper<T> wrapper); // 根据条件查询列表
List<Map<String, Object>> listMaps(); // 查询所有返回 Map
List<Map<String, Object>> listMaps(Wrapper<T> wrapper); // 条件查询返回 Map
long count(); // 总数
long count(Wrapper<T> wrapper); // 根据条件查询总数
IPage<T> page(IPage<T> page); // 分页查询所有
IPage<T> page(IPage<T> page, Wrapper<T> wrapper); // 分页查询
IPage<Map<String, Object>> pageMaps(IPage<T> page); // 分页返回 Map
链式查询
// 获取 LambdaQueryWrapper
LambdaQueryChainWrapper<T> lambdaQuery();
// 示例：链式查询
List<User> users = userService.lambdaQuery()
.eq(User::getAge, 25)
.like(User::getName, "张")
.list();
链式更新
// 获取 LambdaUpdateWrapper
LambdaUpdateChainWrapper<T> lambdaUpdate();
// 示例：链式更新
boolean success = userService.lambdaUpdate()
.eq(User::getId, 1L)
.set(User::getName, "新名字")
.update();
条件构造器
比较操作
eq(String column, Object val) // 等于 =
ne(String column, Object val) // 不等于 <>
gt(String column, Object val) // 大于 >
ge(String column, Object val) // 大于等于 >=
lt(String column, Object val) // 小于 <
le(String column, Object val) // 小于等于 <=
between(String column, Object v1, Object v2) // BETWEEN
notBetween(String column, Object v1, Object v2) // NOT BETWEEN
isNull(String column) // IS NULL
isNotNull(String column) // IS NOT NULL
模糊查询
like(String column, Object val) // LIKE '%值%'
notLike(String column, Object val) // NOT LIKE '%值%'
likeLeft(String column, Object val) // LIKE '%值'
likeRight(String column, Object val) // LIKE '值%'
范围查询
in(String column, Collection<?> coll) // IN
in(String column, Object... values) // IN
notIn(String column, Collection<?> coll) // NOT IN
notIn(String column, Object... values) // NOT IN
inSql(String column, String inValue) // IN SQL
notInSql(String column, String inValue) // NOT IN SQL
分组排序
groupBy(String... columns) // GROUP BY
orderByAsc(String... columns) // ORDER BY ASC
orderByDesc(String... columns) // ORDER BY DESC
orderBy(boolean condition, boolean isAsc, String... columns) // ORDER BY
having(String sqlHaving, Object... params) // HAVING
逻辑连接
and(Consumer<Param> consumer) // AND 嵌套
or() // OR
or(Consumer<Param> consumer) // OR 嵌套
nested(Consumer<Param> consumer) // 正常嵌套 不带 AND OR
apply(String applySql, Object... params) // 拼接 SQL
last(String lastSql) // 拼接在 SQL 末尾
exists(String existsSql) // EXISTS
notExists(String notExistsSql) // NOT EXISTS
Lambda 方式
// 使用 Lambda 表达式，避免字段名硬编码
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(User::getName, "张三")
.gt(User::getAge, 20)
.like(User::getEmail, "example")
.orderByDesc(User::getCreateTime);
条件判断
// 所有方法都支持条件参数
eq(boolean condition, String column, Object val)
// 示例
wrapper.eq(name != null, User::getName, name)
.ge(minAge != null, User::getAge, minAge)
.le(maxAge != null, User::getAge, maxAge);
UpdateWrapper
LambdaUpdateWrapper<User> wrapper = new LambdaUpdateWrapper<>();
wrapper.eq(User::getId, 1L)
.set(User::getName, "新名字") // 设置字段值
.set(User::getAge, null) // 设置为 NULL
.setSql("age = age + 1"); // 自定义 SQL
分页查询
配置分页插件
@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
return interceptor;
}
}
使用分页
Page<User> page = new Page<>(1, 10);
LambdaQueryWrapper<User> wrapper = new LambdaQueryWrapper<>();
wrapper.gt(User::getAge, 20);
IPage<User> result = userMapper.selectPage(page, wrapper);
result.getCurrent(); // 当前页码
result.getSize(); // 每页大小
result.getTotal(); // 总记录数
result.getPages(); // 总页数
result.getRecords(); // 数据列表
result.hasPrevious(); // 是否有上一页
result.hasNext(); // 是否有下一页
自动填充
@Component
public class MyMetaObjectHandler implements MetaObjectHandler {
@Override
public void insertFill(MetaObject metaObject) {
this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
}
@Override
public void updateFill(MetaObject metaObject) {
this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
}
}
逻辑删除
mybatis-plus:
global-config:
db-config:
logic-delete-field: deleted
logic-delete-value: 1
logic-not-delete-value: 0
@TableLogic
private Integer deleted;
乐观锁
@Configuration
public class MybatisPlusConfig {
@Bean
public MybatisPlusInterceptor mybatisPlusInterceptor() {
MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
return interceptor;
}
}
@Data
public class User {
@Version
private Integer version;
}
常用配置
mybatis-plus:
configuration:
log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 打印 SQL
map-underscore-to-camel-case: true # 驼峰转换
global-config:
db-config:
id-type: auto # 主键策略
table-prefix: t_ # 表名前缀
logic-delete-field: deleted # 逻辑删除字段
logic-delete-value: 1 # 逻辑删除值
logic-not-delete-value: 0 # 逻辑未删除值
mapper-locations: classpath*:/mapper/**/*.xml # XML 位置
type-aliases-package: com.example.entity # 实体类包
Db 静态工具类
Db 类是 MyBatis Plus 提供的静态工具类，可以在不注入 Mapper 或 Service 的情况下直接执行 CRUD 操作。适用于工具类、测试代码等场景。
import com.baomidou.mybatisplus.extension.toolkit.Db;
// 插入
boolean success = Db.save(user);
// 根据 ID 查询
User user = Db.getById(1L, User.class);
// 条件查询
List<User> users = Db.lambdaQuery(User.class)
.eq(User::getAge, 25)
.list();
// 条件更新
boolean success = Db.lambdaUpdate(User.class)
.eq(User::getId, 1L)
.set(User::getName, "新名字")
.update();
// 条件删除
boolean success = Db.lambdaUpdate(User.class)
.eq(User::getAge, 0)
.remove();
// 批量插入
boolean success = Db.saveBatch(userList);
// 分页查询
IPage<User> page = Db.page(new Page<>(1, 10), User.class);