ShardingSphere 5.3 系列Spring 配置升级指南 | Spring Cloud 47

一、背景

在 5.3.0 版本以前，ShardingSphere-JDBC 同时支持 Java API、YAML、Spring Boot Starter 和 Spring Namespace 等配置方式。其中，为兼容 Spring 的配置方式，给社区带来了以下难题：

• 当新增或更新 API 时，需要调整多项配置文件，工作量大
• 社区需要维护多重配置文档和示例
• Spring Bean 生命周期管理容易受到项目其他依赖的影响，比如 PostProcessor 无法正常执行
• Spring Boot Starter 和 Spring Namespace 配置风格与 ShardingSphere 标准的 YAML 有较大差别
• Spring Boot Starter 和 Spring Namespace 受 Spring 版本影响，会带来额外的配置兼容性问题

基于以上考虑，ShardingSphere 社区决定在 ShardingSphere 5.3.0 Release 中移除 Spring 全部依赖和配置支持。

那么，对需要使用 Spring Boot 或 Spring Namespace 的 ShardingSphere-JDBC 用户，应当如何接入 ShardingSphere 原有的用户怎样升级呢？本文将解为您答这些疑问。

二、影响范围

2.1 Maven依赖

升级到 ShardingSphere 5.3.0 或更高的版本，以Spring Boot项目举例原有相关的依赖将会失效：

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-jdbc-core-spring-boot-starter</artifactId>
    <version>${shardingsphere.version}</version>
</dependency>

调整为：

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>shardingsphere-jdbc-core</artifactId>
    <version>${shardingsphere.version}</version>
</dependency>

2.2 自定义算法

移除 Spring 模块会同时移除 AlgorithmProvided 相关类。若此前用户在自定义算法中有使用到 Bean 注入相关的逻辑，更新后将失效。对需要在算法中使用 Spring Bean 的场景，需开发者主动管理。

2.3 事务

用于支持方法级别事务声明的 @ShardingSphereTransactionType 注解将被同时移除。若用户有在方法级别更改事务类型的需求，请使用 Java API方式。

针对分布式事务稍后单独梳理一篇详细的配置升级文档

2.4 配置文件

在升级 5.3.0 版本后，原有的 Spring Boot Starter 或 Spring Namespace 数据源配置将会失效。

三、升级指南

3.1 ShardingSphereDriver介绍

从 5.1.2 版本开始， ShardingSphere-JDBC 提供了原生 JDBC 驱动 ShardingSphereDriver，无需修改代码，仅通过配置即可接入使用。通过这种接入方式，可以更加统一 ShardingSphere-JDBC 和 ShardingSphere-Proxy 的配置文件格式，只需少量修改即可复用。

在升级到 5.3.x 版本后，使用 Spring Boot Starter 或 Spring Namespace 的用户，推荐通过 ShardingSphereDriver 方式来接入 ShardingSphere-JDBC。

3.2 使用 Spring Boot Starter升级指导

以我的上篇文章进行举例说明：

Spring Boot集成ShardingSphere分片利器 AutoTable （二）—— 自动分片算法示例 | Spring Cloud 46

请自行参考 2.1 章节更换Maven依赖

3.2.1 配置文件升级

3.2.1.1 升级前

application.yml:

server:
  port: 8844

