Sharding-JDBC系列(三):Sharding-JDBC分片配置示例与说明

本篇描述 Sharding-JDBC 的数据分片的多种配置方式,支持 Java API 配置,Yaml 配置,Spring Boot Starter 配置文件配置,Spring XML 命名空间配置

Sharding-JDBC 的配置主要包含系统级属性配置分片属性配置分片算法策略配置,其它的还包括内置分布式序列算法,负载均衡算法,加密算法的配置。

此系列文章都是基于 Sharding-JDBC 4.x版本, 在写此文章时,正式发布的是 4.1.0版本,点此 4.x 官方文档

引入依赖

Sharding-JDBC 数据分片配置方式非常灵活方便。下方内容源自官方文档:[用户手册 > 使用手册I][https://shardingsphere.apache.org/document/legacy/4.x/document/cn/manual/sharding-jdbc/usage/]

下面几种示例都需要引入 Maven 依赖,目前最新的版本是 4.1.0:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<!-- no spring -->
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>shardingsphere-jdbc-core</artifactId>
<version>${shardingsphere.version}</version>
</dependency>

<!-- for spring boot -->
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>sharding-jdbc-spring-boot-starter</artifactId>
<version>${sharding-sphere.version}</version>
</dependency>

<!-- for spring namespace -->
<dependency>
<groupId>org.apache.shardingsphere</groupId>
<artifactId>sharding-jdbc-spring-namespace</artifactId>
<version>${sharding-sphere.version}</version>
</dependency>

使用手册

使用Java API

ShardingSphere-JDBC 的 Java API 通过数据源集合、规则集合以及属性配置组成。 以下示例是根据 user_id 取模分库, 且根据 order_id 取模分表的 2 库 2 表的配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// 配置真实数据源
Map<String, DataSource> dataSourceMap = new HashMap<>();

// 配置第一个数据源
BasicDataSource dataSource1 = new BasicDataSource();
dataSource1.setDriverClassName("com.mysql.jdbc.Driver");
dataSource1.setUrl("jdbc:mysql://localhost:3306/ds0");
dataSource1.setUsername("root");
dataSource1.setPassword("");
dataSourceMap.put("ds0", dataSource1);

// 配置第二个数据源
BasicDataSource dataSource2 = new BasicDataSource();
dataSource2.setDriverClassName("com.mysql.jdbc.Driver");
dataSource2.setUrl("jdbc:mysql://localhost:3306/ds1");
dataSource2.setUsername("root");
dataSource2.setPassword("");
dataSourceMap.put("ds1", dataSource2);

// 配置Order表规则
TableRuleConfiguration orderTableRuleConfig = new TableRuleConfiguration("t_order","ds${0..1}.t_order${0..1}");

// 配置分库 + 分表策略
orderTableRuleConfig.setDatabaseShardingStrategyConfig(new InlineShardingStrategyConfiguration("user_id", "ds${user_id % 2}"));
orderTableRuleConfig.setTableShardingStrategyConfig(new InlineShardingStrategyConfiguration("order_id", "t_order${order_id % 2}"));

// 配置分片规则
ShardingRuleConfiguration shardingRuleConfig = new ShardingRuleConfiguration();
shardingRuleConfig.getTableRuleConfigs().add(orderTableRuleConfig);

// 省略配置order_item表规则...
// ...

// 获取数据源对象
DataSource dataSource = ShardingDataSourceFactory.createDataSource(dataSourceMap, shardingRuleConfig, new Properties());

使用YAML配置

ShardingSphere-JDBC 的 YAML 配置文件 通过数据源集合、规则集合以及属性配置组成。 以下示例是根据 user_id 取模分库, 且根据 order_id 取模分表的 2 库 2 表的配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
dataSources: # 数据源配置
ds0: !!org.apache.commons.dbcp.BasicDataSource
driverClassName: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/ds0
username: root
password:
ds1: !!org.apache.commons.dbcp.BasicDataSource
driverClassName: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/ds1
username: root
password:

shardingRule: # 分片规则
tables:
t_order: # 逻辑表名
actualDataNodes: ds${0..1}.t_order${0..1} #由数据源名 + 表名组成,以小数点分隔。多个表以逗号分隔,支持行表达式。缺省表示使用已知数据源与逻辑表名称生成数据节点,用于广播表(即每个库中都需要一个同样的表用于关联查询,多为字典表)或只分库不分表且所有库的表结构完全一致的情况
databaseStrategy: # 分库策略,缺省表示使用默认分库策略,以下的分片策略只能选其一
inline: # 行表达式方式
shardingColumn: user_id # 分片键
algorithmExpression: ds${user_id % 2} # 算法表达式
tableStrategy: # 分表策略,同分库策略
inline:
shardingColumn: order_id
algorithmExpression: t_order${order_id % 2}
t_order_item: # 关联表
actualDataNodes: ds${0..1}.t_order_item${0..1}
databaseStrategy:
inline:
shardingColumn: user_id
algorithmExpression: ds${user_id % 2}
tableStrategy:
inline:
shardingColumn: order_id
algorithmExpression: t_order_item${order_id % 2}

加载 YAML 文件创建数据源:

1
DataSource dataSource = YamlShardingDataSourceFactory.createDataSource(yamlFile);

使用原生JDBC

通过ShardingDataSourceFactory或者YamlShardingDataSourceFactory工厂和规则配置对象获取ShardingDataSource,ShardingDataSource实现自JDBC的标准接口DataSource。然后可通过DataSource选择使用原生JDBC开发,或者使用JPA, MyBatis等ORM工具。 以JDBC原生实现为例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
DataSource dataSource = YamlShardingDataSourceFactory.createDataSource(yamlFile);
String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id WHERE o.user_id=? AND o.order_id=?";
try (
Connection conn = dataSource.getConnection();
PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
preparedStatement.setInt(1, 10);
preparedStatement.setInt(2, 1001);
try (ResultSet rs = preparedStatement.executeQuery()) {
while(rs.next()) {
System.out.println(rs.getInt(1));
System.out.println(rs.getInt(2));
}
}
}

使用Spring配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:sharding="http://shardingsphere.apache.org/schema/shardingsphere/sharding"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://shardingsphere.apache.org/schema/shardingsphere/sharding
http://shardingsphere.apache.org/schema/shardingsphere/sharding/sharding.xsd
">
<!--数据源-->
<bean id="ds0" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="com.mysql.jdbc.Driver" />
<property name="url" value="jdbc:mysql://localhost:3306/ds0" />
<property name="username" value="root" />
<property name="password" value="" />
</bean>
<bean id="ds1" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="com.mysql.jdbc.Driver" />
<property name="url" value="jdbc:mysql://localhost:3306/ds1" />
<property name="username" value="root" />
<property name="password" value="" />
</bean>

<!--分片算法-->
<sharding:inline-strategy id="databaseStrategy" sharding-column="user_id" algorithm-expression="ds$->{user_id % 2}" />
<sharding:inline-strategy id="orderTableStrategy" sharding-column="order_id" algorithm-expression="t_order$->{order_id % 2}" />
<sharding:inline-strategy id="orderItemTableStrategy" sharding-column="order_id" algorithm-expression="t_order_item$->{order_id % 2}" />

<!--分片策略-->
<sharding:data-source id="shardingDataSource">
<sharding:sharding-rule data-source-names="ds0,ds1">
<sharding:table-rules>
<sharding:table-rule logic-table="t_order" actual-data-nodes="ds$->{0..1}.t_order$->{0..1}" database-strategy-ref="databaseStrategy" table-strategy-ref="orderTableStrategy" />
<sharding:table-rule logic-table="t_order_item" actual-data-nodes="ds$->{0..1}.t_order_item$->{0..1}" database-strategy-ref="databaseStrategy" table-strategy-ref="orderItemTableStrategy" />
</sharding:table-rules>
</sharding:sharding-rule>
</sharding:data-source>
</beans>

在Spring中使用DataSource

直接通过注入的方式即可使用DataSource,或者将DataSource配置在JPA、Hibernate或MyBatis中使用。

1
2
@Resource
private DataSource dataSource;

使用Spring Boot Starter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 数据源名
spring.shardingsphere.datasource.names=ds0,ds1

spring.shardingsphere.datasource.ds0.type=org.apache.commons.dbcp2.BasicDataSource
spring.shardingsphere.datasource.ds0.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds0.url=jdbc:mysql://localhost:3306/ds0
spring.shardingsphere.datasource.ds0.username=root
spring.shardingsphere.datasource.ds0.password=

spring.shardingsphere.datasource.ds1.type=org.apache.commons.dbcp2.BasicDataSource
spring.shardingsphere.datasource.ds1.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds1.url=jdbc:mysql://localhost:3306/ds1
spring.shardingsphere.datasource.ds1.username=root
spring.shardingsphere.datasource.ds1.password=
# 分库策略,算法使用行表达式
spring.shardingsphere.sharding.default-database-strategy.inline.sharding-column=user_id
spring.shardingsphere.sharding.default-database-strategy.inline.algorithm-expression=ds$->{user_id % 2}
# 分表策略,算法使用行表达式
spring.shardingsphere.sharding.tables.t_order.actual-data-nodes=ds$->{0..1}.t_order$->{0..1}
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.sharding-column=order_id
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.algorithm-expression=t_order$->{order_id % 2}
# 关联表
spring.shardingsphere.sharding.tables.t_order_item.actual-data-nodes=ds$->{0..1}.t_order_item$->{0..1}
spring.shardingsphere.sharding.tables.t_order_item.table-strategy.inline.sharding-column=order_id
spring.shardingsphere.sharding.tables.t_order_item.table-strategy.inline.algorithm-expression=t_order_item$->{order_id % 2}

规则配置包括数据源配置、表规则配置、分库策略和分表策略组成。这只是最简单的配置方式,实际使用可更加灵活,如:多分片键,分片策略直接和表规则配置绑定等。更多的详细配置请参考配置手册

注意事项:

行表达式标识符可以使用${...}$->{...},但前者与Spring本身的属性文件占位符冲突,因此在Spring环境中使用行表达式标识符建议使用$->{...}

配置项手册

Java API配置

配置示例

以下配置中DataSourceUtil的实现为DataSourceUtil,ModuloShardingTableAlgorithm 类需用户自定义实现,详细例子 ModuloShardingTableAlgorithm

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
DataSource getShardingDataSource() throws SQLException {
ShardingRuleConfiguration shardingRuleConfig = new ShardingRuleConfiguration();
shardingRuleConfig.getTableRuleConfigs().add(getOrderTableRuleConfiguration());
shardingRuleConfig.getTableRuleConfigs().add(getOrderItemTableRuleConfiguration());
shardingRuleConfig.getBindingTableGroups().add("t_order, t_order_item");
shardingRuleConfig.getBroadcastTables().add("t_config");
shardingRuleConfig.setDefaultDatabaseShardingStrategyConfig(new InlineShardingStrategyConfiguration("user_id", "ds${user_id % 2}"));
shardingRuleConfig.setDefaultTableShardingStrategyConfig(new StandardShardingStrategyConfiguration("order_id", new ModuloShardingTableAlgorithm()));
return ShardingDataSourceFactory.createDataSource(createDataSourceMap(), shardingRuleConfig, new Properties());
}

private static KeyGeneratorConfiguration getKeyGeneratorConfiguration() {
KeyGeneratorConfiguration result = new KeyGeneratorConfiguration("SNOWFLAKE", "order_id");
return result;
}

TableRuleConfiguration getOrderTableRuleConfiguration() {
TableRuleConfiguration result = new TableRuleConfiguration("t_order", "ds${0..1}.t_order${0..1}");
result.setKeyGeneratorConfig(getKeyGeneratorConfiguration());
return result;
}

TableRuleConfiguration getOrderItemTableRuleConfiguration() {
TableRuleConfiguration result = new TableRuleConfiguration("t_order_item", "ds${0..1}.t_order_item${0..1}");
return result;
}

Map<String, DataSource> createDataSourceMap() {
Map<String, DataSource> result = new HashMap<>();
result.put("ds0", DataSourceUtil.createDataSource("ds0"));
result.put("ds1", DataSourceUtil.createDataSource("ds1"));
return result;
}

配置项说明

ShardingDataSourceFactory:数据分片的数据源创建工厂。

名称 数据类型 说明
dataSourceMap Map<String, DataSource> 数据源配置
shardingRuleConfig ShardingRuleConfiguration 数据分片配置规则
props Properties 属性配置

ShardingRuleConfiguration:分片规则配置对象。

名称 数据类型 说明
tableRuleConfigs Collection<TableRuleConfiguration> 分片规则列表
bindingTableGroups Collection<String> 绑定表规则列表
broadcastTables Collection<String> 广播表规则列表
defaultDataSourceName String 未配置分片规则的表将通过默认数据源定位
defaultDatabaseShardingStrategyConfig ShardingStrategyConfiguration 默认分库策略
defaultTableShardingStrategyConfig ShardingStrategyConfiguration 默认分表策略
defaultKeyGeneratorConfig KeyGeneratorConfiguration 默认自增列值生成器配置,缺省将使用org.apache.shardingsphere.core.keygen.generator.impl.SnowflakeKeyGenerator
masterSlaveRuleConfigs Collection<MasterSlaveRuleConfiguration> 读写分离规则,缺省表示不使用读写分离

TableRuleConfiguration:表分片规则配置对象。

名称 数据类型 说明
logicTable String 逻辑表名称
actualDataNodes String 由数据源名 + 表名组成,以小数点分隔。多个表以逗号分隔,支持inline表达式。缺省表示使用已知数据源与逻辑表名称生成数据节点,用于广播表(即每个库中都需要一个同样的表用于关联查询,多为字典表)或只分库不分表且所有库的表结构完全一致的情况
databaseShardingStrategyConfig ShardingStrategyConfiguration 分库策略,缺省表示使用默认分库策略
tableShardingStrategyConfig ShardingStrategyConfiguration 分表策略,缺省表示使用默认分表策略
keyGeneratorConfig KeyGeneratorConfiguration 自增列值生成器配置,缺省表示使用默认自增主键生成器
encryptorConfiguration EncryptorConfiguration 加解密生成器配置

StandardShardingStrategyConfiguration:ShardingStrategyConfiguration的实现类,用于单分片键的标准分片场景。

名称 数据类型 说明
shardingColumn String 分片列名称
preciseShardingAlgorithm PreciseShardingAlgorithm 精确分片算法,用于=和IN
rangeShardingAlgorithm RangeShardingAlgorithm 范围分片算法,用于BETWEEN

ComplexShardingStrategyConfiguration:ShardingStrategyConfiguration的实现类,用于多分片键的复合分片场景。

名称 数据类型 说明
shardingColumns String 分片列名称,多个列以逗号分隔
shardingAlgorithm ComplexKeysShardingAlgorithm 复合分片算法

InlineShardingStrategyConfiguration:ShardingStrategyConfiguration的实现类,用于配置行表达式分片策略。

名称 数据类型 说明
shardingColumn String 分片列名称
algorithmExpression String 分片算法行表达式,需符合groovy语法,详情请参考行表达式

HintShardingStrategyConfiguration:ShardingStrategyConfiguration的实现类,用于配置Hint方式分片策略。

名称 数据类型 说明
shardingAlgorithm HintShardingAlgorithm Hint分片算法

NoneShardingStrategyConfiguration:ShardingStrategyConfiguration的实现类,用于配置不分片的策略,是一个空的实现类。

KeyGeneratorConfiguration:分布式序列配置类。

名称 数据类型 说明
column String 自增列名称
type String 自增列值生成器类型,可自定义或选择内置类型:SNOWFLAKE/UUID
props Properties 自增列值生成器的相关属性配置
  • Properties:属性配置项,可以为以下自增列值生成器的属性。

    SNOWFLAKE:

名称 数据类型 说明
worker.id long 工作机器唯一id,默认为0
max.tolerate.time.difference.milliseconds long 最大容忍时钟回退时间,单位:毫秒。默认为10毫秒
max.vibration.offset int 最大抖动上限值,范围[0, 4096),默认为1。
注:若使用此算法生成值作分片值,建议配置此属性。
此算法在不同毫秒内所生成的key取模2^n (2^n一般为分库或分表数)
之后结果总为0或1。
为防止上述分片问题,建议将此属性值配置为(2^n)-1

EncryptRuleConfiguration

名称 数据类型 说明
encryptors Map<String, EncryptorRuleConfiguration> 加解密器配置列表,可自定义或选择内置类型:MD5/AES
tables Map<String, EncryptTableRuleConfiguration> 加密表配置列表

EncryptorRuleConfiguration

名称 数据类型 说明
type String 加解密器类型,可自定义或选择内置类型:MD5/AES
properties Properties 属性配置, 注意:使用AES加密器,需要配置AES加密器的KEY属性:aes.key.value

EncryptTableRuleConfiguration

名称 数据类型 说明
tables Map<String, EncryptColumnRuleConfiguration> 加密列配置列表

EncryptColumnRuleConfiguration

名称 数据类型 说明
plainColumn String 存储明文的字段
cipherColumn String 存储密文的字段
assistedQueryColumn String 辅助查询字段,针对ShardingQueryAssistedEncryptor类型的加解密器进行辅助查询
encryptor String 加解密器名字

Properties:ShardingShpere系统属性配置项,可以为以下属性。

名称 数据类型 说明
sql.show boolean 是否开启SQL显示,默认值: false
executor.size int 工作线程数量,默认值: CPU核数
max.connections.size.per.query int 每个物理数据库为每次查询分配的最大连接数量。默认值: 1
check.table.metadata.enabled boolean 是否在启动时检查分表元数据一致性,默认值: false
query.with.cipher.column boolean 当存在明文列时,是否使用密文列查询,默认值: true
allow.range.query.with.inline.sharding boolean 当使用inline分表策略时,是否允许范围查询,默认值: false

Yaml配置

配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
dataSources:
ds0: !!org.apache.commons.dbcp.BasicDataSource
driverClassName: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/ds0
username: root
password:
ds1: !!org.apache.commons.dbcp.BasicDataSource
driverClassName: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/ds1
username: root
password:

shardingRule:
tables:
t_order:
actualDataNodes: ds${0..1}.t_order${0..1}
databaseStrategy:
inline:
shardingColumn: user_id
algorithmExpression: ds${user_id % 2}
tableStrategy:
inline:
shardingColumn: order_id
algorithmExpression: t_order${order_id % 2}
keyGenerator:
type: SNOWFLAKE
column: order_id
t_order_item:
actualDataNodes: ds${0..1}.t_order_item${0..1}
databaseStrategy:
inline:
shardingColumn: user_id
algorithmExpression: ds${user_id % 2}
tableStrategy:
inline:
shardingColumn: order_id
algorithmExpression: t_order_item${order_id % 2}
bindingTables:
- t_order,t_order_item
broadcastTables:
- t_config

defaultDataSourceName: ds0
defaultTableStrategy:
none:
defaultKeyGenerator:
type: SNOWFLAKE
column: order_id

props:
sql.show: true

配置项说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
dataSources: #数据源配置,可配置多个data_source_name
<data_source_name>: #<!!数据库连接池实现类> `!!`表示实例化该类
driverClassName: #数据库驱动类名
url: #数据库url连接
username: #数据库用户名
password: #数据库密码
# ... 数据库连接池的其它属性

shardingRule:
tables: #数据分片规则配置,可配置多个logic_table_name
<logic_table_name>: #逻辑表名称
actualDataNodes: #由数据源名 + 表名组成,以小数点分隔。多个表以逗号分隔,支持inline表达式。缺省表示使用已知数据源与逻辑表名称生成数据节点,用于广播表(即每个库中都需要一个同样的表用于关联查询,多为字典表)或只分库不分表且所有库的表结构完全一致的情况

databaseStrategy: #分库策略,缺省表示使用默认分库策略,以下的分片策略只能选其一
standard: #用于单分片键的标准分片场景
shardingColumn: #分片列名称
preciseAlgorithmClassName: #精确分片算法类名称,用于=和IN。。该类需实现PreciseShardingAlgorithm接口并提供无参数的构造器
rangeAlgorithmClassName: #范围分片算法类名称,用于BETWEEN,可选。。该类需实现RangeShardingAlgorithm接口并提供无参数的构造器
complex: #用于多分片键的复合分片场景
shardingColumns: #分片列名称,多个列以逗号分隔
algorithmClassName: #复合分片算法类名称。该类需实现ComplexKeysShardingAlgorithm接口并提供无参数的构造器
inline: #行表达式分片策略
shardingColumn: #分片列名称
algorithmInlineExpression: #分片算法行表达式,需符合groovy语法
hint: #Hint分片策略
algorithmClassName: #Hint分片算法类名称。该类需实现HintShardingAlgorithm接口并提供无参数的构造器
none: #不分片
tableStrategy: #分表策略,同分库策略
keyGenerator:
column: #自增列名称,缺省表示不使用自增主键生成器
type: #自增列值生成器类型,缺省表示使用默认自增列值生成器。可使用用户自定义的列值生成器或选择内置类型:SNOWFLAKE/UUID
props: #属性配置, 注意:使用SNOWFLAKE算法,需要配置worker.id与max.tolerate.time.difference.milliseconds属性。若使用此算法生成值作分片值,建议配置max.vibration.offset属性
<property-name>: 属性名称

bindingTables: #绑定表规则列表
- <logic_table_name1, logic_table_name2, ...>
- <logic_table_name3, logic_table_name4, ...>
- <logic_table_name_x, logic_table_name_y, ...>
broadcastTables: #广播表规则列表
- table_name1
- table_name2
- table_name_x

defaultDataSourceName: #未配置分片规则的表将通过默认数据源定位
defaultDatabaseStrategy: #默认数据库分片策略,同分库策略
defaultTableStrategy: #默认表分片策略,同分库策略
defaultKeyGenerator: #默认的主键生成算法 如果没有设置,默认为SNOWFLAKE算法
type: #默认自增列值生成器类型,缺省将使用org.apache.shardingsphere.core.keygen.generator.impl.SnowflakeKeyGenerator。可使用用户自定义的列值生成器或选择内置类型:SNOWFLAKE/UUID
props:
<property-name>: #自增列值生成器属性配置, 比如SNOWFLAKE算法的worker.id与max.tolerate.time.difference.milliseconds

masterSlaveRules: #读写分离规则,详见读写分离部分
<data_source_name>: #数据源名称,需要与真实数据源匹配,可配置多个data_source_name
masterDataSourceName: #详见读写分离部分
slaveDataSourceNames: #详见读写分离部分
loadBalanceAlgorithmType: #详见读写分离部分
props: #读写分离负载算法的属性配置
<property-name>: #属性值

props: #属性配置
sql.show: #是否开启SQL显示,默认值: false
executor.size: #工作线程数量,默认值: CPU核数
max.connections.size.per.query: # 每个查询可以打开的最大连接数量,默认为1
check.table.metadata.enabled: #是否在启动时检查分表元数据一致性,默认值: false

Yaml语法说明:

  • !! 表示实例化该类

  • - 表示可以包含一个或多个

  • [] 表示数组,可以与减号相互替换使用

Spring命名空间配置

注意事项:行表达式标识符可以使用${...}$->{...},但前者与Spring本身的属性文件占位符冲突,因此在Spring环境中使用行表达式标识符建议使用$->{...}

配置示例

详细example: shardingsphere-example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:tx="http://www.springframework.org/schema/tx"
xmlns:sharding="http://shardingsphere.apache.org/schema/shardingsphere/sharding"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://shardingsphere.apache.org/schema/shardingsphere/sharding
http://shardingsphere.apache.org/schema/shardingsphere/sharding/sharding.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx.xsd">
<context:annotation-config />

<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<property name="dataSource" ref="shardingDataSource" />
<property name="jpaVendorAdapter">
<bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter" p:database="MYSQL" />
</property>
<property name="packagesToScan" value="org.apache.shardingsphere.example.core.jpa.entity" />
<property name="jpaProperties">
<props>
<prop key="hibernate.dialect">org.hibernate.dialect.MySQLDialect</prop>
<prop key="hibernate.hbm2ddl.auto">create</prop>
<prop key="hibernate.show_sql">true</prop>
</props>
</property>
</bean>
<bean id="transactionManager" class="org.springframework.orm.jpa.JpaTransactionManager" p:entityManagerFactory-ref="entityManagerFactory" />
<tx:annotation-driven />

<bean id="ds0" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="com.mysql.jdbc.Driver" />
<property name="url" value="jdbc:mysql://localhost:3306/ds0" />
<property name="username" value="root" />
<property name="password" value="" />
</bean>

<bean id="ds1" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="com.mysql.jdbc.Driver" />
<property name="url" value="jdbc:mysql://localhost:3306/ds1" />
<property name="username" value="root" />
<property name="password" value="" />
</bean>

<bean id="preciseModuloDatabaseShardingAlgorithm" class="org.apache.shardingsphere.example.algorithm.PreciseModuloShardingDatabaseAlgorithm" />
<bean id="preciseModuloTableShardingAlgorithm" class="org.apache.shardingsphere.example.algorithm.PreciseModuloShardingTableAlgorithm" />

<sharding:standard-strategy id="databaseShardingStrategy" sharding-column="user_id" precise-algorithm-ref="preciseModuloDatabaseShardingAlgorithm" />
<sharding:standard-strategy id="tableShardingStrategy" sharding-column="order_id" precise-algorithm-ref="preciseModuloTableShardingAlgorithm" />

<sharding:key-generator id="orderKeyGenerator" type="SNOWFLAKE" column="order_id" />
<sharding:key-generator id="itemKeyGenerator" type="SNOWFLAKE" column="order_item_id" />

<sharding:data-source id="shardingDataSource">
<sharding:sharding-rule data-source-names="ds0,ds1">
<sharding:table-rules>
<sharding:table-rule logic-table="t_order" actual-data-nodes="ds$->{0..1}.t_order$->{0..1}" database-strategy-ref="databaseShardingStrategy" table-strategy-ref="tableShardingStrategy" key-generator-ref="orderKeyGenerator" />
<sharding:table-rule logic-table="t_order_item" actual-data-nodes="ds$->{0..1}.t_order_item$->{0..1}" database-strategy-ref="databaseShardingStrategy" table-strategy-ref="tableShardingStrategy" key-generator-ref="itemKeyGenerator" />
</sharding:table-rules>
<sharding:binding-table-rules>
<sharding:binding-table-rule logic-tables="t_order, t_order_item" />
</sharding:binding-table-rules>
<sharding:broadcast-table-rules>
<sharding:broadcast-table-rule table="t_config" />
</sharding:broadcast-table-rules>
</sharding:sharding-rule>
</sharding:data-source>
</beans>

配置项说明

分库分表

命名空间:http://shardingsphere.apache.org/schema/shardingsphere/sharding/sharding.xsd

<sharding:data-source />

名称 类型 说明
id 属性 Spring Bean Id
sharding-rule 标签 数据分片配置规则
props 标签 属性配置

<sharding:sharding-rule />

名称 类型 说明
data-source-names 属性 数据源Bean列表,多个Bean以逗号分隔
table-rules 标签 表分片规则配置对象
binding-table-rules 标签 绑定表规则列表
broadcast-table-rules 标签 广播表规则列表
default-data-source-name 属性 未配置分片规则的表将通过默认数据源定位
default-database-strategy-ref 属性 默认数据库分片策略,
对应sharding:xxx-strategy中的策略Id,缺省表示不分库
default-table-strategy-ref 属性 默认表分片策略,
对应sharding:xxx-strategy中的策略Id,缺省表示不分表
default-key-generator-ref 属性 默认自增列值生成器引用,
缺省使用org.apache.shardingsphere.core.keygen.generator.impl.SnowflakeKeyGenerator
encrypt-rule 标签 脱敏规则

<sharding:table-rules />

名称 类型 说明
table-rule 标签 表分片规则配置对象

<sharding:table-rule />

名称 类型 说明
logic-table 属性 逻辑表名称
actual-data-nodes 属性 由数据源名 + 表名组成,以小数点分隔。
多个表以逗号分隔,支持inline表达式。
缺省表示使用已知数据源与逻辑表名称生成数据节点,
用于广播表(即每个库中都需要一个同样的表用于关联查询,多为字典表)
或只分库不分表且所有库的表结构完全一致的情况
database-strategy-ref 属性 数据库分片策略,对应sharding:xxx-strategy中的策略Id,
缺省表示使用<sharding:sharding-rule />配置的默认数据库分片策略
table-strategy-ref 属性 表分片策略,对应sharding:xxx-strategy中的策略Id,
缺省表示使用<sharding:sharding-rule />配置的默认表分片策略
key-generator-ref 属性 自增列值生成器引用,缺省表示使用默认自增列值生成器

<sharding:binding-table-rules />

名称 类型 说明
binding-table-rule 标签 绑定表规则

<sharding:binding-table-rule />

名称 类型 说明
logic-tables 属性 绑定规则的逻辑表名,多表以逗号分隔

<sharding:broadcast-table-rules />

名称 类型 说明
broadcast-table-rule 标签 广播表规则

<sharding:broadcast-table-rule />

名称 类型 *说明
table 属性 广播规则的表名

<sharding:standard-strategy />

名称 类型 说明
id 属性 Spring Bean Id
sharding-column 属性 分片列名称
precise-algorithm-ref 属性 精确分片算法引用,用于=和IN。该类需实现PreciseShardingAlgorithm接口
range-algorithm-ref 属性 范围分片算法引用,用于BETWEEN。该类需实现RangeShardingAlgorithm接口

<sharding:complex-strategy />

名称 类型 说明
id 属性 Spring Bean Id
sharding-columns 属性 分片列名称,多个列以逗号分隔
algorithm-ref 属性 复合分片算法引用。该类需实现ComplexKeysShardingAlgorithm接口

<sharding:inline-strategy />

名称 类型 说明
id 属性 Spring Bean Id
sharding-column 属性 分片列名称
algorithm-expression 属性 分片算法行表达式,需符合groovy语法

<sharding:hint-database-strategy />

名称 类型 说明
id 属性 Spring Bean Id
algorithm-ref 属性 Hint分片算法。该类需实现HintShardingAlgorithm接口

<sharding:none-strategy />

名称 类型 说明
id 属性 Spring Bean Id

<sharding:key-generator />

名称 类型 说明
column 属性 自增列名称
type 属性 自增列值生成器类型,可自定义或选择内置类型:SNOWFLAKE/UUID
props-ref 属性 自增列值生成器的属性配置引用

Properties:属性配置项,可以为以下自增列值生成器的属性。

SNOWFLAKE:

名称 数据类型 说明
worker.id long 工作机器唯一id,默认为0
max.tolerate.time.difference.milliseconds long 最大容忍时钟回退时间,单位:毫秒。默认为10毫秒
max.vibration.offset int 最大抖动上限值,范围[0, 4096),默认为1。
注:若使用此算法生成值作分片值,建议配置此属性。
此算法在不同毫秒内所生成的key取模2^n (2^n一般为分库或分表数) 之后结果总为0或1。
为防止上述分片问题,建议将此属性值配置为(2^n)-1

<sharding:encrypt-rule />

名称 类型 说明
encrypt:encrypt-rule 标签 加解密规则

<sharding:props />

名称 类型 说明
sql.show 属性 是否开启SQL显示,默认值: false
executor.size 属性 工作线程数量,默认值: CPU核数
max.connections.size.per.query 属性 每个物理数据库为每次查询分配的最大连接数量。默认值: 1
check.table.metadata.enabled 属性 是否在启动时检查分表元数据一致性,默认值: false
query.with.cipher.column 属性 当存在明文列时,是否使用密文列查询,默认值: true

Spring Boot配置

注意事项:行表达式标识符可以使用${...}$->{...},但前者与Spring本身的属性文件占位符冲突,因此在Spring环境中使用行表达式标识符建议使用$->{...}

配置示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
spring.shardingsphere.datasource.names=ds0,ds1

spring.shardingsphere.datasource.ds0.type=org.apache.commons.dbcp.BasicDataSource
spring.shardingsphere.datasource.ds0.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds0.url=jdbc:mysql://localhost:3306/ds0
spring.shardingsphere.datasource.ds0.username=root
spring.shardingsphere.datasource.ds0.password=

spring.shardingsphere.datasource.ds1.type=org.apache.commons.dbcp.BasicDataSource
spring.shardingsphere.datasource.ds1.driver-class-name=com.mysql.jdbc.Driver
spring.shardingsphere.datasource.ds1.url=jdbc:mysql://localhost:3306/ds1
spring.shardingsphere.datasource.ds1.username=root
spring.shardingsphere.datasource.ds1.password=

spring.shardingsphere.sharding.tables.t_order.actual-data-nodes=ds$->{0..1}.t_order$->{0..1}
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.sharding-column=order_id
spring.shardingsphere.sharding.tables.t_order.table-strategy.inline.algorithm-expression=t_order$->{order_id % 2}
spring.shardingsphere.sharding.tables.t_order.key-generator.column=order_id
spring.shardingsphere.sharding.tables.t_order.key-generator.type=SNOWFLAKE
spring.shardingsphere.sharding.tables.t_order_item.actual-data-nodes=ds$->{0..1}.t_order_item$->{0..1}
spring.shardingsphere.sharding.tables.t_order_item.table-strategy.inline.sharding-column=order_id
spring.shardingsphere.sharding.tables.t_order_item.table-strategy.inline.algorithm-expression=t_order_item$->{order_id % 2}
spring.shardingsphere.sharding.tables.t_order_item.key-generator.column=order_item_id
spring.shardingsphere.sharding.tables.t_order_item.key-generator.type=SNOWFLAKE
spring.shardingsphere.sharding.binding-tables=t_order,t_order_item
spring.shardingsphere.sharding.broadcast-tables=t_config

spring.shardingsphere.sharding.default-database-strategy.inline.sharding-column=user_id
spring.shardingsphere.sharding.default-database-strategy.inline.algorithm-expression=ds$->{user_id % 2}

配置项说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
spring.shardingsphere.datasource.names= #数据源名称,多数据源以逗号分隔

spring.shardingsphere.datasource.<data-source-name>.type= #数据库连接池类名称
spring.shardingsphere.datasource.<data-source-name>.driver-class-name= #数据库驱动类名
spring.shardingsphere.datasource.<data-source-name>.url= #数据库url连接
spring.shardingsphere.datasource.<data-source-name>.username= #数据库用户名
spring.shardingsphere.datasource.<data-source-name>.password= #数据库密码
spring.shardingsphere.datasource.<data-source-name>.xxx= #数据库连接池的其它属性

spring.shardingsphere.sharding.tables.<logic-table-name>.actual-data-nodes= #由数据源名 + 表名组成,以小数点分隔。多个表以逗号分隔,支持inline表达式。缺省表示使用已知数据源与逻辑表名称生成数据节点,用于广播表(即每个库中都需要一个同样的表用于关联查询,多为字典表)或只分库不分表且所有库的表结构完全一致的情况

#分库策略,缺省表示使用默认分库策略,以下的分片策略只能选其一

#用于单分片键的标准分片场景
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.standard.sharding-column= #分片列名称
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.standard.precise-algorithm-class-name= #精确分片算法类名称,用于=和IN。该类需实现PreciseShardingAlgorithm接口并提供无参数的构造器
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.standard.range-algorithm-class-name= #范围分片算法类名称,用于BETWEEN,可选。该类需实现RangeShardingAlgorithm接口并提供无参数的构造器

#用于多分片键的复合分片场景
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.complex.sharding-columns= #分片列名称,多个列以逗号分隔
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.complex.algorithm-class-name= #复合分片算法类名称。该类需实现ComplexKeysShardingAlgorithm接口并提供无参数的构造器

#行表达式分片策略
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.inline.sharding-column= #分片列名称
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.inline.algorithm-expression= #分片算法行表达式,需符合groovy语法

#Hint分片策略
spring.shardingsphere.sharding.tables.<logic-table-name>.database-strategy.hint.algorithm-class-name= #Hint分片算法类名称。该类需实现HintShardingAlgorithm接口并提供无参数的构造器

#分表策略,同分库策略
spring.shardingsphere.sharding.tables.<logic-table-name>.table-strategy.xxx= #省略

spring.shardingsphere.sharding.tables.<logic-table-name>.key-generator.column= #自增列名称,缺省表示不使用自增主键生成器
spring.shardingsphere.sharding.tables.<logic-table-name>.key-generator.type= #自增列值生成器类型,缺省表示使用默认自增列值生成器。可使用用户自定义的列值生成器或选择内置类型:SNOWFLAKE/UUID
spring.shardingsphere.sharding.tables.<logic-table-name>.key-generator.props.<property-name>= #属性配置, 注意:使用SNOWFLAKE算法,需要配置worker.id与max.tolerate.time.difference.milliseconds属性。若使用此算法生成值作分片值,建议配置max.vibration.offset属性

spring.shardingsphere.sharding.binding-tables[0]= #绑定表规则列表
spring.shardingsphere.sharding.binding-tables[1]= #绑定表规则列表
spring.shardingsphere.sharding.binding-tables[x]= #绑定表规则列表

spring.shardingsphere.sharding.broadcast-tables[0]= #广播表规则列表
spring.shardingsphere.sharding.broadcast-tables[1]= #广播表规则列表
spring.shardingsphere.sharding.broadcast-tables[x]= #广播表规则列表

spring.shardingsphere.sharding.default-data-source-name= #未配置分片规则的表将通过默认数据源定位
spring.shardingsphere.sharding.default-database-strategy.xxx= #默认数据库分片策略,同分库策略
spring.shardingsphere.sharding.default-table-strategy.xxx= #默认表分片策略,同分表策略
spring.shardingsphere.sharding.default-key-generator.type= #默认自增列值生成器类型,缺省将使用org.apache.shardingsphere.core.keygen.generator.impl.SnowflakeKeyGenerator。可使用用户自定义的列值生成器或选择内置类型:SNOWFLAKE/UUID
spring.shardingsphere.sharding.default-key-generator.props.<property-name>= #自增列值生成器属性配置, 比如SNOWFLAKE算法的worker.id与max.tolerate.time.difference.milliseconds

spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.master-data-source-name= #详见读写分离部分
spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.slave-data-source-names[0]= #详见读写分离部分
spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.slave-data-source-names[1]= #详见读写分离部分
spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.slave-data-source-names[x]= #详见读写分离部分
spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.load-balance-algorithm-class-name= #详见读写分离部分
spring.shardingsphere.sharding.master-slave-rules.<master-slave-data-source-name>.load-balance-algorithm-type= #详见读写分离部分

spring.shardingsphere.props.sql.show= #是否开启SQL显示,默认值: false
spring.shardingsphere.props.executor.size= #工作线程数量,默认值: CPU核数

Hint 强制路由

Apache ShardingSphere 使用 ThreadLocal 管理分片键值进行强制路由。 可以通过编程的方式向 HintManager 中添加分片值,该分片值仅在当前线程内生效。

Hint 的主要使用场景:

  • 分片字段不存在 SQL 和数据库表结构中,而存在于外部业务逻辑。
  • 强制在主库进行某些数据操作。

Hint 分片算法需要用户实现 org.apache.shardingsphere.sharding.api.sharding.hint.HintShardingAlgorithm 接口。 Apache ShardingSphere 在进行路由时,将会从 HintManager 中获取分片值进行路由操作。

基于Hint的数据分片

配置Hint分片算法

参考配置如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
shardingRule:
tables:
t_order:
actualDataNodes: demo_ds_${0..1}.t_order_${0..1}
databaseStrategy:
hint:
algorithmClassName: org.apache.shardingsphere.userAlgo.HintAlgorithm
tableStrategy:
hint:
algorithmClassName: org.apache.shardingsphere.userAlgo.HintAlgorithm
defaultTableStrategy:
none:
defaultKeyGenerator:
type: SNOWFLAKE
column: order_id
props:
sql.show: true

获取 HintManager

1
HintManager hintManager = HintManager.getInstance();

添加分片键值

  • 使用 hintManager.addDatabaseShardingValue 来添加数据源分片键值。
  • 使用 hintManager.addTableShardingValue 来添加表分片键值。

分库不分表情况下,强制路由至某一个分库时,可使用 hintManager.setDatabaseShardingValue 方式添加分片。 通过此方式添加分片键值后,将跳过 SQL 解析和改写阶段,从而提高整体执行效率。

清除分片值

分片键值保存在 ThreadLocal 中,所以需要在操作结束时调用 hintManager.close() 来清除 ThreadLocal 中的内容。

hintManager 实现了 AutoCloseable 接口,可推荐使用 try with resource 自动关闭。

完整代码示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Sharding database and table with using HintManager
String sql = "SELECT * FROM t_order";
try (HintManager hintManager = HintManager.getInstance();
Connection conn = dataSource.getConnection();
PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
hintManager.addDatabaseShardingValue("t_order", 1);
hintManager.addTableShardingValue("t_order", 2);
try (ResultSet rs = preparedStatement.executeQuery()) {
while (rs.next()) {
// ...
}
}
}

// Sharding database without sharding table and routing to only one database with using HintManager
String sql = "SELECT * FROM t_order";
try (HintManager hintManager = HintManager.getInstance();
Connection conn = dataSource.getConnection();
PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
hintManager.setDatabaseShardingValue(3);
try (ResultSet rs = preparedStatement.executeQuery()) {
while (rs.next()) {
// ...
}
}
}

基于Hint的强制主库路由

获取 HintManager

与基于 Hint 的数据分片相同。

设置主库路由

  • 使用 hintManager.setMasterRouteOnly 设置主库路由。

清除分片健值

与基于 Hint 的数据分片相同。

完整代码示例

1
2
3
4
5
6
7
8
9
10
11
12
String sql = "SELECT * FROM t_order";
try (
HintManager hintManager = HintManager.getInstance();
Connection conn = dataSource.getConnection();
PreparedStatement preparedStatement = conn.prepareStatement(sql)) {
hintManager.setMasterRouteOnly();
try (ResultSet rs = preparedStatement.executeQuery()) {
while (rs.next()) {
// ...
}
}
}

官方:强制路由分片示例 > hint-example

系统级配置属性

特别注意:官方文档中的少部文属性名与实际使用并不相同,是官方文档没有更新。

属性配置类

Apache ShardingSphere 系统级属性名可参考 org.apache.shardingsphere.underlying.common.config.properties.ConfigurationPropertyKey 枚举类,已有的枚举值如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public enum ConfigurationPropertyKey implements TypedPropertyKey {
SQL_SHOW("sql.show", String.valueOf(Boolean.FALSE), Boolean.TYPE),
SQL_SIMPLE("sql.simple", String.valueOf(Boolean.FALSE), Boolean.TYPE),
ACCEPTOR_SIZE("acceptor.size", String.valueOf(Runtime.getRuntime().availableProcessors() * 2), Integer.TYPE),
EXECUTOR_SIZE("executor.size", String.valueOf(0), Integer.TYPE),
MAX_CONNECTIONS_SIZE_PER_QUERY("max.connections.size.per.query", String.valueOf(1), Integer.TYPE),
QUERY_WITH_CIPHER_COLUMN("query.with.cipher.column", String.valueOf(Boolean.TRUE), Boolean.TYPE),
ALLOW_RANGE_QUERY_WITH_INLINE_SHARDING("allow.range.query.with.inline.sharding", String.valueOf(Boolean.FALSE), Boolean.TYPE),
PROXY_FRONTEND_FLUSH_THRESHOLD("proxy.frontend.flush.threshold", String.valueOf(128), Integer.TYPE),
PROXY_TRANSACTION_TYPE("proxy.transaction.type", "LOCAL", String.class),
PROXY_OPENTRACING_ENABLED("proxy.opentracing.enabled", String.valueOf(Boolean.FALSE), Boolean.TYPE),
PROXY_HINT_ENABLED("proxy.hint.enabled", String.valueOf(Boolean.FALSE), Boolean.TYPE),
PROXY_BACKEND_MAX_CONNECTIONS("proxy.backend.max.connections", String.valueOf(8), Integer.TYPE),
PROXY_BACKEND_CONNECTION_TIMEOUT_SECONDS("proxy.backend.connection.timeout.seconds", String.valueOf(60), Integer.TYPE),
CHECK_TABLE_METADATA_ENABLED("check.table.metadata.enabled", String.valueOf(Boolean.FALSE), Boolean.TYPE);
//................省略..............
}

系统属性名

官方文档中的系统属性配置:

名称 数据类型 说明 默认值
sql-show boolean 是否在日志中打印 SQL。
打印 SQL 可以帮助开发者快速定位系统问题。
日志内容包含:逻辑 SQL,真实 SQL 和 SQL 解析结果。
如果开启配置,日志将使用 Topic ShardingSphere-SQL
日志级别是 INFO。
false
sql.simple boolean 是否在日志中打印简单风格的 SQL。 false
executor-size int 用于设置任务处理线程池的大小。
每个 ShardingSphereDataSource 使用一个独立的线程池,
同一个 JVM 的不同数据源不共享线程池。
infinite
max-connections-size-per-query int 一次查询请求在每个数据库实例中所能使用的最大连接数。 1
check-table-metadata-enabled boolean 是否在程序启动和更新时检查分片元数据的结构一致性。 false
query-with-cipher-column boolean 是否使用加密列进行查询。
在有原文列的情况下,可以使用原文列进行查询。
true

分片策略配置

分片策略配置类

分片策略配置类:org.apache.shardingsphere.api.config.sharding.strategy.ShardingStrategyConfiguration

ShardingStrategyConfiguration 是分片配置的抽象接口,有 4 个实现类,分别是:

  • 标准分片策略配置类:StandardShardingStrategyConfiguration
  • 行表达式分片策略配置类:InlineShardingStrategyConfiguration
  • 复合分片策略配置类:ComplexShardingStrategyConfiguration
  • 强制路由分片策略配置类:HintShardingStrategyConfiguration
  • 不分片策略配置类:NoneShardingStrategyConfiguration,这是一个空类

下面是分片策略工厂:根据传入的分片策略配置类型返因具体的分片策略对象。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/**
* Sharding strategy factory.
*/
@NoArgsConstructor(access = AccessLevel.PRIVATE)
public final class ShardingStrategyFactory {

/**
* Create sharding algorithm.
*
* @param shardingStrategyConfig sharding strategy configuration
* @return sharding strategy instance
*/
public static ShardingStrategy newInstance(final ShardingStrategyConfiguration shardingStrategyConfig) {
if (shardingStrategyConfig instanceof StandardShardingStrategyConfiguration) {
return new StandardShardingStrategy((StandardShardingStrategyConfiguration) shardingStrategyConfig);
}
if (shardingStrategyConfig instanceof InlineShardingStrategyConfiguration) {
return new InlineShardingStrategy((InlineShardingStrategyConfiguration) shardingStrategyConfig);
}
if (shardingStrategyConfig instanceof ComplexShardingStrategyConfiguration) {
return new ComplexShardingStrategy((ComplexShardingStrategyConfiguration) shardingStrategyConfig);
}
if (shardingStrategyConfig instanceof HintShardingStrategyConfiguration) {
return new HintShardingStrategy((HintShardingStrategyConfiguration) shardingStrategyConfig);
}
return new NoneShardingStrategy();
}
}

行表达式分片策略配置

行表达式分片策略配置:只能在 Spring Boot 环境的配置文件中使用。

Spring Boot 配置文件中行表达式配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Getter
@Setter
public final class YamlShardingStrategyConfiguration implements YamlConfiguration {
// 标准分片
private YamlStandardShardingStrategyConfiguration standard;
// 复合分片
private YamlComplexShardingStrategyConfiguration complex;
// 强制路由分片
private YamlHintShardingStrategyConfiguration hint;
// 行表达式分片
private YamlInlineShardingStrategyConfiguration inline;
// 不分片
private YamlNoneShardingStrategyConfiguration none;
}

配置属性:

1
2
3
4
5
6
7
8
9
10
11
/**
* Inline sharding strategy configuration for YAML.
*/
@Getter
@Setter
public final class YamlInlineShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {

private String shardingColumn;

private String algorithmExpression;
}

标准分片策略配置

类名称:org.apache.shardingsphere.sharding.api.config.strategy.sharding.StandardShardingStrategyConfiguration

可配置属性:

名称 数据类型 说明
shardingColumn String 分片列名称
shardingAlgorithmName String 分片算法名称
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@Getter
public final class StandardShardingStrategyConfiguration implements ShardingStrategyConfiguration {

private final String shardingColumn;

private final PreciseShardingAlgorithm preciseShardingAlgorithm;

private final RangeShardingAlgorithm rangeShardingAlgorithm;

public StandardShardingStrategyConfiguration(final String shardingColumn, final PreciseShardingAlgorithm preciseShardingAlgorithm) {
this(shardingColumn, preciseShardingAlgorithm, null);
}

public StandardShardingStrategyConfiguration(final String shardingColumn, final PreciseShardingAlgorithm preciseShardingAlgorithm, final RangeShardingAlgorithm rangeShardingAlgorithm) {
Preconditions.checkArgument(!Strings.isNullOrEmpty(shardingColumn), "ShardingColumns is required.");
Preconditions.checkNotNull(preciseShardingAlgorithm, "PreciseShardingAlgorithm is required.");
this.shardingColumn = shardingColumn;
this.preciseShardingAlgorithm = preciseShardingAlgorithm;
this.rangeShardingAlgorithm = rangeShardingAlgorithm;
}
}

复合分片策略配置

类名称:org.apache.shardingsphere.sharding.api.config.strategy.sharding.ComplexShardingStrategyConfiguration

可配置属性:

名称 数据类型 说明
shardingColumns String 分片列名称,多个列以逗号分隔
shardingAlgorithmName String 分片算法名称
1
2
3
4
5
6
7
8
9
10
11
12
13
14
@Getter
public final class ComplexShardingStrategyConfiguration implements ShardingStrategyConfiguration {

private final String shardingColumns;

private final ComplexKeysShardingAlgorithm shardingAlgorithm;

public ComplexShardingStrategyConfiguration(final String shardingColumns, final ComplexKeysShardingAlgorithm shardingAlgorithm) {
Preconditions.checkArgument(!Strings.isNullOrEmpty(shardingColumns), "ShardingColumns is required.");
Preconditions.checkNotNull(shardingAlgorithm, "ShardingAlgorithm is required.");
this.shardingColumns = shardingColumns;
this.shardingAlgorithm = shardingAlgorithm;
}
}

Hint 分片策略配置

类名称:org.apache.shardingsphere.sharding.api.config.strategy.sharding.HintShardingStrategyConfiguration

可配置属性:

名称 数据类型 说明
shardingAlgorithmName String 分片算法名称
1
2
3
4
5
6
7
8
9
10
@Getter
public final class HintShardingStrategyConfiguration implements ShardingStrategyConfiguration {

private final HintShardingAlgorithm shardingAlgorithm;

public HintShardingStrategyConfiguration(final HintShardingAlgorithm shardingAlgorithm) {
Preconditions.checkNotNull(shardingAlgorithm, "ShardingAlgorithm is required.");
this.shardingAlgorithm = shardingAlgorithm;
}
}

不分片策略配置

类名称:org.apache.shardingsphere.sharding.api.config.strategy.sharding.NoneShardingStrategyConfiguration

可配置属性:无,这是一个空类

1
2
public final class NoneShardingStrategyConfiguration implements ShardingStrategyConfiguration {
}

算法类型的详情,请参见内置分片算法列表

Spring Boot 分片策略配置

如果使用基于 Spring Boot 的 Starter 包,直接在配置文件中配置分片策略的,分片策略是基于 YAML 格式的配置类。

分片规则配置类 org.apache.shardingsphere.core.yaml.config.sharding.YamlShardingStrategyConfiguration 实现了 org.apache.shardingsphere.underlying.common.yaml.config.YamlConfiguration 接口。

  • YamlShardingRuleConfiguration:分片规则配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    @Getter
    @Setter
    public class YamlShardingRuleConfiguration implements YamlConfiguration {

    private Map<String, YamlTableRuleConfiguration> tables = new LinkedHashMap<>();

    private Collection<String> bindingTables = new ArrayList<>();

    private Collection<String> broadcastTables = new ArrayList<>();

    private String defaultDataSourceName;
    // 分片策略配置
    private YamlShardingStrategyConfiguration defaultDatabaseStrategy;
    // 分片策略配置
    private YamlShardingStrategyConfiguration defaultTableStrategy;

    private YamlKeyGeneratorConfiguration defaultKeyGenerator;

    private Map<String, YamlMasterSlaveRuleConfiguration> masterSlaveRules = new LinkedHashMap<>();

    private YamlEncryptRuleConfiguration encryptRule;
    }
  • YamlShardingStrategyConfiguration:分片策略配置

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    @Getter
    @Setter
    public final class YamlShardingStrategyConfiguration implements YamlConfiguration {

    private YamlStandardShardingStrategyConfiguration standard;

    private YamlComplexShardingStrategyConfiguration complex;

    private YamlHintShardingStrategyConfiguration hint;

    private YamlInlineShardingStrategyConfiguration inline;

    private YamlNoneShardingStrategyConfiguration none;
    }
  • YamlStandardShardingStrategyConfiguration:标准备片策略配置类

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    @Getter
    @Setter
    public final class YamlStandardShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {

    private String shardingColumn;

    private String preciseAlgorithmClassName;

    private String rangeAlgorithmClassName;
    }
  • YamlComplexShardingStrategyConfiguration:复合分片策略配置类

    1
    2
    3
    4
    5
    6
    7
    8
    @Getter
    @Setter
    public final class YamlComplexShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {

    private String shardingColumns;

    private String algorithmClassName;
    }
  • YamlInlineShardingStrategyConfiguration:行表达式分片策略配置类

    1
    2
    3
    4
    5
    6
    7
    8
    @Getter
    @Setter
    public final class YamlInlineShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {

    private String shardingColumn;

    private String algorithmExpression;
    }
  • YamlHintShardingStrategyConfiguration:强制路由分片策略配置类

    1
    2
    3
    4
    5
    6
    @Getter
    @Setter
    public final class YamlHintShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {

    private String algorithmClassName;
    }
  • YamlNoneShardingStrategyConfiguration:不分片策略配置类,这是一个空类

    1
    2
    public final class YamlNoneShardingStrategyConfiguration implements YamlBaseShardingStrategyConfiguration {
    }

分布式序列策略配置

类名称:org.apache.shardingsphere.sharding.api.config.strategy.keygen.KeyGenerateStrategyConfiguration

可配置属性:

名称 数据类型 说明
column String 分布式序列列名称
keyGeneratorName String 分布式序列算法名称

算法类型的详情,请参见内置分布式序列算法列表

其它参考

  1. 分库分表需要考虑的问题及方案
  2. MySQL分表分库使用场景以及设计方式
  3. Sharding-JDBC 分布式事务

Sharding-JDBC系列(三):Sharding-JDBC分片配置示例与说明

http://blog.gxitsky.com/2019/09/26/sharding-jdbc-3-sharding-manual/

作者

光星

发布于

2019-09-26

更新于

2021-02-05

许可协议

评论