Fluent Mybatis Tutorial: Overview, Features, and Practical Code Examples

This article introduces the Fluent Mybatis ORM framework, a Mybatis‑enhanced library that combines features of Mybatis‑Plus, Dynamic SQL, and JPA. It explains the design philosophy, highlights, and typical use cases.

Key Highlights

Eliminates the need to write XML mapper files.

Provides a fluent Java API to build complex SQL statements.

Generates code at compile time via an annotation processor.

Typical SQL Requirement

create table `student_score` (
    id           bigint auto_increment comment '主键ID' primary key,
    student_id   bigint            not null comment '学号',
    gender_man   tinyint default 0 not null comment '性别, 0:女; 1:男',
    school_term  int               null comment '学期',
    subject      varchar(30)       null comment '学科',
    score        int               null comment '成绩',
    gmt_create   datetime          not null comment '记录创建时间',
    gmt_modified datetime          not null comment '记录最后修改时间',
    is_deleted   tinyint default 0 not null comment '逻辑删除标识'
) engine = InnoDB default charset=utf8;

The goal is to compute, for the year 2000, the count, minimum, maximum, and average scores of three subjects (English, Math, Chinese) per term, with at least two records per group.

Implementation Comparison

Three approaches are shown: Fluent Mybatis, native Mybatis, and Mybatis‑Plus. The native Mybatis solution requires a mapper interface, a parameter POJO, and an XML select statement, while Mybatis‑Plus reduces boilerplate but still relies on string‑based column names. Fluent Mybatis achieves the same result with a concise fluent API and IDE‑friendly code completion.

Fluent Mybatis Example

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = HelloWorldConfig.class)
public class HelloWorldTest {
    @Autowired
    HelloWorldMapper mapper;

    @Test
    public void testHelloWorld() {
        // delete previous data
        mapper.delete(mapper.query().where.id().eq(1L).end());
        // insert
        HelloWorldEntity entity = new HelloWorldEntity();
        entity.setId(1L);
        entity.setSayHello("hello world");
        entity.setYourName("Fluent Mybatis");
        entity.setIsDeleted(false);
        mapper.insert(entity);
        // query
        HelloWorldEntity result1 = mapper.findOne(mapper.query().where.id().eq(1L).end());
        System.out.println("1. " + result1);
        // update
        mapper.updateBy(mapper.updater()
            .set.sayHello().is("say hello, say hello!")
            .set.yourName().is("Fluent Mybatis is powerful!").end()
            .where.id().eq(1L).end());
        // query after update
        HelloWorldEntity result2 = mapper.findOne(mapper.query()
            .where.sayHello().like("hello")
            .and.isDeleted().eq(false).end()
            .limit(1));
        System.out.println("2. " + result2);
    }
}

The corresponding entity class is annotated with @FluentMybatis and extends RichEntity :

@FluentMybatis
public class HelloWorldEntity extends RichEntity {
    private Long id;
    private String sayHello;
    private String yourName;
    private Date gmtCreated;
    private Date gmtModified;
    private Boolean isDeleted;
    @Override
    public Class
entityClass() { return HelloWorldEntity.class; }
}

Configuration of the data source and Mybatis session factory is done via a Spring @Configuration class, requiring only standard JDBC settings.

After compilation, Fluent Mybatis automatically generates mapper interfaces, base DAO classes, query wrappers, updaters, and helper classes, enabling full CRUD functionality without manual XML or SQL writing.

Conclusion

Fluent Mybatis provides a powerful, type‑safe, and concise way to interact with databases in Java. It reduces boilerplate compared to native Mybatis and Mybatis‑Plus, while offering compile‑time code generation and IDE support.