Java MyBatis-Flex 实战指南：从 BaseMapper 到 QueryWrapper 的轻量 ORM 用法

简介

MyBatis-Flex 是一个基于 MyBatis 的增强框架。

它的定位很直接：

1保留 MyBatis 写 SQL 的灵活性，同时补上通用 CRUD、链式查询、分页、逻辑删除、乐观锁等常用能力。
2

普通 MyBatis 项目里，常见代码结构是：

1Entity
2Mapper 接口
3Mapper XML
4Service
5Controller
6

如果只是做一张表的增删改查，也要写不少重复 SQL。

MyBatis-Flex 的思路是：

1简单 CRUD 交给 BaseMapper
2复杂条件交给 QueryWrapper
3特别复杂的 SQL 仍然可以回到 MyBatis 原生 XML 或注解 SQL
4

一句话概括：

1MyBatis-Flex 是一个轻量的 MyBatis 增强工具，适合需要 SQL 控制感，又想减少重复 CRUD 代码的项目。
2

MyBatis-Flex 解决什么问题

先看普通 MyBatis 的单表查询。

Mapper 接口：

1public interface UserMapper {
2    User selectById(Long id);
3}
4

XML：

1<select id="selectById" resultType="com.example.entity.User">
2    select id, username, email, age, status, created_at
3    from tb_user
4    where id = #{id}
5</select>
6

新增、修改、删除、分页、条件查询都继续写 SQL。

这种方式很灵活，但简单操作会显得重复。

MyBatis-Flex 的写法是：

1public interface UserMapper extends BaseMapper<User> {
2}
3

然后直接使用：

1User user = userMapper.selectOneById(1L);
2

这类基础方法由 BaseMapper 提供。

如果需要条件查询：

1QueryWrapper query = QueryWrapper.create()
2        .where(USER.AGE.ge(18))
3        .and(USER.STATUS.eq("ACTIVE"))
4        .orderBy(USER.ID.desc());
5
6List<User> users = userMapper.selectListByQuery(query);
7

这就是 MyBatis-Flex 的核心体验：

1单表 CRUD 少写 SQL
2条件查询用链式 API
3复杂 SQL 仍然保留 MyBatis 原生能力
4

核心概念

学习 MyBatis-Flex 时，先抓住几个关键词。

其中最常用的是：

1@Table + @Id + BaseMapper + QueryWrapper
2

Maven 依赖

MyBatis-Flex 需要根据 Spring Boot 版本选择不同 starter。

Spring Boot 2.x：

1<dependency>
2    <groupId>com.mybatis-flex</groupId>
3    <artifactId>mybatis-flex-spring-boot-starter</artifactId>
4    <version>1.11.7</version>
5</dependency>
6

Spring Boot 3.x：

1<dependency>
2    <groupId>com.mybatis-flex</groupId>
3    <artifactId>mybatis-flex-spring-boot3-starter</artifactId>
4    <version>1.11.7</version>
5</dependency>
6

数据库驱动以 MySQL 为例：

1<dependency>
2    <groupId>com.mysql</groupId>
3    <artifactId>mysql-connector-j</artifactId>
4    <scope>runtime</scope>
5</dependency>
6

APT 处理器建议放到 annotationProcessorPaths 里：

1<plugin>
2    <groupId>org.apache.maven.plugins</groupId>
3    <artifactId>maven-compiler-plugin</artifactId>
4    <version>3.11.0</version>
5    <configuration>
6        <annotationProcessorPaths>
7            <path>
8                <groupId>com.mybatis-flex</groupId>
9                <artifactId>mybatis-flex-processor</artifactId>
10                <version>1.11.7</version>
11            </path>
12        </annotationProcessorPaths>
13    </configuration>
14</plugin>
15

APT 用来生成表定义类。

比如实体类叫 User，编译后会生成类似这样的类：

1UserTableDef
2

代码里就可以静态导入：

1import static com.example.entity.table.UserTableDef.USER;
2

然后写出：

1USER.ID.eq(1L)
2USER.USERNAME.like("张")
3

数据源配置

application.yml 示例：

1spring:
2  datasource:
3    url: jdbc:mysql://localhost:3306/flex_demo?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8
4    username: root
5    password: 123456
6    driver-class-name: com.mysql.cj.jdbc.Driver
7
8mybatis-flex:
9  print-banner: false
10  configuration:
11    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
12

开发环境可以打开 SQL 日志，便于观察生成的 SQL。

生产环境一般会交给日志系统统一管理。

启动类配置

启动类需要扫描 Mapper。

1import org.mybatis.spring.annotation.MapperScan;
2import org.springframework.boot.SpringApplication;
3import org.springframework.boot.autoconfigure.SpringBootApplication;
4
5@SpringBootApplication
6@MapperScan("com.example.demo.mapper")
7public class MyBatisFlexDemoApplication {
8
9    public static void main(String[] args) {
10        SpringApplication.run(MyBatisFlexDemoApplication.class, args);
11    }
12}
13

