Xbatis 是一个 SpringBoot 应用环境中使用的数据管理框架，它基于 MyBatis 实现，支持 MySQL，可以使用更加 Java 的方式实现业务逻辑中的 CRUD 操作。

安装

下载源码


git clone https://github.com/njdi/durian.git

编译源码


cd durian/

切换至最新版本（Tag），如：0.4，


git checkout 0.4

编译安装至本地 Maven 仓库：


mvn clean package

添加依赖

SpringBoot 项目使用 Xbatis 时，需要在 Maven pom.xml 中添加：


<dependency>

<groupId>io.njdi</groupId>

<artifactId>durian-xbatis</artifactId>

<version>${version}</version>

</dependency>

${version} 替换为具体的版本号，如：0.4。

数据表

数据表 mytable 包含 3 个字段：id、col1 和 col2，


CREATE TABLE `mytable` (

`id` int NOT NULL AUTO_INCREMENT,

`col1` varchar(45) COLLATE utf8mb4_unicode_ci NOT NULL,

`col2` varchar(45) COLLATE utf8mb4_unicode_ci NOT NULL,

PRIMARY KEY (`id`)

) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

其中，字段 id 是主键，且支持自增。

Xbatis 中每一张数据表都要求必须包含一个整数类型的主键字段，名称为 id，且支持自增。

数据源

Xbatis 运行时需要使用 SpringBoot 提供的数据源（DataSource），需要在 application.yml 中添加：


spring:

application:

name: sample

datasource:

url: jdbc:mysql://${host}:${port}/${db}?useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true

username: ${user}

password: ${passwd}

hikari:

keepaliveTime: 30000

maxLifetime: 600000

maximumPoolSize: 30

${...} 替换为具体的数据库信息：

${host}：MySQL 实例地址；
${port}：MySQL 实例端口；
${db}：数据库名称；
${user}：用户名；
${passwd}：密码；

Xbatis

Xbatis 是基于 MyBatis 实现的，运行时相关实例需要以 Bean 的形式注入到 Spring 容器，为保证 Spring 可以正常扫描且实例化这些 Bean，需要作如下配置：

Main


import org.mybatis.spring.annotation.MapperScan;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication

@ComponentScan({"io.njdi.durian.sample.xbatis", "io.njdi.durian.xbatis"})

@MapperScan(basePackages = {"io.njdi.durian.xbatis.core"})

public class Main {

public static void main(String[] args) {

SpringApplication.run(Main.class, args);

}

}

Main 是 SpringBoot 应用的入口类，@ComponentScan 用于指定“去哪里”扫描 Xbatis 的 Bean，“io.njdi.durian.sample.xbatis” 是示例项目的 Bean，“io.njdi.durian.xbatis” 是 Xbatis 项目的 Bean；@MapperScan 用于指定“去哪里”扫描 MyBatis 的 Mapper。

application.xml


mybatis:

mapper-locations: classpath:xbatis.xml

mybatis.mapper-locations 用于指定“去哪里”加载 MyBatis 的配置文件。

XbatisManager

XbatisManager 是数据管理器实例，用以完成 CRUD 相关的具体操作，可以在 Service 或 Dao 层注入此实例：


@Autowired

private XbatisManager xbatisManager;

Database/Table/Column

Xbatis 中也有数据库（Database）、数据表（Table）和数据列（Column）的概念，它们是 业务逻辑 中的库/表/列，相较于 MySQL 中的物理库/表/列，它们拥有更多的业务属性。

Column

Column 用于定义列，它对应着 MySQL 中的一列，包含以下属性：

name

列名称，指业务逻辑中列的名称；如果业务逻辑中列的名称与 MySQL 中对应列的名称不一致，则需要使用列别名（alias）指定。

alias

列别名，指 MySQL 中列的名称；仅列名称与列别名不一致时需要指定。

type

列类型，指业务逻辑中列的数据类型，支持数值和字符串类型，默认为字符串类型（String）。

implicit

列默认查询标识，查询数据表时，如果没有指定需要查询具体哪些列，会使用默认查询列替代，默认为 true。

create

列允许插入标识，指列是否支持插入，默认为 true。

select

列允许查询标识，指列是否支持查询，默认为 true。

update

列允许更新标识，指列是否支持更新，默认为 false。

Column 实例支持通过 Builder 模式进行创建：


Column id = Column.builder().name(COLUMN_MYTABLE_ID).type(Integer.class).create(false).build();

Column colOne = Column.builder().name("colOne").alias("col1").build();

Column colTwo = Column.builder().name("colTwo").alias("col2").build();

其中，id 可使用 type() 指定类型为整数，使用 create() 指定不允许插入；colOne 和 colTwo 可使用 alias() 分别指定别名 col1 和 col2。

