文章目录一、技术栈版本适配避坑核心二、项目依赖引入Maven2.1 SpringBoot2.x 完整依赖2.2 SpringBoot3.x 适配调整三、数据库环境准备2库4表实战场景3.1 创建分片数据库3.2 批量创建分片数据表四、ShardingSphere5 核心配置application.yml4.1 完整可运行配置文件4.2 核心配置逐行解析五、业务代码实战零侵入CRUD5.1 订单实体类5.2 Mapper接口5.3 测试接口验证分片路由六、项目启动与结果验证6.1 启动项目6.2 接口测试七、常用扩展功能配置7.1 单库分表配置轻量化方案7.2 广播表配置解决跨库关联八、生产环境高频踩坑总结8.1 启动报错依赖版本不兼容8.2 查询无数据、路由异常8.3 主键重复、插入失败8.4 控制台无SQL日志本文基于ShardingSphere5.3.2 稳定版手把手讲解 SpringBoot 完整整合流程包含环境适配、依赖引入、数据库搭建、全量配置、代码实战、核心功能讲解及生产踩坑方案所有代码可直接复制上线使用。一、技术栈版本适配避坑核心ShardingSphere5 对框架版本有严格适配要求版本混用会直接导致启动报错、分片失效新手务必严格对照以下适配组合SpringBoot2.x 适配组合SpringBoot2.7.x ShardingSphere5.3.2 MySQL8.0 MyBatis-Plus3.5.xSpringBoot3.x 适配组合SpringBoot3.2.x ShardingSphere5.5.x JDK17 MySQL8.0核心说明ShardingSphere5 彻底废弃4.x旧依赖包名统一使用shardingsphere-jdbc-core-spring-boot-starter新旧依赖不可混用二、项目依赖引入Maven新建或打开已有 SpringBoot 项目在 pom.xml 中引入核心依赖本文提供生产通用稳定配置包含分片核心、数据库驱动、持久层框架全套依赖。2.1 SpringBoot2.x 完整依赖!-- SpringBoot Web基础 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- ShardingSphere5 分片核心依赖 -- dependency groupIdorg.apache.shardingsphere/groupId artifactIdshardingsphere-jdbc-core-spring-boot-starter/artifactId version5.3.2/version /dependency !-- MySQL8驱动 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- MyBatis-Plus 持久层框架 -- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version3.5.3.1/version /dependency !-- Lombok 简化代码 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency2.2 SpringBoot3.x 适配调整SpringBoot3 项目只需修改 ShardingSphere 版本其余依赖通用适配最新特性version5.5.0/version三、数据库环境准备2库4表实战场景本次实战采用企业最常用的水平分库分表方案模拟订单大数据量场景搭建2个数据库每个数据库包含2张结构一致的订单表实现数据均匀分片存储。3.1 创建分片数据库新建两个独立数据库统一编码为 utf8mb4适配全字符集CREATE DATABASE IF NOT EXISTS order_db0 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE DATABASE IF NOT EXISTS order_db1 DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;3.2 批量创建分片数据表order_db0、order_db1 两个库中分别创建 t_order_0、t_order_1 两张分片表四张物理表结构完全一致-- 切换数据库 order_db0 USE order_db0; CREATE TABLE IF NOT EXISTS t_order_0 ( id BIGINT COMMENT 分布式唯一主键, user_id BIGINT NOT NULL COMMENT 分片键-用户ID, order_no VARCHAR(32) NOT NULL COMMENT 订单编号, amount DECIMAL(10,2) COMMENT 订单金额, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_id(user_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; CREATE TABLE IF NOT EXISTS t_order_1 LIKE t_order_0; -- 切换数据库 order_db1 执行相同建表语句 USE order_db1; CREATE TABLE IF NOT EXISTS t_order_0 LIKE t_order_0; CREATE TABLE IF NOT EXISTS t_order_1 LIKE t_order_0;四、ShardingSphere5 核心配置application.ymlShardingSphere5 所有规则统一配置在spring.shardingsphere节点下摒弃了4.x混乱的配置方式支持行表达式简化多库多表配置。本次配置实现user_id 取模分库取模分表搭配雪花算法分布式ID全程零代码侵入。4.1 完整可运行配置文件spring: # ShardingSphere5 分片核心配置 shardingsphere: # 多数据源配置 datasource: names: ds0,ds1 # 第一个分片库 order_db0 ds0: type: com.zaxxer.hikari.HikariDataSource driver-class-name: com.mysql.cj.jdbc.Driver jdbc-url: jdbc:mysql://127.0.0.1:3306/order_db0?useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: 你的数据库密码 # 第二个分片库 order_db1 ds1: type: com.zaxxer.hikari.HikariDataSource driver-class-name: com.mysql.cj.jdbc.Driver jdbc-url: jdbc:mysql://127.0.0.1:3306/order_db1?useSSLfalseserverTimezoneAsia/ShanghaiallowPublicKeyRetrievaltrue username: root password: 你的数据库密码 # 分片规则配置 rules: sharding: # 逻辑表分片规则 tables: # 业务操作逻辑表名无需真实存在 t_order: # 匹配所有物理数据节点 actual-data-nodes: ds$-{0..1}.t_order_$-{0..1} # 分库策略 database-strategy: standard: sharding-column: user_id sharding-algorithm-name: order-mod-inline # 分表策略 table-strategy: standard: sharding-column: user_id sharding-algorithm-name: order-mod-inline # 分布式主键策略 key-generate-strategy: column: id key-generator-name: snowflake # 分片算法定义 sharding-algorithms: order-mod-inline: type: INLINE props: # 取模分片算法user_id % 2 algorithm-expression: $-{user_id % 2} # 分布式ID生成器 key-generators: snowflake: type: SNOWFLAKE props: worker-id: 1 # 单机固定1集群需保证节点唯一 # 全局参数配置 props: sql-show: true # 开启SQL日志打印查看分片路由详情 # MyBatis-Plus基础配置 mybatis-plus: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.sharding.entity configuration: map-underscore-to-camel-case: true4.2 核心配置逐行解析datasource.names声明所有分片数据源别名多个用逗号分隔actual-data-nodes行表达式批量匹配所有物理库表无需逐个手动配置简洁高效standard标准分片策略适用于单分片键场景支持等值查询、IN查询精准路由INLINE行表达式算法新手首选基于取模、范围规则分片维护成本最低snowflake分布式ID全局唯一主键彻底解决多库自增ID重复问题sql-showtrue控制台打印真实路由SQL是调试分片规则的核心利器五、业务代码实战零侵入CRUDSharding-JDBC 最大优势就是业务代码零侵入整合完成后原有 MyBatis、MyBatis-Plus 写法完全不变只需操作逻辑表中间件自动完成SQL解析、路由、数据聚合。5.1 订单实体类实体类只需标注逻辑表名主键设置为雪花算法自动生成package com.sharding.entity; import com.baomidou.mybatisplus.annotation.IdType; import com.baomidou.mybatisplus.annotation.TableId; import com.baomidou.mybatisplus.annotation.TableName; import lombok.Data; import java.math.BigDecimal; import java.time.LocalDateTime; Data TableName(t_order) // 对应配置中的逻辑表 public class TOrder { // 雪花算法自动生成分布式ID TableId(type IdType.ASSIGN_ID) private Long id; // 分片键 private Long userId; // 订单编号 private String orderNo; // 订单金额 private BigDecimal amount; // 创建时间 private LocalDateTime createTime; }5.2 Mapper接口package com.sharding.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.sharding.entity.TOrder; import org.apache.ibatis.annotations.Mapper; Mapper public interface OrderMapper extends BaseMapperTOrder { }5.3 测试接口验证分片路由编写测试接口插入不同 userId 的订单数据验证自动分片路由package com.sharding.controller; import com.sharding.entity.TOrder; import com.sharding.mapper.OrderMapper; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.annotation.Resource; import java.math.BigDecimal; RestController RequestMapping(/order) public class OrderController { Resource private OrderMapper orderMapper; GetMapping(/add) public String addOrder() { // userId1 1%21 路由至 ds1.t_order_1 TOrder order1 new TOrder(); order1.setUserId(1L); order1.setOrderNo(ORD20260712001); order1.setAmount(new BigDecimal(89.90)); orderMapper.insert(order1); // userId2 2%20 路由至 ds0.t_order_0 TOrder order2 new TOrder(); order2.setUserId(2L); order2.setOrderNo(ORD20260712002); order2.setAmount(new BigDecimal(129.90)); orderMapper.insert(order2); return 分片数据插入成功查看控制台路由日志; } }六、项目启动与结果验证6.1 启动项目启动 SpringBoot 项目无报错即代表 ShardingSphere 整合成功数据源、分片规则加载完成。6.2 接口测试访问接口http://localhost:8080/order/add查看控制台SQL日志可清晰看到userId1 的数据插入ds1.t_order_1userId2 的数据插入ds0.t_order_0业务层无需感知多库多表完全由 ShardingSphere 自动完成分片路由整合生效。七、常用扩展功能配置7.1 单库分表配置轻量化方案若仅需解决单表数据量大问题无需分库可简化为单库多表配置仅保留一个数据源即可适配中小数据量场景。7.2 广播表配置解决跨库关联字典表、配置表等小表可配置为广播表自动同步到所有分片库解决跨库JOIN查询问题只需在sharding规则中新增广播表配置即可。八、生产环境高频踩坑总结8.1 启动报错依赖版本不兼容问题原因SpringBoot3 搭配低版本 ShardingSphere5.3.x存在自动配置冲突解决方案SpringBoot3 统一使用 5.5.0 及以上版本SpringBoot2 稳定使用5.3.28.2 查询无数据、路由异常问题原因查询SQL未携带分片键触发全库全表广播查询性能极差且数据错乱解决方案业务查询强制携带分片键禁止无分片键全量查询8.3 主键重复、插入失败问题原因未关闭数据库自增未配置雪花算法ID解决方案实体类主键使用 ASSIGN_IDyml 开启雪花算法生成策略8.4 控制台无SQL日志解决方案确认sql-show: true配置生效排查日志级别配置