spring:
  application:
    name: @artifactId@
  shardingsphere:
    # 数据源配置
    datasource:
      names: ds1,ds2
      ds1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        url: jdbc:mysql://192.168.0.35:3306/db1?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true&allowMultiQueries=true&serverTimezone=Asia/Shanghai
        username: root
        password: '1qaz@WSX'
      ds2:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        url: jdbc:mysql://192.168.0.46:3306/db2?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true&allowMultiQueries=true&serverTimezone=Asia/Shanghai
        username: root
        password: '1qaz@WSX'

    # 定义规则
    rules:
      sharding:
        # 采用自动分片算法
        autoTables:
          # 取模
          t_auto_order_mod:
            actualDataSources: ds$->{
    
    1..2}
            sharding-strategy:
              standard:
                sharding-column: order_id
                sharding-algorithm-name: auto_order_mod
            # 分布式序列策略
            key-generate-strategy:
              # 自增列名称，缺省表示不使用自增主键生成器
              column: order_id
              # 分布式序列算法名称
              key-generator-name: snowflake
          # 散列取模
          t_auto_order_hash_mod:
            actualDataSources: ds1
            sharding-strategy:
              standard:
                sharding-column: order_id
                sharding-algorithm-name: auto_order_hash_mod
            # 分布式序列策略
            key-generate-strategy:
              # 自增列名称，缺省表示不使用自增主键生成器
              column: order_id
              # 分布式序列算法名称
              key-generator-name: snowflake
          # 容量范围
          t_auto_order_volume_range:
            actualDataSources: ds$->{
    
    1..2}
            sharding-strategy:
              standard:
                sharding-column: price
                sharding-algorithm-name: auto_order_volume_range
            # 分布式序列策略
            key-generate-strategy:
              # 自增列名称，缺省表示不使用自增主键生成器
              column: order_id
              # 分布式序列算法名称
              key-generator-name: snowflake
          # 边界范围
          t_auto_order_boundary_range:
            actualDataSources: ds$->{
    
    1..2}
            sharding-strategy:
              standard:
                sharding-column: price
                sharding-algorithm-name: auto_order_boundary_range
            # 分布式序列策略
            key-generate-strategy:
              # 自增列名称，缺省表示不使用自增主键生成器
              column: order_id
              # 分布式序列算法名称
              key-generator-name: snowflake
          # 自动日期间隔
          t_auto_order_auto_interval:
            actualDataSources: ds$->{
    
    1..2}
            sharding-strategy:
              standard:
                sharding-column: create_time
                sharding-algorithm-name: auto_order_auto_interval
            # 分布式序列策略
            key-generate-strategy:
              # 自增列名称，缺省表示不使用自增主键生成器
              column: order_id
              # 分布式序列算法名称
              key-generator-name: snowflake
        # 分片算法配置
        sharding-algorithms:
          # 取模
          auto_order_mod:
            type: MOD
            props:
              sharding-count: 6
          # 散列取模
          auto_order_hash_mod:
            type: HASH_MOD
            props:
              sharding-count: 6
          # 容量范围
          auto_order_volume_range:
            type: VOLUME_RANGE
            props:
              range-lower: 0
              range-upper: 20000
              sharding-volume: 10000
          # 边界范围
          auto_order_boundary_range:
            type: BOUNDARY_RANGE
            props:
              sharding-ranges: 10,15,100,12000,16000
          # 自动日期间隔
          auto_order_auto_interval:
            type: AUTO_INTERVAL
            props:
              datetime-lower: 2023-05-07 00:00:00
              datetime-upper: 2023-05-10 00:00:00
              sharding-seconds: 86400
        # 分布式序列算法配置（如果是自动生成的，在插入数据的sql中就不要传id，null也不行，直接插入字段中就不要有主键的字段）
        keyGenerators:
          # 分布式序列算法名称
          snowflake:
            # 分布式序列算法类型
            type: SNOWFLAKE
    props:
      sql-show: true #显示sql

mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

3.2.1.2 升级后

application.yml:将原有的 ShardingSphere 相关配置替换为 ShardingSphereDriver 配置项：

server:
  port: 8844

spring:
  application:
    name: @artifactId@
  datasource:
    driver-class-name: org.apache.shardingsphere.driver.ShardingSphereDriver
    url: jdbc:shardingsphere:classpath:shading-auto-tables-algorithm.yaml
mybatis:
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl

在 resources 目录下新建 yaml 配置文件，如: shading-auto-tables-algorithm.yaml，并按照 用户手册-YAML配置 改写原有配置内容：

dataSources:
  ds1:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.mysql.cj.jdbc.Driver
    jdbcUrl: jdbc:mysql://192.168.0.35:3306/db1?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true&allowMultiQueries=true&serverTimezone=Asia/Shanghai
    username: root
    password: '1qaz@WSX'
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1

  ds2:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.mysql.cj.jdbc.Driver
    jdbcUrl: jdbc:mysql://192.168.0.46:3306/db2?useUnicode=true&characterEncoding=UTF-8&rewriteBatchedStatements=true&allowMultiQueries=true&serverTimezone=Asia/Shanghai
    username: root
    password: '1qaz@WSX'
    connectionTimeoutMilliseconds: 30000
    idleTimeoutMilliseconds: 60000
    maxLifetimeMilliseconds: 1800000
    maxPoolSize: 50
    minPoolSize: 1