Table

Table 用于定义表，它对应着 MySQL 中的一张表，包含以下属性：

name

表名称，指业务逻辑中表的名称；如果业务逻辑中表的名称与 MySQL 中对应表的名称不一致，则需要使用表别名（alias）指定。

alias

表别名，指 MySQL 中表的名称；仅表名称与表别名不一致时需要指定。

columns

列集合，指某表的多个列（Column）。

limit

查询某表时，最多可以返回的记录数目，默认为整数最大值（Integer.MAX_VALUE），即不限制。

create

表允许插入标识，默认为 true。

delete

表允许删除标识，默认为 true。

page

表允许（分页）查询标识，默认为 true。

update

表允许更新标识，默认为 true。

deleteMustHaveWhere

表删除时，必须指定过滤条件标识，默认为 true。

pageMustHaveWhere

表查询时，必须指定过滤条件标识，默认为 true。

updateMustHaveWhere

表更新时，必须指定过滤条件标识，默认为 true。

Table 实例支持通过 Builder 模式进行创建：


Table myTable = Table.builder()

.name("myTable")

.alias("mytable")

.column(id)

.column(colOne)

.column(colTwo)

.build();

使用 alias() 可指定表别名（注意 myTable 和 mytable 的区别）；使用 column() 可添加多个列。

Database

Database 用于定义库，它对应着 MySQL 中的一个数据库，仅包含一个属性：

tables

表集合，指库的多张表（Table）。

Database 实例支持通过 Builder 模式进行创建：


Database database = Database.builder()

.table(myTable)

.build();

使用 table() 可添加多张表。

Database（库）实例可以包含多个 Table（表）实例；Table 实例可以包含多个 Column（列）实例。其中，Database 实例创建完成以后，需要以 Bean 的形式注入 Spring 容器：


import io.njdi.durian.xbatis.model.schema.Column;

import io.njdi.durian.xbatis.model.schema.Database;

import io.njdi.durian.xbatis.model.schema.Table;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

@Configuration

public class DbConfigurer {

public static final String TABLE_MYTABLE = "myTable";

public static final String COLUMN_MYTABLE_ID = "id";

public static final String COLUMN_MYTABLE_COL_ONE = "colOne";

public static final String COLUMN_MYTABLE_COL_TWO = "colTwo";

public Table createTable() {

Column id = Column.builder().name(COLUMN_MYTABLE_ID).type(Integer.class).create(false).build();

Column colOne = Column.builder().name(COLUMN_MYTABLE_COL_ONE).alias("col1").build();

Column colTwo = Column.builder().name(COLUMN_MYTABLE_COL_TWO).alias("col2").build();

return Table.builder()

.name(TABLE_MYTABLE)

.alias("mytable")

.column(id)

.column(colOne)

.column(colTwo)

.build();

}

@Bean

public Database createDatabase() {

Table myTable = createTable();

return Database.builder()

.table(myTable)

.build();

}

}

注意 @Configuration 和 @Bean 两个注解的使用。其中，业务逻辑中的表名和列名均使用公共静态常量（public/static/final）进行声明，方便业务代码引用。

Create/Creates

Create 用于描述插入操作，每一个 Create 实例对应着一条 Insert 语句，如下：


INSERT INTO mytable (col1, col2) VALUES('a', 'b')

Insert 语句包含两部分重要内容：键值对和表名。键值对即列名和列值，如：


col1 -> a

col2 -> b

Pair

在 Xbatis 中键值对是使用 Pair 表示的，每一个 Pair 实例表示一组列名和列值；其中，列名使用属性 name 表示，列值使用属性 value 表示，如：


Pair<String> colOne = Pair.<String>builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.value("a")

.build();

Pair<String> colTwo = Pair.<String>builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_TWO)

.value("b")

.build();

创建一个 Create 实例表示一条 Insert 语句：


String table = DbConfigurer.TABLE_MYTABLE;

Pair<String> colOne = Pair.<String>builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.value("a")

.build();

Pair<String> colTwo = Pair.<String>builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_TWO)

.value("b")

.build();

Create create = Create.builder()

.pair(colOne)

.pair(colTwo)

.table(table)

.build();

创建 Create 实例时，使用了 DbConfigurer 中表名和列名的公共静态常量。

id

id 是 Create 中一个很重要的属性，它要求 MySQL 数据表中的主键字段名称为 id，且必须是自增的；使用 XbatisManager 执行插入操作后，可以获取已插入记录的主键值：


int id = xbatisManager.create(create);

log.info("id: {}", id);

也可以通过 Create 实例获取主键值：


log.info("id: {}", create.getId());

Creates