也可以在每个 Mapper 接口上加 @Mapper。

项目里 Mapper 较多时，@MapperScan 更省事。

准备演示表

下面用一个用户表做示例。

1DROP TABLE IF EXISTS tb_user;
2
3CREATE TABLE tb_user (
4  id BIGINT PRIMARY KEY AUTO_INCREMENT,
5  username VARCHAR(50) NOT NULL,
6  email VARCHAR(100) NOT NULL,
7  age INT NOT NULL,
8  status VARCHAR(20) NOT NULL,
9  deleted TINYINT NOT NULL DEFAULT 0,
10  created_at DATETIME NOT NULL,
11  updated_at DATETIME NULL
12);
13
14INSERT INTO tb_user (username, email, age, status, deleted, created_at, updated_at) VALUES
15('张三', 'zhangsan@example.com', 20, 'ACTIVE', 0, '2026-01-01 10:00:00', NULL),
16('李四', 'lisi@example.com', 25, 'ACTIVE', 0, '2026-01-02 10:00:00', NULL),
17('王五', 'wangwu@example.com', 17, 'DISABLED', 0, '2026-01-03 10:00:00', NULL);
18

实体类

1package com.example.demo.entity;
2
3import com.mybatisflex.annotation.Column;
4import com.mybatisflex.annotation.Id;
5import com.mybatisflex.annotation.Table;
6import com.mybatisflex.core.keygen.KeyType;
7
8import java.time.LocalDateTime;
9
10@Table("tb_user")
11public class User {
12
13    @Id(keyType = KeyType.Auto)
14    private Long id;
15
16    private String username;
17
18    private String email;
19
20    private Integer age;
21
22    private String status;
23
24    @Column(isLogicDelete = true)
25    private Boolean deleted;
26
27    private LocalDateTime createdAt;
28
29    private LocalDateTime updatedAt;
30
31    public Long getId() {
32        return id;
33    }
34
35    public void setId(Long id) {
36        this.id = id;
37    }
38
39    public String getUsername() {
40        return username;
41    }
42
43    public void setUsername(String username) {
44        this.username = username;
45    }
46
47    public String getEmail() {
48        return email;
49    }
50
51    public void setEmail(String email) {
52        this.email = email;
53    }
54
55    public Integer getAge() {
56        return age;
57    }
58
59    public void setAge(Integer age) {
60        this.age = age;
61    }
62
63    public String getStatus() {
64        return status;
65    }
66
67    public void setStatus(String status) {
68        this.status = status;
69    }
70
71    public Boolean getDeleted() {
72        return deleted;
73    }
74
75    public void setDeleted(Boolean deleted) {
76        this.deleted = deleted;
77    }
78
79    public LocalDateTime getCreatedAt() {
80        return createdAt;
81    }
82
83    public void setCreatedAt(LocalDateTime createdAt) {
84        this.createdAt = createdAt;
85    }
86
87    public LocalDateTime getUpdatedAt() {
88        return updatedAt;
89    }
90
91    public void setUpdatedAt(LocalDateTime updatedAt) {
92        this.updatedAt = updatedAt;
93    }
94}
95

几个重点：

• @Table("tb_user")：实体类对应 tb_user 表
• @Id(keyType = KeyType.Auto)：主键由数据库自增生成
• @Column(isLogicDelete = true)：标记逻辑删除字段
• created_at 会自动映射到 createdAt

Mapper 接口

1package com.example.demo.mapper;
2
3import com.example.demo.entity.User;
4import com.mybatisflex.core.BaseMapper;
5
6public interface UserMapper extends BaseMapper<User> {
7}
8

继承 BaseMapper<User> 后，常见 CRUD 方法就可以直接使用。

新增数据

1User user = new User();
2user.setUsername("赵六");
3user.setEmail("zhaoliu@example.com");
4user.setAge(28);
5user.setStatus("ACTIVE");
6user.setDeleted(false);
7user.setCreatedAt(LocalDateTime.now());
8
9userMapper.insert(user);
10
11System.out.println(user.getId());
12

如果主键配置为自增，插入后主键会回填到实体对象。

常见生成 SQL 大致是：

1insert into tb_user (username, email, age, status, deleted, created_at)
2values (?, ?, ?, ?, ?, ?)
3

根据 ID 查询

1User user = userMapper.selectOneById(1L);
2

对应场景：

1通过主键查一条数据。
2

如果实体配置了逻辑删除字段，查询会自动带上未删除条件。

查询全部

1List<User> users = userMapper.selectAll();
2

实际项目中，selectAll 更适合数据量很小的字典表、配置表。