rules:
  - !SHARDING
    autoTables:
      # 取模
      t_auto_order_mod:
        actualDataSources: ds$->{
    
    1..2}
        shardingStrategy:
          standard:
            shardingColumn: order_id
            shardingAlgorithmName: auto_order_mod
        # 分布式序列策略
        keyGenerateStrategy:
          # 自增列名称，缺省表示不使用自增主键生成器
          column: order_id
          # 分布式序列算法名称
          keyGeneratorName: snowflake
      # 散列取模
      t_auto_order_hash_mod:
        actualDataSources: ds1
        shardingStrategy:
          standard:
            shardingColumn: order_id
            shardingAlgorithmName: auto_order_hash_mod
        # 分布式序列策略
        keyGenerateStrategy:
          # 自增列名称，缺省表示不使用自增主键生成器
          column: order_id
          # 分布式序列算法名称
          keyGeneratorName: snowflake
      # 容量范围
      t_auto_order_volume_range:
        actualDataSources: ds$->{
    
    1..2}
        shardingStrategy:
          standard:
            shardingColumn: price
            shardingAlgorithmName: auto_order_volume_range
        # 分布式序列策略
        keyGenerateStrategy:
          # 自增列名称，缺省表示不使用自增主键生成器
          column: order_id
          # 分布式序列算法名称
          keyGeneratorName: snowflake
      # 边界范围
      t_auto_order_boundary_range:
        actualDataSources: ds$->{
    
    1..2}
        shardingStrategy:
          standard:
            shardingColumn: price
            shardingAlgorithmName: auto_order_boundary_range
        # 分布式序列策略
        keyGenerateStrategy:
          # 自增列名称，缺省表示不使用自增主键生成器
          column: order_id
          # 分布式序列算法名称
          keyGeneratorName: snowflake
      # 自动日期间隔
      t_auto_order_auto_interval:
        actualDataSources: ds$->{
    
    1..2}
        shardingStrategy:
          standard:
            shardingColumn: create_time
            shardingAlgorithmName: auto_order_auto_interval
        # 分布式序列策略
        keyGenerateStrategy:
          # 自增列名称，缺省表示不使用自增主键生成器
          column: order_id
          # 分布式序列算法名称
          keyGeneratorName: snowflake
    # 分片算法配置
    shardingAlgorithms:
      # 取模
      auto_order_mod:
        type: MOD
        props:
          sharding-count: 6
      # 散列取模
      auto_order_hash_mod:
        type: HASH_MOD
        props:
          sharding-count: 6
      # 容量范围
      auto_order_volume_range:
        type: VOLUME_RANGE
        props:
          range-lower: 0
          range-upper: 20000
          sharding-volume: 10000
      # 边界范围
      auto_order_boundary_range:
        type: BOUNDARY_RANGE
        props:
          sharding-ranges: 10,15,100,12000,16000
      # 自动日期间隔
      auto_order_auto_interval:
        type: AUTO_INTERVAL
        props:
          datetime-lower: "2023-05-07 00:00:00"
          datetime-upper: "2023-05-10 00:00:00"
          sharding-seconds: 86400
    # 分布式序列算法配置（如果是自动生成的，在插入数据的sql中就不要传id，null也不行，直接插入字段中就不要有主键的字段）
    keyGenerators:
      # 分布式序列算法名称
      snowflake:
        # 分布式序列算法类型
        type: SNOWFLAKE
props:
  sql-show: true

四、结语

此次升级，大大减少了 ShardingSphere-JDBC 和 ShardingSphere-Proxy 在配置方面的差异，为 ShardingSphere-JDBC 用户顺利过渡到 ShardingSphere 集群架构打好了基础，在 API 标准化、提升配置兼容性方面迈出了坚实的一步。

对于 ShardingSphere 新用户而言，ShardingSphereDriver 的配置方式也能减少配置侵入性，上手更简单。