Creates 实例内部可以添加多个 Create 实例，用于表示多条记录的插入操作。


Creates creates = Creates.builder()

.create(create)

.create(create2)

.build();

List<Integer> ids = xbatisManager.creates(creates);

log.info("ids: {}", ids);

Delete/Deletes

Delete 用于描述删除操作，每一个 Delete 实例对应着一条 Delete 语句，如下：


DELETE FROM mytable WHERE col1 = 'a'

Delete 语句包含两部分重要内容：表名和过滤条件（可选）。

Where

Xbatis 中过滤条件使用 Where 表示，每一个 Where 实例表示一个过滤条件。Where 有四种实现：

Filter（基本过滤器）
OrFilter（逻辑或过滤器）
AndFilter（逻辑与过滤器）
NotFilter（逻辑非过滤器）

Filter

Filter 是基本过滤器的实现，它含有三个属性：

name

列名称。

operator

操作符，支持：EQ（=）, NE（!=）, GT（>）, LT（<）, GE（>=）, LE（<=）, BETWEEN（between ... and ...）, LIKE（like）, IN（in）, NOT_IN（not in）, IS_NULL（is null）, IS_NOT_NULL（is not null）。

values

值列表，根据操作符的不同，可能是零个、一个或多个值。

创建 Filter 实例：


// col1 = 'a'

Filter eq = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.operator(Filter.Operator.EQ)

.value("a")

.build();

// id between 1 and 10

Filter between = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_ID)

.operator(Filter.Operator.BETWEEN)

.value(1)

.value(10)

.build();

// col2 is not null

Filter isNotNull = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_TWO)

.operator(Filter.Operator.IS_NOT_NULL)

.build();

Delete、Page 和 Update 实例均可以添加多个 Filter（Where）实例，多个 Filter 之间的逻辑关系是 And（与）。

OrFilter

OrFilter 逻辑非过滤器，用于表示多个 Filter 之间的逻辑或（Or）关系。

假设需要表示过滤：


col1 = 'a' || col2 is not null

使用 OrFilter：


// col1 = 'a'

Filter eq = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.operator(Filter.Operator.EQ)

.value("a")

.build();

// col2 is not null

Filter isNotNull = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_TWO)

.operator(Filter.Operator.IS_NOT_NULL)

.build();

// col1 = 'a' or col2 is not null

OrFilter orFilter = OrFilter.builder()

.filter(eq)

.filter(isNotNull)

.build();

AndFilter

AndFilter 逻辑与过滤器，用于表示多个 Filter 之间的逻辑与（And）关系，使用场景较少。

NotFilter

NotFilter 逻辑非过滤器，用于表示多个 Filter 之间的逻辑非（Not）关系，使用场景较少。

使用 Where 创建 Delete 实例：


String table = DbConfigurer.TABLE_MYTABLE;

Filter colOne = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.operator(Filter.Operator.EQ)

.value("a")

.build();

Delete delete = Delete.builder()

.table(table)

.where(colOne)

.build();

可以使用 Delete where() 添加多个 Where 实例，它们之间的逻辑关系是与（And）。

执行删除操作：


int rows = xbatisManager.delete(delete);

log.info("rows: {}", rows);

XbatisManager delete() 会返回执行删除操作后所影响的记录行数，也可以使用 Deletes 执行多个删除操作。

Page

Page 用于描述查询操作，每一个 Page 实例对应着一条 Select 语句，它是 Xbatis 中最复杂的结构，包含若干组成部分：

Field（查询字段）
Where（过滤）
Group（分组）
Having（分组过滤）
Order（排序）
limit/offset（分页）

Field

Field 用于描述查询字段部分：


SELECT

select_expr [, select_expr] ...

FROM

table

select_expr 就是查询字段，每一个 Field 实例对应着一个查询字段，它包含两个属性：

name

列名称。

alias

列别名，如果需要为查询的列起一个其它的名称，可以使用列别名指定。

创建 Field 实例：


Field field = Field.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.alias("mycol")

.build();

翻译成 SQL 片段：


SELECT

col1 AS mycol

FROM

table

Where


SELECT

select_expr [, select_expr] ...

FROM

table

WHERE

where_condition

详细内容参考 Delete Where。

Group

列名称集合，每一个列名称表示一个分组字段，直接使用字符串表示。


SELECT

select_expr [, select_expr] ...

FROM

table

WHERE

where_condition

GROUP BY

col_name [, col_name] ...

Having


SELECT

select_expr [, select_expr] ...

FROM

table

WHERE

where_condition

GROUP BY

col_name [, col_name] ...

HAVING

where_condition

详细内容参考 Delete Where。

Order

Order 用于描述排序字段部分：


SELECT

select_expr [, select_expr] ...

FROM

table

WHERE

