首页
/ 三步掌握MyBatis-Flex：零基础通关ORM框架开发

三步掌握MyBatis-Flex：零基础通关ORM框架开发

2026-04-10 09:43:16作者：柯茵沙
mybatis-flex
mybatis-flex is an elegant Mybatis Enhancement Framework
项目地址：https://gitcode.com/gh_mirrors/my/mybatis-flex

MyBatis-Flex是一个基于MyBatis的增强工具，它以"优雅SQL构建"、"零XML配置"和"高性能数据访问"为核心特性，为开发者提供了更加灵活高效的数据访问解决方案。作为MyBatis的增强框架，MyBatis-Flex既保留了MyBatis的灵活性，又通过创新的查询构造器和代码生成工具显著提升了开发效率，让开发者能够专注于业务逻辑而非重复的SQL编写工作。

核心价值解析：为什么选择MyBatis-Flex

MyBatis-Flex就像一位"数据库翻译官"，能够将面向对象的Java代码自动转换为高效的SQL语句，同时保留开发者对SQL的完全控制权。这种"半自动化"的设计理念，既避免了全自动化ORM框架的黑盒操作，又解决了原生MyBatis需要大量XML配置的繁琐问题。

核心价值点解析

  • 开发效率提升：通过APT技术自动生成表结构定义类，配合链式查询构造器，将CRUD操作代码量减少60%以上
  • 性能优化内置：内置的SQL优化器能自动处理查询条件，避免N+1查询问题，比传统MyBatis提升20-30%查询性能
  • 灵活扩展机制：支持自定义SQL模板、字段处理器和数据类型转换器，满足复杂业务场景需求

💡 小贴士：如果你正在使用MyBatis但苦于频繁编写XML映射文件，或者使用JPA却需要更精细的SQL控制，MyBatis-Flex将是理想的折中选择。

环境配置指南：5分钟搭建开发环境

开发环境准备

确保你的开发环境满足以下要求：

  • JDK 8或更高版本
  • Maven 3.6+构建工具
  • Spring Boot 2.x/3.x（根据项目需求选择）
  • 任意关系型数据库（本文以MySQL为例）

项目初始化与依赖配置

首先创建一个Spring Boot项目，然后在pom.xml中添加以下核心依赖：

<dependencies>
    <!-- MyBatis-Flex Spring Boot启动器 -->
    <dependency>
        <groupId>com.mybatis-flex</groupId>
        <artifactId>mybatis-flex-spring-boot-starter</artifactId>
        <version>1.10.9</version>
    </dependency>
    
    <!-- MySQL驱动 -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- 数据库连接池 -->
    <dependency>
        <groupId>com.zaxxer</groupId>
        <artifactId>HikariCP</artifactId>
    </dependency>
    
    <!-- Lombok简化代码 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

⚠️ 注意：如果使用Spring Boot 3.x版本，请将mybatis-flex-spring-boot-starter替换为mybatis-flex-spring-boot3-starter

数据库配置

在application.yml中添加数据源配置：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/flex_demo?useSSL=false&serverTimezone=UTC
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

# MyBatis-Flex配置
mybatis-flex:
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true

APT配置（关键步骤）

MyBatis-Flex使用APT(Annotation Processing Tool)在编译期生成表结构定义类，需要在pom.xml中添加APT处理器依赖：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.mybatis-flex</groupId>
                        <artifactId>mybatis-flex-processor</artifactId>
                        <version>1.10.9</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

配置完成后，记得将生成的源代码目录标记为"生成的源代码根目录"，这一步在IDEA中如图所示：

MyBatis-Flex生成源代码目录配置

📌 经验值+1：正确配置APT是使用MyBatis-Flex的关键步骤，它能自动生成TableDef类，避免手写表字段常量的繁琐工作。

实战案例教学：构建完整数据访问层

第一步：创建数据库表

首先创建一个简单的用户表用于演示：

