ShardingSphere 5.3 系列升级解读：Spring 配置升级指南

关注

转载最新推荐文章于 2026-08-24 15:50:36 发布 1.5w 阅读 AI 写同款· GEO 优化 ›

AI权益加码！Claude Code、Cursor等20+工具免费用！购周边限时加赠Coding Plan Lite，畅享主流AI工具！学习进阶更高效！阅读详情

背景

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

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

例如在最新发版的 Spring Boot 3.0.0 中，移除了对 2.x 版本 spring.factories 的支持 [3][4]，这为想要升级但正在使用 ShardingSphere Spring Boot Starter 的用户带来了挑战，而升级 Spring Boot 依赖也会为 ShardingSphere 用户带来新的兼容性问题。基于以上考虑，ShardingSphere 社区决定在 ShardingSphere 5.3.0 Release 中移除 Spring 全部依赖和配置支持。

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

影响范围

为方便正在使用以下功能的用户来评估升级影响，我们梳理了此次调整的影响范围：

ShardingSphere Spring Boot Starter

ShardingSphere Spring Namespace

Maven 坐标

升级到 ShardingSphere 5.3.0 或更高的版本，原有 Spring 相关的依赖坐标将会失效。

<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-spring-namespace</artifactId>
    <version>${shardingsphere.version}</version>
</dependency>

调整为

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

自定义算法

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

事务

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

配置文件

在升级 5.3.0 版本后，原有的 Spring Boot Starter 或 Spring Namespace 数据源配置将会失效。具体的配置升级方式，请参考下一章节。

升级指导

ShardingSphereDriver

从 5.1.2 版本开始，工程师无需修改代码。ShardingSphere-JDBC 提供了原生 JDBC 驱动 ShardingSphereDriver，工程师仅通过配置即可接入使用，通过这种接入方式：‍

可以更加统一 ShardingSphere-JDBC 和 ShardingSphere-Proxy 的配置文件格式，只需少量修改即可复用，详情见用户手册-JDBC 驱动[6]。在升级到 5.3.x 版本后，使用 Spring Boot Starter 或 Spring Namespace 的用户：‍

推荐使用 ShardingSphereDriver 方式来接入 ShardingSphere-JDBC。

正在使用 Spring Boot Starter 如何升级

升级前

在 application.yml 中，ShardingSphere 相关的配置如下：

application.yml

spring:
  shardingsphere:
    database:
      name: sharding_db
    datasource:
      names: ds_0,ds_1
      ds_0:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://127.0.0.1:3306/demo_ds_0?serverTimezone=UTC&useSSL=false
        username: root
        password:
      ds_1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://127.0.0.1:3306/demo_ds_1?serverTimezone=UTC&useSSL=false
        username: root
        password:
    rules:
      sharding:
        default-database-strategy:
          standard:
            sharding-column: id
            sharding-algorithm-name: database_inline
        tables:
          t_order:
            actual-data-nodes: ds_$->{0..1}.t_order_$->{0..1}
            table-strategy:
              standard:
                sharding-column: count
                sharding-algorithm-name: t_order_inline
        sharding-algorithms: 
          database_inline:
            type: INLINE
            props:
              algorithm-expression: ds_$->{user_id % 2}
          t_order_inline:
            type: INLINE
            props:
              algorithm-expression: t_order_$->{order_id % 2}
    props:
      sql-show: true

升级后

在 resources 目录下新建 YAML 配置文件，如 sharding.yaml，并按照用户手册-YAML配置 [7] 改写原有配置内容。

sharding.yaml

dataSources:
  ds_0:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.mysql.jdbc.Driver
    jdbcUrl: jdbc:mysql://127.0.0.1:3306/demo_ds_0?serverTimezone=UTC&useSSL=false
    username: root
    password:
  ds_1:
    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
    driverClassName: com.mysql.jdbc.Driver
    jdbcUrl: jdbc:mysql://127.0.0.1:3306/demo_ds_1?serverTimezone=UTC&useSSL=false
    username: root
    password:

rules:
- !SHARDING
  tables:
    t_order:
      actualDataNodes: ds_$->{0..1}.t_order_$->{0..1}
      tableStrategy:
        standard:
          shardingColumn: count
          shardingAlgorithmName: t_order_inline
  defaultDatabaseStrategy:
    standard:
      shardingColumn: id
      shardingAlgorithmName: database_inline
  shardingAlgorithms:
    database_inline:
      type: INLINE
      props:
        algorithm-expression: ds_$->{user_id % 2}
    t_order_inline:
      type: INLINE
      props:
        algorithm-expression: t_order_$->{order_id % 2}

props:
  sql-show: true

如果以集群模式部署，当对应 namespace 已有所需配置：sharding.yaml 中仅配置 mode 即可

mode:
  type: Cluster
  repository:
    type: ZooKeeper
    props:
      namespace: governance_ds
      server-lists: localhost:2181
      retryIntervalMilliseconds: 500
      timeToLiveSeconds: 60
      maxRetries: 3
      operationTimeoutMilliseconds: 500

application.yml

将原有的 ShardingSphere 相关配置替换为 ShardingSphereDriver 配置项：

spring:
  datasource:
    driver-class-name: org.apache.shardingsphere.driver.ShardingSphereDriver
    url: jdbc:shardingsphere:classpath:sharding.yaml

