ShardingSphere 开发随笔

SpringBoot 整合方式

ShardingSphere‐JDBC 可以通过 Java 代码、YAML 文件、Spring 命名空间和 SpringBoot Starter 这四种方式进行配置，开发者可根据场景选择适合的配置方式，详情请参见 官方文档。对于 SpringBoot 项目，可以使用以下两种方式来整合 ShardingSphere‑JDBC。

特别注意

ShardingSphere 官方已停止维护 SpringBoot Starter（5.2.1 为最后版本），因为 Starter 模式过于封装不利于灵活配置，官方希望统一使用 ShardingSphere Agent 或 Proxy 而非 JDBC Starter，且 Starter 与 SpringBoot 版本高度耦合、维护成本高，内部自动配置复杂容易引发版本冲突；因此官方推荐使用 URL 模式，从 5.3.x / 5.4.x 开始可通过 jdbc:shardingsphere:classpath:sharding.yaml 统一配置，ShardingSphere-JDBC 将自动加载，无需 Starter。值得一提的是，在 ShardingSphere‑JDBC 较新版本中（5.2.1 以上版本），建议 SpringBoot 使用 YAML / Properties + JDBC 驱动 方式来整合 ShardingSphere‑JDBC。

第一种方式：YAML / Properties + JDBC 驱动

• 引入 Maven 依赖

<dependency>
  <groupId>org.apache.shardingsphere</groupId>
  <artifactId>shardingsphere-jdbc</artifactId>
  <version>5.5.0</version>
</dependency>

<!-- 如果使用 YAML 配置 ShardingSphere-JDBC，需要依赖 snakeyaml -->
<dependency>
  <groupId>org.yaml</groupId>
  <artifactId>snakeyaml</artifactId>
  <version>2.2</version>
</dependency>

• 在 application.yml（或者 application.properties）中配置：

spring:
  datasource:
    # 使用 ShardingSphere 统一提供的原生 JDBC 驱动
    driver-class-name: org.apache.shardingsphere.driver.ShardingSphereDriver
    # 指定 ShardingSphere 的配置文件路径，通过 URL 自动加载规则配置
    url: jdbc:shardingsphere:classpath:sharding.yaml

• 其中 sharding.yaml 是定义数据源、分片规则、读写分离、主从、广播表等的配置文件。
• 这种方式适合希望将分片 / 数据源配置与业务代码分离，集中管理规则。

第二种方式：YAML / Properties + SpringBoot Starter 配置

• 引入 ShardingSphere‑JDBC 的 SpringBoot Starter

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

• 在 application.yml（或者 application.properties）中直接配置分片数据源，不需要额外的 YAML 配置文件

spring:
  shardingsphere:
    datasource:
      names: ds0, ds1
      ds0:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://localhost:3306/ds0
        username: root
        password: 123456
      ds1:
        type: com.zaxxer.hikari.HikariDataSource
        driver-class-name: com.mysql.cj.jdbc.Driver
        jdbc-url: jdbc:mysql://localhost:3306/ds1
        username: root
        password: 123456
    rules:
      sharding:
        tables:
          t_order:
            actual-data-nodes: ds$->{0..1}.t_order$->{0..1}
            table-strategy:
              inline:
                sharding-column: order_id
                algorithm-expression: t_order$->{order_id % 2}
            key-generator:
              column: order_id
              type: SNOWFLAKE
          t_order_item:
            actual-data-nodes: ds$->{0..1}.t_order_item$->{0..1}
            table-strategy:
              inline:
                sharding-column: order_id
                algorithm-expression: t_order_item$->{order_id % 2}
            key-generator:
              column: order_item_id
              type: SNOWFLAKE
        binding-tables: t_order, t_order_item
        broadcast-tables: t_config
      # 可选 默认数据库分片策略
      default-database-strategy:
        inline:
          sharding-column: user_id
          algorithm-expression: ds$->{user_id % 2}

• 上面的配置示例中，演示了 分库 + 分表 + 主键生成 + 绑定表 的一个典型使用场景。
• 特别注意：Spring 表达式中使用 $->{...} 形式，以避免与 Spring 自身的占位符冲突。

ShardingSphere-JDBC 整合后的使用说明（假设使用 MyBatis 或 JPA）

• SpringBoot 整合 ShardingSphere-JDBC 之后，SpringBoot 启动时会创建一个 DataSource，对应整个逻辑数据库（逻辑库 / 逻辑数据源 + 分片规则 + 实际数据源集合）。
• 开发者可以像平常一样通过 JDBC / MyBatis / JPA 使用这个 DataSource。对于开发者来说，几乎不需要感知底层是多库多表，只要按逻辑表 + 逻辑主键查询即可，ShardingSphere 会把请求路由到真实的分片表。
• 当开发者插入数据时，ShardingSphere 会根据配置自动决定写入哪个库 / 表，并可能自动生成主键（SNOWFLAKE 或者自定义 Key Generator），对开发者透明。
• 例如，如果开发者定义了 t_order 和 t_order_item 的分片规则，那么 order_id = 123，ShardingSphere 会自动把它插到对应的 dsX.t_orderY 表中；对业务层来说，开发者只写 INSERT INTO t_order ... 即可。

ShardingSphere-JDBC 底层创建的数据源

通过 ShardingSphereDataSourceFactory 工厂类结合相应的规则配置对象，可以创建 ShardingSphereDataSource 实例。该实例实现自 JDBC 的标准 DataSource 接口，可直接用于原生 JDBC 开发，也可以在 JPA、Hibernate、MyBatis 等 ORM 框架中使用。

DataSource dataSource = ShardingSphereDataSourceFactory.createDataSource(schemaName, modeConfig, dataSourceMap, ruleConfigs, props);