CREATE TABLE IF NOT EXISTS `tb_user` (
    `id`          BIGINT PRIMARY KEY auto_increment,
    `username`    VARCHAR(50) NOT NULL COMMENT '用户名',
    `age`         INT COMMENT '年龄',
    `email`       VARCHAR(100) COMMENT '邮箱',
    `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `status`      TINYINT DEFAULT 1 COMMENT '状态(1:正常,0:禁用)'
);

-- 插入测试数据
INSERT INTO tb_user(username, age, email) VALUES 
('张三', 25, 'zhangsan@example.com'),
('李四', 30, 'lisi@example.com'),
('王五', 28, 'wangwu@example.com');

第二步：定义实体类

创建与数据库表对应的实体类，使用MyBatis-Flex注解标记表名和字段：

package com.example.entity;

import com.mybatisflex.annotation.Id;
import com.mybatisflex.annotation.Table;
import com.mybatisflex.annotation.Column;
import lombok.Data;
import java.util.Date;

@Data
@Table("tb_user")  // 指定对应的数据库表名
public class User {
    
    @Id(keyType = com.mybatisflex.annotation.KeyType.Auto)  // 主键自增
    private Long id;
    
    private String username;
    
    private Integer age;
    
    @Column("email")  // 字段名与属性名一致时可省略
    private String email;
    
    @Column("create_time")
    private Date createTime;
    
    private Integer status;
}

第三步：创建Mapper接口

创建Mapper接口并继承BaseMapper，无需编写任何方法即可获得CRUD能力：

package com.example.mapper;

import com.example.entity.User;
import com.mybatisflex.core.BaseMapper;

public interface UserMapper extends BaseMapper<User> {
    // 继承BaseMapper后自动获得CRUD操作，无需编写方法
}

第四步：配置Mapper扫描

在Spring Boot启动类上添加@MapperScan注解指定Mapper接口所在包：

package com.example;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@MapperScan("com.example.mapper")  // 扫描Mapper接口
public class MybatisFlexDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(MybatisFlexDemoApplication.class, args);
    }
}

第五步：实现业务逻辑

创建Service层实现业务逻辑，演示MyBatis-Flex的核心查询功能：

package com.example.service;

import com.example.entity.User;
import com.example.entity.table.UserTableDef;
import com.example.mapper.UserMapper;
import com.mybatisflex.core.query.QueryWrapper;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper;
    
    // 基本查询示例
    public List<User> getUsersByAge(int minAge, int maxAge) {
        // 使用条件构造器构建查询条件
        QueryWrapper query = QueryWrapper.create()
            .where(UserTableDef.USER.AGE.between(minAge, maxAge))
            .and(UserTableDef.USER.STATUS.eq(1))
            .orderBy(UserTableDef.USER.CREATE_TIME.desc());
            
        // 执行查询并返回结果
        return userMapper.selectListByQuery(query);
    }
    
    // 新增用户示例
    public boolean saveUser(User user) {
        return userMapper.insert(user) > 0;
    }
    
    // 复杂查询示例 - 流式API风格
    public User getUserByEmail(String email) {
        return userMapper.selectOneByQuery(QueryWrapper.create()
            .select()
            .from(UserTableDef.USER)
            .where(UserTableDef.USER.EMAIL.eq(email))
            .and(UserTableDef.USER.STATUS.eq(1)));
    }
    
    // 动态更新示例 - 只更新非空字段
    public boolean updateSelective(User user) {
        return userMapper.update(user, QueryWrapper.create()
            .set(UserTableDef.USER.USERNAME, user.getUsername())
            .set(UserTableDef.USER.AGE, user.getAge())
            .where(UserTableDef.USER.ID.eq(user.getId())));
    }
}

第六步：编写测试用例

创建测试类验证功能是否正常工作：

package com.example.service;

import com.example.entity.User;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import java.util.List;
import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest
class UserServiceTest {

    @Autowired
    private UserService userService;
    
    @Test
    void testGetUsersByAge() {
        List<User> users = userService.getUsersByAge(20, 30);
        assertNotNull(users);
        assertFalse(users.isEmpty());
        users.forEach(user -> {
            assertTrue(user.getAge() >= 20 && user.getAge() <= 30);
            assertEquals(1, user.getStatus());
        });
    }
    
    @Test
    void testSaveAndGetUser() {
        // 创建新用户
        User user = new User();
        user.setUsername("测试用户");
        user.setAge(26);
        user.setEmail("test@example.com");
        
        // 保存用户
        assertTrue(userService.saveUser(user));
        assertNotNull(user.getId());  // 验证ID已自动生成
        
        // 查询用户
        User savedUser = userService.getUserByEmail("test@example.com");
        assertNotNull(savedUser);
        assertEquals("测试用户", savedUser.getUsername());
    }
}

📌 经验值+1：MyBatis-Flex的条件构造器支持链式调用和流式API两种风格，可根据个人习惯选择使用，推荐在复杂查询中使用流式API以提高可读性。

进阶技巧探索：释放框架全部潜力

代码生成器：一键生成全套代码

MyBatis-Flex提供了强大的代码生成器，能够根据数据库表结构自动生成实体类、Mapper接口、Service等代码。以下是使用代码生成器的示例配置：

public class CodeGenerator {
    public static void main(String[] args) {
        // 配置数据源
        DataSource dataSource = DataSourceBuilder
            .create()
            .driverClassName("com.mysql.cj.jdbc.Driver")
            .url("jdbc:mysql://localhost:3306/flex_demo")
            .username("root")
            .password("your_password")
            .build();
            
        // 创建配置
        GlobalConfig globalConfig = new GlobalConfig();
        
        // 设置包名
        PackageConfig packageConfig = new PackageConfig();
        packageConfig.setBasePackage("com.example");
        packageConfig.setEntity("entity");
        packageConfig.setMapper("mapper");
        packageConfig.setService("service");
        packageConfig.setServiceImpl("service.impl");
        
        globalConfig.setPackageConfig(packageConfig);
        
        // 设置生成策略
        StrategyConfig strategyConfig = new StrategyConfig();
        strategyConfig.setTablePrefix("tb_");  // 表前缀
        strategyConfig.setEntityLombokModel(true);  // 使用Lombok
        strategyConfig.setLogicDeleteColumn("status");  // 逻辑删除字段
        
        globalConfig.setStrategyConfig(strategyConfig);
        
        // 执行生成
        Generator generator = new Generator(dataSource, globalConfig);
        generator.generate();
    }
}

MyBatis-Flex还提供了IDEA插件"mybatis-flex-helper"，通过图形界面配置代码生成参数，如图所示：

MyBatis-Flex代码生成器配置界面

💡 小贴士：使用代码生成器时，建议先设计好数据库表结构，然后通过生成器一键创建基础代码，再根据业务需求进行调整，可节省80%的重复编码工作。

动态表名：轻松实现分表功能

MyBatis-Flex支持动态表名功能，特别适合分表场景。实现方式如下：

// 1. 定义表名处理器
public class DynamicTableNameProcessor implements IDynamicTableProcessor {
    @Override
    public String process(String tableName) {
        // 根据业务规则动态修改表名
        if ("tb_order".equals(tableName)) {
            // 例如：按用户ID哈希分表
            Long userId = UserContext.getUserId();
            return tableName + "_" + (userId % 10);
        }
        return tableName;
    }
}

// 2. 注册表名处理器
@Configuration
public class MyBatisFlexConfig {
    @Bean
    public FlexConfigurationCustomizer flexConfigurationCustomizer() {
        return configuration -> {
            configuration.setDynamicTableProcessor(new DynamicTableNameProcessor());
        };
    }
}

乐观锁实现：一行注解搞定并发控制

MyBatis-Flex内置乐观锁支持，只需在实体类的版本字段上添加@Version注解：

@Data
@Table("tb_product")
public class Product {
    @Id(keyType = KeyType.Auto)
    private Long id;
    
    private String name;
    
    private Integer stock;
    
    @Version  // 乐观锁注解
    private Integer version;
}

更新时会自动检查版本号，实现并发控制：

// 乐观锁更新示例
public boolean updateProductStock(Long id, int quantity) {
    Product product = new Product();
    product.setId(id);
    product.setStock(quantity);
    
    // 执行更新，MyBatis-Flex会自动处理版本检查
    return productMapper.update(product) > 0;
}

📌 经验值+1：乐观锁适用于读多写少的场景，能有效提高并发性能，避免悲观锁带来的性能问题。

多数据源配置：轻松切换数据源

MyBatis-Flex支持多数据源，可通过注解灵活切换：

// 1. 配置多数据源
@Configuration
public class DataSourceConfig {
    @Bean
    @ConfigurationProperties("spring.datasource.master")
    public DataSource masterDataSource() {
        return DataSourceBuilder.create().type(HikariDataSource.class).build();
    }
    
    @Bean
    @ConfigurationProperties("spring.datasource.slave")
    public DataSource slaveDataSource() {
        return DataSourceBuilder.create().type(HikariDataSource.class).build();
    }
    
    @Bean
    public DataSource dataSource() {
        return new FlexDataSource()
            .addDataSource("master", masterDataSource())
            .addDataSource("slave", slaveDataSource())
            .setDefaultDataSourceKey("master");
    }
}

// 2. 在Service方法上指定数据源
@Service
public class ProductService {
    @Autowired
    private ProductMapper productMapper;
    
    // 使用主库写操作
    public boolean saveProduct(Product product) {
        return productMapper.insert(product) > 0;
    }
    
    // 使用从库读操作
    @UseDataSource("slave")
    public Product getProductById(Long id) {
        return productMapper.selectById(id);
    }
}

避坑指南：常见问题与解决方案

对比选型：MyBatis-Flex vs MyBatis-Plus vs JPA

特性 MyBatis-Flex MyBatis-Plus JPA
设计理念 半自动化ORM，保留SQL控制能力 全自动化CRUD，简化开发 全自动化ORM，面向对象
性能 优秀，接近原生MyBatis 良好，但有额外性能开销 一般，复杂查询性能较差
灵活性 高，支持复杂SQL和自定义查询 中，部分复杂查询需写SQL 低，复杂查询需JPQL或原生SQL
学习曲线 平缓，SQL经验可复用 平缓，API设计友好 陡峭，需学习JPQL和规范
代码侵入性 低，仅需少量注解 中，需继承特定基类 高，需遵循JPA规范

常见问题解决方案

问题1：字段名与属性名映射问题

症状：查询结果中某些字段为null，但数据库中有值。

解决方案：

  1. 使用@Column注解显式指定字段名：
@Column("user_name")
private String userName;
  1. 配置全局下划线转驼峰命名规则：
mybatis-flex:
  configuration:
    map-underscore-to-camel-case: true

问题2：APT未生成TableDef类

症状：编译时提示"找不到符号UserTableDef"。

解决方案：

  1. 检查APT依赖是否正确配置
  2. 确保实体类添加了@Table注解
  3. 在IDEA中执行"Build -> Rebuild Project"
  4. 确认generated-sources目录已标记为"Generated Sources Root"

问题3：分页查询总条数为0

症状：分页查询返回结果正确，但total为0。

解决方案： MyBatis-Flex分页需要单独配置分页拦截器：

@Configuration
public class MyBatisConfig {
    @Bean
    public PaginationInterceptor paginationInterceptor() {
        return new PaginationInterceptor();
    }
}

⚠️ 注意：分页查询时必须使用Page对象作为方法参数，而不是自己构造limit条件。

下一步学习路径与社区资源

进阶学习路径

  1. 核心功能深入：

    • 高级查询构造器用法
    • 自定义类型处理器
    • 拦截器开发

  2. 性能优化：

    • 缓存策略配置
    • SQL优化技巧
    • 批量操作最佳实践

  3. 企业级特性：

    • 多租户实现方案
    • 读写分离配置
    • 分布式事务支持

社区资源导航

  • 官方文档：项目中的docs目录包含完整文档
  • 示例代码：项目中的mybatis-flex-test目录提供各种场景的示例
  • 代码生成器：使用mybatis-flex-codegen模块生成基础代码
  • 常见问题：参考项目中的changes.md文件了解版本变化和常见问题

💡 小贴士：参与社区讨论是提升技能的有效方式，你可以通过项目中的交流群获取帮助和分享经验。

通过本文的学习，你已经掌握了MyBatis-Flex的核心用法和最佳实践。这个强大的ORM框架将帮助你在日常开发中编写更少的代码，同时保持对SQL的完全控制。随着使用的深入，你会发现更多隐藏的功能和优化技巧，让数据访问层的开发变得更加高效和愉悦。

祝你在MyBatis-Flex的学习之路上越走越远，构建出更优秀的Java应用！

mybatis-flex
mybatis-flex is an elegant Mybatis Enhancement Framework
项目地址：https://gitcode.com/gh_mirrors/my/mybatis-flex
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
27
14
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
658
4.26 K
pytorchpytorch
Ascend Extension for PyTorch
Python
502
606
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
939
862
Oohos_react_native
React Native鸿蒙化仓库
JavaScript
334
378
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
390
284
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
123
195
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
180
258
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.54 K
892
MindSpeed-LLMMindSpeed-LLM
昇腾LLM分布式训练框架
Python
142
168