业务表数据量较大时，通常使用条件查询或分页查询。

修改数据

1User user = new User();
2user.setId(1L);
3user.setEmail("new-zhangsan@example.com");
4user.setUpdatedAt(LocalDateTime.now());
5
6userMapper.update(user);
7

这类写法适合根据实体主键更新。

如果只想更新某些字段，实体里只设置需要修改的字段更清楚。

删除数据

1userMapper.deleteById(1L);
2

如果实体类没有配置逻辑删除，这就是物理删除。

如果实体类配置了：

1@Column(isLogicDelete = true)
2private Boolean deleted;
3

删除会变成更新逻辑删除字段。

大致 SQL 是：

1update tb_user
2set deleted = 1
3where id = ?
4  and deleted = 0
5

逻辑删除后的数据，普通查询会自动过滤。

QueryWrapper 是什么

QueryWrapper 是 MyBatis-Flex 里非常核心的查询构造器。

它用来在 Java 代码里组装 SQL。

普通 SQL：

1select *
2from tb_user
3where age >= 18
4  and status = 'ACTIVE'
5order by id desc
6

QueryWrapper 写法：

1QueryWrapper query = QueryWrapper.create()
2        .where(USER.AGE.ge(18))
3        .and(USER.STATUS.eq("ACTIVE"))
4        .orderBy(USER.ID.desc());
5
6List<User> users = userMapper.selectListByQuery(query);
7

这里的 USER 来自 APT 生成的表定义类。

常见静态导入：

1import static com.example.demo.entity.table.UserTableDef.USER;
2

常见条件写法

等于：

1USER.STATUS.eq("ACTIVE")
2

不等于：

1USER.STATUS.ne("DISABLED")
2

大于：

1USER.AGE.gt(18)
2

大于等于：

1USER.AGE.ge(18)
2

小于：

1USER.AGE.lt(60)
2

模糊查询：

1USER.USERNAME.like("张")
2

范围查询：

1USER.AGE.between(18, 30)
2

IN 查询：

1USER.ID.in(1L, 2L, 3L)
2

排序：

1orderBy(USER.ID.desc())
2

动态条件查询

业务接口里经常会有可选筛选条件。

比如：

1username 可传可不传
2status 可传可不传
3minAge 可传可不传
4

可以这样写：

1public List<User> search(String username, String status, Integer minAge) {
2    QueryWrapper query = QueryWrapper.create()
3            .select()
4            .from(USER);
5
6    if (username != null && !username.isBlank()) {
7        query.and(USER.USERNAME.like(username));
8    }
9
10    if (status != null && !status.isBlank()) {
11        query.and(USER.STATUS.eq(status));
12    }
13
14    if (minAge != null) {
15        query.and(USER.AGE.ge(minAge));
16    }
17
18    query.orderBy(USER.ID.desc());
19
20    return userMapper.selectListByQuery(query);
21}
22

这种写法比手动拼 SQL 字符串更稳。

参数仍然会走预编译绑定，不需要把业务值直接拼到 SQL 里。

查询单个对象

按唯一字段查询：

1public User findByEmail(String email) {
2    QueryWrapper query = QueryWrapper.create()
3            .where(USER.EMAIL.eq(email));
4
5    return userMapper.selectOneByQuery(query);
6}
7

如果数据可能不存在，业务层可以包一层 Optional：

1public Optional<User> findOptionalByEmail(String email) {
2    QueryWrapper query = QueryWrapper.create()
3            .where(USER.EMAIL.eq(email));
4
5    User user = userMapper.selectOneByQuery(query);
6    return Optional.ofNullable(user);
7}
8

查询部分字段

有些接口不需要返回整张表的所有字段。

1QueryWrapper query = QueryWrapper.create()
2        .select(USER.ID, USER.USERNAME, USER.EMAIL)
3        .from(USER)
4        .where(USER.STATUS.eq("ACTIVE"));
5
6List<User> users = userMapper.selectListByQuery(query);
7

这段 SQL 只会查询指定字段。

字段越少，网络传输和对象映射压力越小。

查询单个字段

统计数量：

1QueryWrapper query = QueryWrapper.create()
2        .where(USER.STATUS.eq("ACTIVE"));
3
4long count = userMapper.selectCountByQuery(query);
5

查询第一列：

1QueryWrapper query = QueryWrapper.create()
2        .select(USER.EMAIL)
3        .from(USER)
4        .where(USER.ID.eq(1L));
5
6String email = userMapper.selectObjectByQueryAs(query, String.class);
7

这类写法适合只取一个字段的场景。

分页查询

BaseMapper 提供了 paginate 方法。

1import com.mybatisflex.core.paginate.Page;
2
3public Page<User> pageActiveUsers(int pageNumber, int pageSize) {
4    QueryWrapper query = QueryWrapper.create()
5            .where(USER.STATUS.eq("ACTIVE"))
6            .orderBy(USER.ID.desc());
7
8    return userMapper.paginate(pageNumber, pageSize, query);
9}
10