正在使用 Spring Namespace 如何升级

升级前

spring-sharding.xml

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:shardingsphere="http://shardingsphere.apache.org/schema/shardingsphere/datasource"
       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://www.springframework.org/schema/tx 
                           http://www.springframework.org/schema/tx/spring-tx.xsd
                           http://www.springframework.org/schema/context 
                           http://www.springframework.org/schema/context/spring-context.xsd
                           http://shardingsphere.apache.org/schema/shardingsphere/datasource
                           http://shardingsphere.apache.org/schema/shardingsphere/datasource/datasource.xsd
                           http://shardingsphere.apache.org/schema/shardingsphere/sharding
                           http://shardingsphere.apache.org/schema/shardingsphere/sharding/sharding.xsd
                           ">

    <bean id="ds_0" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close">
        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
        <property name="jdbcUrl" value="jdbc:mysql://127.0.0.1:3306/demo_ds_0?serverTimezone=UTC&amp;useSSL=false&amp;useUnicode=true&amp;characterEncoding=UTF-8"/>
        <property name="username" value="root"/>
        <property name="password" value=""/>
    </bean>
    
    <bean id="ds_1" class="com.zaxxer.hikari.HikariDataSource" destroy-method="close">
        <property name="driverClassName" value="com.mysql.jdbc.Driver"/>
        <property name="jdbcUrl" value="jdbc:mysql://127.0.0.1:3306/demo_ds_1?serverTimezone=UTC&amp;useSSL=false&amp;useUnicode=true&amp;characterEncoding=UTF-8"/>
        <property name="username" value="root"/>
        <property name="password" value=""/>
    </bean>
    
    <sharding:standard-strategy id="databaseStrategy" sharding-column="user_id" algorithm-ref="inlineStrategyShardingAlgorithm" />

    <sharding:sharding-algorithm id="inlineStrategyShardingAlgorithm" type="INLINE">
        <props>
            <prop key="algorithm-expression">ds_${user_id % 2}</prop>
        </props>
    </sharding:sharding-algorithm>
    
    <sharding:standard-strategy id="orderTableStrategy" sharding-column="order_id" algorithm-ref="orderTableAlgorithm" />
    
    <sharding:sharding-algorithm id="orderTableAlgorithm" type="INLINE">
        <props>
            <prop key="algorithm-expression">t_order_${order_id % 2}</prop>
        </props>
    </sharding:sharding-algorithm>
    
    <sharding:rule id="shardingRule">
        <sharding:table-rules>
            <sharding:table-rule logic-table="t_order" database-strategy-ref="databaseStrategy" table-strategy-ref="orderTableStrategy" />
        </sharding:table-rules>
    </sharding:rule>
    
    <shardingsphere:data-source id="shardingDataSource" database-name="sharding-databases" data-source-names="ds_0,ds_1" rule-refs="shardingRule" >
        <props>
            <prop key="sql-show">true</prop>
        </props>
    </shardingsphere:data-source>
</beans>

升级后

sharding.yaml

新增 sharding.yaml 配置文件，格式同 Spring Boot 示例中一致。

spring-sharding.xml

spring-sharding.xml 中移除原有 ShardingSphere 配置，替换为 ShardingSphereDriver 配置内容。

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
                           http://www.springframework.org/schema/beans/spring-beans.xsd">
    
    <bean id="shardingDataSource" class="org.springframework.jdbc.datasource.SimpleDriverDataSource">
        <property name="driverClass" value="org.apache.shardingsphere.driver.ShardingSphereDriver" />
        <property name="url" value="jdbc:shardingsphere:classpath:sharding.yaml" />
    </bean>
</beans>

🎉 完成以上配置，即可畅享

ShardingSphere-JDBC 全新版本！

结语 & 参考🔗‍

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

对于新用户而言，ShardingSphereDriver 的配置方式也能减少配置侵入性，上手更简单。此后，Apache ShardingSphere 社区也能更好的专注于自身功能迭代，为用户和开发者带来更多更好的特性。

以上就是本次分享的全部内容，关于配置升级的更多信息，请参考官网用户手册 [8]。若读者对 ShardingSphere 有任何疑问或建议，欢迎在 GitHub issue 列表 [9] 提出，或可前往中文社区 [10] 交流讨论。

[1] issue: ShardingSphereAlgorithmPostProcessor.init() https://github.com/apache/shardingsphere/issues/18093
[2] issue: ShardingSphere Bean is not eligible for getting processed by all BeanPostProcessors https://github.com/apache/shardingsphere/issues/11650
[3] Spring Boot: Remove spring.factories auto-configuration support https://github.com/spring-projects/spring-boot/issues/29699
[4] issue: spring boot 3.0.0-M5 Failed to determine a suitable driver class https://github.com/apache/shardingsphere/issues/21225
[5] 用户手册-分布式事务 https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-jdbc/special-api/transaction/java-api/
[6] 用户手册-JDBC 驱动 https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/
[7] 用户手册-YAML 配置 https://shardingsphere.apache.org/document/current/cn/user-manual/shardingsphere-jdbc/yaml-config/
[8] 用户手册：https://shardingsphere.apache.org/document/current/cn/user-manual/
[9] GitHub issue 列表：https://github.com/apache/shardingsphere/issues
[10] 中文社区：https://community.sphere-ex.com/