where_condition

GROUP BY

col_name [, col_name] ...

HAVING

where_condition

ORDER BY order_expr [, order_expr] ...

order_expr 就是排序字段，每一个 Order 实例对应着一个排序字段，它包含两个属性：

name

列名称。

sort

排序，升序（ASC）或降序（DESC）。

创建 Order 实例：


Order order = Order.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.sort(Order.Sort.DESC)

.build();

翻译成 SQL 片段：


ORDER BY col1 DESC

limit/offset

limit 用于限制查询返回的记录行数，offset 用于指定记录偏移量，两者结合可实现分页。


SELECT

select_expr [, select_expr] ...

FROM

table

WHERE

where_condition

GROUP BY

col_name [, col_name] ...

HAVING

where_condition

ORDER BY order_expr [, order_expr] ...

LIMIT limit

OFFSET offset

创建 Page 实例：


Page page = Page.builder()

.field(...)

.table(table)

.where(...)

.group(...)

.having(...)

.order(...)

.limit(...)

.offset(...)

.build();

其中，field()、where()、group()、having()、order() 均可以使用多次。

执行查询操作：


List<Map<String, Object>> rows = xbatisManager.page(page);

log.info("rows: {}", rows);

XbatisManager page() 会返回一个记录集合，使用 List 表示；每一个记录使用一个 Map 表示，Key（String）代表列名称，Value（Object）代表列值。

XbatisManager page() 有一个重载方法，可以直接以对象集合的形式返回查询结果：


public class MyRow {

private Integer id;

private String colOne;

private String colTwo;

}

List<MyRow> rows = xbatisManager.page(page, MyRow.class);

log.info("rows: {}", rows);

每一个 MyRow 实例表示一行记录。注意，MyRow 属性名称及类型必须与列名称及类型一一对应。

id/ids

使用 ID 查询记录是很常见的需求，Xbatis 直接支持这样的查询请求。ID 可以有两种解读：

MySQL 数据表记录中的自增 id
业务逻辑中的唯一记录标识

对于第一种情况：


String table = DbConfigurer.TABLE_MYTABLE;

int id = 106;

MyRow myRow = xbatisManager.id(table, id, MyRow.class);

log.info("id: {}", myRow);

直接使用 id 值查询对应的记录。

对于第二种情况：


String table = DbConfigurer.TABLE_MYTABLE;

String name = "id";

Integer value = 106;

MyRow myRow = xbatisManager.id(table, name, value, MyRow.class);

log.info("id: {}", myRow);

需要特别指定唯一记录标识列的名称 name。

此外，id() 也支持返回 Map 类型的记录。

ids() 可以查询 ID 集合（多个ID）的记录列表。如果 ID 集合中存在重复的 ID，返回的记录列表也会包含重复的记录。

Update/Updates

Update 用于描述更新操作，每一个 Update 实例对应着一条 Update 语句，如下：


UPDATE

mytable

SET

col2 = 'b'

WHERE

col1 = 'a'

Update 语句包含三部分重要内容：表名，键值对（Pair）和过滤条件（Where）；其中，Pair 请参考 Create Pair，Where 请参考 Delete Where。

创建 Update 实例:


String table = DbConfigurer.TABLE_MYTABLE;

Filter filter = Filter.builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_ONE)

.operator(Filter.Operator.EQ)

.value("a")

.build();

Pair<String> pair = Pair.<String>builder()

.name(DbConfigurer.COLUMN_MYTABLE_COL_TWO)

.value("c")

.build();

Update update = Update.builder()

.table(table)

.pair(pair)

.where(filter)

.build();

执行更新操作：


int rows = xbatisManager.update(update);

log.info("rows: {}", rows);

XbatisManager update() 会返回执行更新操作后所影响的记录行数，也可以使用 Updates 执行多个删除操作。

自定义列名称

一般情况下，Field.name、Filter.name 和 Order.name 只能使用已经定义的列名称 Column.name。如果需要使用自定义的列名称，则需要通过 expr 属性额外指定。

以 Field 为例，假设需要查询列 colOne 大写之后的值：


Field field = Field.builder()

.name("UPPER(col1)")

.alias("colOne")

.expr(true)

.build();

注意，使用自定义列名称时，只能引用 MySQL 数据表中的列名，如：col1。

Xbatis：SpringBoot 数据管理框架

安装

下载源码

编译源码

添加依赖

数据表

数据源

Xbatis

XbatisManager

Database/Table/Column

Column

Table

Database

Create/Creates

Pair

id

Creates

Delete/Deletes

Where

Filter

OrFilter

AndFilter

NotFilter

Page

Field

Where

Group

Having

Order

limit/offset

id/ids

Update/Updates

自定义列名称

示例