返回值是 Page<User>。

常用字段：

1Page<User> page = pageActiveUsers(1, 10);
2
3List<User> records = page.getRecords();
4long totalRow = page.getTotalRow();
5long totalPage = page.getTotalPage();
6

分页参数含义：

1pageNumber：当前页，从 1 开始
2pageSize：每页条数
3

第二页以后复用总数

分页查询通常会查两次：

1一次查总数
2一次查当前页数据
3

如果第一页已经拿到总数，第二页以后可以把总数传进去，减少一次 count 查询。

1long totalRow = 120L;
2
3Page<User> page = userMapper.paginate(2, 10, totalRow, query);
4

这个写法适合对性能比较敏感的列表页。

多表查询

准备一张订单表：

1DROP TABLE IF EXISTS tb_order;
2
3CREATE TABLE tb_order (
4  id BIGINT PRIMARY KEY AUTO_INCREMENT,
5  user_id BIGINT NOT NULL,
6  order_no VARCHAR(50) NOT NULL,
7  amount DECIMAL(10, 2) NOT NULL,
8  status VARCHAR(20) NOT NULL,
9  created_at DATETIME NOT NULL
10);
11

实体类：

1@Table("tb_order")
2public class Order {
3
4    @Id(keyType = KeyType.Auto)
5    private Long id;
6
7    private Long userId;
8
9    private String orderNo;
10
11    private BigDecimal amount;
12
13    private String status;
14
15    private LocalDateTime createdAt;
16
17    // getter setter
18}
19

Mapper：

1public interface OrderMapper extends BaseMapper<Order> {
2}
3

定义一个 DTO 接收结果：

1public class OrderUserDTO {
2    private Long orderId;
3    private String orderNo;
4    private BigDecimal amount;
5    private String orderStatus;
6    private Long userId;
7    private String username;
8    private String email;
9
10    // getter setter
11}
12

关联查询：

1import static com.example.demo.entity.table.OrderTableDef.ORDER;
2import static com.example.demo.entity.table.UserTableDef.USER;
3
4public List<OrderUserDTO> findOrderUsers(String orderStatus) {
5    QueryWrapper query = QueryWrapper.create()
6            .select(
7                    ORDER.ID.as("orderId"),
8                    ORDER.ORDER_NO.as("orderNo"),
9                    ORDER.AMOUNT,
10                    ORDER.STATUS.as("orderStatus"),
11                    USER.ID.as("userId"),
12                    USER.USERNAME.as("username"),
13                    USER.EMAIL.as("email")
14            )
15            .from(ORDER)
16            .leftJoin(USER).on(ORDER.USER_ID.eq(USER.ID))
17            .where(ORDER.STATUS.eq(orderStatus))
18            .orderBy(ORDER.ID.desc());
19
20    return orderMapper.selectListByQueryAs(query, OrderUserDTO.class);
21}
22

这种写法适合：

1SQL 不算特别复杂，但又不是简单单表查询。
2

如果 SQL 已经非常复杂，写 XML 也很正常。

MyBatis-Flex 不限制继续使用 MyBatis 原生 XML。

批量插入

1List<User> users = new ArrayList<>();
2
3User user1 = new User();
4user1.setUsername("用户1");
5user1.setEmail("user1@example.com");
6user1.setAge(18);
7user1.setStatus("ACTIVE");
8user1.setDeleted(false);
9user1.setCreatedAt(LocalDateTime.now());
10users.add(user1);
11
12User user2 = new User();
13user2.setUsername("用户2");
14user2.setEmail("user2@example.com");
15user2.setAge(19);
16user2.setStatus("ACTIVE");
17user2.setDeleted(false);
18user2.setCreatedAt(LocalDateTime.now());
19users.add(user2);
20
21userMapper.insertBatch(users);
22

批量操作适合一次写入多条数据。

数据量很大时，可以按固定大小拆批。

1例如每 500 条或 1000 条执行一次。
2

条件删除

删除禁用状态用户：

1QueryWrapper query = QueryWrapper.create()
2        .where(USER.STATUS.eq("DISABLED"));
3
4userMapper.deleteByQuery(query);
5

如果配置了逻辑删除，这里会执行逻辑删除。

如果没有配置逻辑删除，就会执行物理删除。

条件更新

一些更新不方便先查出来再改，可以直接按条件更新。

1User updateEntity = new User();
2updateEntity.setStatus("DISABLED");
3updateEntity.setUpdatedAt(LocalDateTime.now());
4
5QueryWrapper query = QueryWrapper.create()
6        .where(USER.AGE.lt(18));
7
8userMapper.updateByQuery(updateEntity, query);
9