发表更新Sharding-JDBC系列1 小时读完 (大约9034个字)

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

许可协议

#

喜欢这篇文章？打赏一下作者吧

评论

关注我
×