简介本资源是一套基于Spring Boot的多数据源与分库分表实战项目面向Java后端开发者及数据库架构进阶学习者聚焦高并发场景下的数据层扩展难题。项目整合Dynamic-Datasource实现多数据源动态路由采用Sharding-JDBC完成逻辑库表拆分并集成Druid连接池进行性能监控与管理辅以MyBatis-Plus简化CRUD、Lombok减少模板代码、JUnit保障单元测试覆盖。压缩包共162个文件含115个XML映射文件定义SQL与结果映射、14个Java业务类如OrderController、UserTestServiceImpl等、6个YML配置含多源与分片规则、以及日志、测试、构建相关文件整体仅164KB轻量易读。已有624人学习下载提供开箱即用的完整工程结构、典型分片场景如用户/订单水平分表的可运行示例、清晰的测试用例与分层实现逻辑便于快速理解多数据源切换与Sharding-JDBC集成要点。1. 多数据源数据库分库分表当单库扛不住百万级订单并发写入时它真能救场某电商大促压测现场订单服务在 QPS 突破 8000 后开始持续超时DB CPU 长期 95%慢查日志里全是INSERT INTO order_info的堆积。运维拉出主库监控图——连接数打满、redo log 写入延迟飙升、从库同步 lag 超过 47 秒。团队紧急切流、加索引、调参全无效。最后上线的方案不是扩容而是把原来一个order_db拆成 8 个物理库order_db_00 ~ order_db_07每个库再按用户 ID 哈希分 16 张表order_info_00 ~ order_info_15。核心逻辑没动一行业务代码只靠 Spring Boot ShardingSphere-JDBC 多数据源路由3 小时内完成灰度发布QPS 稳定在 2.3w平均响应从 1.2s 降到 86ms。这不是理论 Demo是真实跑在生产环境的分库分表骨架工程——它不教你“什么是分片键”而是直接给你一套可编译、可调试、可替换为 MySQL/PostgreSQL、可对接现有 MyBatis-Plus 的最小可行实现。适合正在被单库性能卡脖子、又不敢贸然上 ShardingSphere-Proxy 的后端开发者尤其适合已有 Spring Boot 2.7/3.x 项目想渐进式改造的团队。2. 技术栈与架构设计Spring Boot 如何用原生能力接管分库分表的“路由权”这个项目不是封装好的黑匣子而是一套显式暴露所有路由决策点的轻量级实现。它绕开了 ShardingSphere-Proxy 的网络层复杂度也避开了 MyCat 的独立进程依赖选择在 Spring Boot 应用进程内完成分片逻辑。关键在于所有分库分表规则都由 Java 代码定义而非 YAML 配置驱动——这意味着你可以用 IDE 调试分片算法、在分片前插入审计日志、甚至根据请求 Header 动态切换分片策略。2.1 核心依赖与版本对齐项目基于 Spring Boot 3.1.0JDK 17关键依赖如下!-- 多数据源管理 -- dependency groupIdcom.baomidou/groupId artifactIddynamic-datasource-spring-boot-starter/artifactId version4.3.2/version /dependency !-- 分片逻辑核心 -- dependency groupIdorg.apache.shardingsphere/groupId artifactIdshardingsphere-jdbc-core-spring-boot-starter/artifactId version5.3.2/version /dependency !-- ORM 层兼容 MyBatis 和 MyBatis-Plus-- dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-spring-boot3-starter/artifactId version3.5.3.1/version /dependency提示ShardingSphere-JDBC 5.3.x 是目前与 Spring Boot 3.x 兼容最稳定的版本。若你用的是 Spring Boot 2.7.x请降级至shardingsphere-jdbc-core-spring-boot-starter:5.2.1否则会因jakarta.*包路径冲突导致DataSource初始化失败。2.2 分库分表拓扑结构8 库 × 16 表的真实映射关系项目默认采用user_id作为分片键分库逻辑为user_id % 8分表逻辑为user_id % 16。物理库名格式为order_db_{00..07}逻辑表名为order_info实际映射到order_db_03.order_info_07这类地址。这种设计规避了“热点用户”问题比如某个大 V 用户订单集中写入单表但要求user_id必须为数字且全局唯一。目录结构中sharding包下有三个核心类DatabaseShardingAlgorithm.java实现StandardShardingAlgorithmInteger重写doSharding()方法输入CollectionString availableTargetNames当前可用库名列表和ShardingValueInteger分片值返回目标库名TableShardingAlgorithm.java同理负责表路由ShardingConfiguration.java通过Bean注册上述算法并绑定到ShardingRuleConfiguration最终注入ShardingSphereDataSource。2.3 数据源初始化链路从 application.yml 到真实 Connection整个数据源加载流程如下application.yml中声明 8 个数据源别名 →DynamicRoutingDataSource加载所有DataSourceBean →ShardingSphereDataSource接收这些数据源并注册分片规则 → 最终SqlSessionFactory使用该DataSource执行 SQL。关键配置片段application.ymlspring: shardingsphere: props: sql-show: true # 开发期必开看实际执行的物理 SQL datasource: names: ds-0,ds-1,ds-2,ds-3,ds-4,ds-5,ds-6,ds-7 ds-0: driver-class-name: com.mysql.cj.jdbc.Driver jdbc-url: jdbc:mysql://127.0.0.1:3306/order_db_00?useSSLfalseserverTimezoneAsia/Shanghai username: root password: 123456 # ... ds-1 ~ ds-7 同理指向不同库 rules: - !SHARDING tables: order_info: actual-data-nodes: ds-$-{0..7}.order_info_$-{0..15} database-strategy: standard: sharding-column: user_id sharding-algorithm-name: db-inline table-strategy: standard: sharding-column: user_id sharding-algorithm-name: tbl-inline sharding-algorithms: db-inline: type: INLINE props: algorithm-expression: ds-$-{user_id % 8} tbl-inline: type: INLINE props: algorithm-expression: order_info_$-{user_id % 16}注意这里的INLINE算法只是开发期快速验证用。生产必须替换为 Java 类实现即前面提到的DatabaseShardingAlgorithm因为 INLINE 不支持调试、无法记录分片日志、无法做异常兜底。2.4 分片键强制校验机制防止“漏掉 user_id”导致全库扫描这是项目最实用的设计之一所有涉及order_info表的INSERT/UPDATE/SELECT操作都必须携带user_id条件。否则框架会在 SQL 解析阶段抛出ShardingSphereSQLException拒绝执行。实现原理在ShardingSphereSQLChecker.java中public class ShardingSphereSQLChecker implements SQLCheckHandler { Override public void check(SQLStatementContext? sqlStatementContext, ListObject parameters) { if (sqlStatementContext instanceof InsertStatementContext) { InsertStatementContext insertCtx (InsertStatementContext) sqlStatementContext; // 检查 INSERT 的列中是否包含 user_id boolean hasUserId insertCtx.getColumns().stream() .anyMatch(column - user_id.equalsIgnoreCase(column.getIdentifier().getValue())); if (!hasUserId) { throw new IllegalArgumentException(INSERT into order_info must contain user_id column); } } else if (sqlStatementContext instanceof SelectStatementContext) { SelectStatementContext selectCtx (SelectStatementContext) sqlStatementContext; // 检查 WHERE 条件中是否含 user_id ? boolean hasUserIdInWhere selectCtx.getWhere().isPresent() selectCtx.getWhere().get().getExpr().toString().contains(user_id); if (!hasUserIdInWhere) { throw new IllegalArgumentException(SELECT from order_info must have user_id ? in WHERE clause); } } } }注意该检查器需在ShardingSphereDataSource初始化前注册到SQLCheckEngine。项目已通过PostConstruct在ShardingConfiguration中完成注册无需额外操作。3. 本地运行实操5 分钟启动一个带分库分表的 Spring Boot Web 服务别被“分库分表”吓住——这个项目设计之初就为降低启动门槛。你不需要 Docker、不需要远程 DB只要本机装了 MySQL 5.7就能跑通全部流程。3.1 准备 8 个物理数据库一键脚本项目根目录下提供init_databases.sql内容为CREATE DATABASE IF NOT EXISTS order_db_00 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE DATABASE IF NOT EXISTS order_db_01 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; -- ... 直到 order_db_07执行方式Linux/macOSmysql -uroot -p123456 init_databases.sql提示密码123456可在application.yml中统一修改。若 MySQL 未启用local_infile需在 MySQL 配置中添加local_infileON并重启。3.2 初始化每库 16 张表MyBatis-Plus 自动建表项目使用MyBatis-Plus的AutoGeneratorSpring Boot Starter实现启动时自动建表。只需确保application.yml中mybatis-plus.global-config.db-config.id-type设为AUTO并在OrderInfoMapper.java上添加TableName(order_info)注解。启动应用后控制台会输出类似日志[INFO] Table order_info_00 created in database order_db_00 [INFO] Table order_info_01 created in database order_db_00 ... [INFO] All 128 tables (8×16) initialized successfully.若未看到该日志请检查OrderInfoEntity.java中TableId(type IdType.AUTO)是否存在以及application.yml中mybatis-plus.mapper-locations是否指向mapper/*.xml。3.3 发送测试请求见证分片效果项目内置/api/order/create接口接收 JSON{ userId: 123456789, productId: P1001, amount: 299.00, status: PAID }发送命令用 curlcurl -X POST http://localhost:8080/api/order/create \ -H Content-Type: application/json \ -d {userId:123456789,productId:P1001,amount:299.00,status:PAID}观察控制台 SQL 日志sql-show: trueActual SQL: ds-0 ::: INSERT INTO order_info_01 (id, user_id, product_id, amount, status) VALUES (?, ?, ?, ?, ?) Actual SQL: ds-3 ::: SELECT * FROM order_info_05 WHERE user_id ?看到ds-0和order_info_01——说明123456789 % 8 1应为 ds-1等等这里有个坑见下一节→ 实际计算123456789 % 8 5所以应为ds-5。若日志显示ds-0说明你本地 MySQL 时间区或字符集不一致导致 ShardingSphere 解析错误需检查jdbc-url中serverTimezoneAsia/Shanghai是否生效。3.4 验证跨库 JOIN 是否被拦截ShardingSphere 默认禁止跨库 JOIN。尝试请求/api/order/list-by-product内部执行SELECT o.* FROM order_info o JOIN product_info p ON o.product_id p.idcurl http://localhost:8080/api/order/list-by-product?productIdP1001预期返回 HTTP 500body 为{code:500,message:Cannot support Multiple-Table for SELECT with sharding table.}这证明分片规则已生效。如需关联查询必须改用应用层 JOIN先查product_info再用IN (id1,id2,...)查order_info或引入Broadcast Table如dict_type表。4. 避坑指南那些让团队加班到凌晨的分库分表典型翻车现场分库分表不是加几个配置就能高枕无忧。我在三个项目中踩过的坑全浓缩在这五条血泪经验里。每一条都附带现象 → 原因 → 解决照着查省下至少 6 小时排查时间。4.1 现象分片后 COUNT(*) 查询结果比实际少一半原因ShardingSphere 默认将COUNT(*)下推到每个物理库执行再汇总结果。但如果某库中order_info_XX表为空该库返回COUNT0汇总时仍计入总数。但更隐蔽的问题是MyBatis-Plus 的Page插件与 ShardingSphere 的分页插件冲突导致COUNTSQL 被重写为SELECT COUNT(1) FROM (SELECT * FROM order_info LIMIT 10)而 ShardingSphere 无法解析子查询中的分片表直接路由到默认库。解决禁用 MyBatis-Plus 分页插件在ShardingConfiguration.java中显式注册ShardingSpherePaginationInterceptor并在 Mapper 方法上用Select(SELECT COUNT(*) FROM order_info WHERE user_id #{userId})手写 COUNT。4.2 现象SELECT * FROM order_info WHERE user_id IN (1,2,3,1000000)查询超时原因IN列表过长 1000 项时ShardingSphere 会为每个user_id计算分库分表位置生成 N 条物理 SQL 并行执行。若IN中包含跨 8 个库的 ID则触发 8×16128 次数据库连接连接池耗尽。解决业务层拆分IN列表每 100 个 ID 一组循环调用或改用SELECT /* sharding_hint */ * FROM order_info Hint 强制走单库需配合HintManager。4.3 现象UPDATE order_info SET status SHIPPED WHERE user_id 123 AND id 1001报错 “Can not find owner data source”原因id是主键但未设为分片键。ShardingSphere 要求UPDATE/DELETE的WHERE条件必须完全覆盖分片键否则无法定位到具体库表。此处user_id 123可定位库但id 1001无法定位表因分表键是user_id非id。解决要么将id改为snowflake算法生成高位含user_id信息要么在UPDATE语句中补全user_id条件即使你知道它是什么或改用ShardingKeyHolder在事务中透传分片值。4.4 现象应用启动时报Cannot determine embedded database driver class for database type NONE原因dynamic-datasource-spring-boot-starter与shardingsphere-jdbc-core-spring-boot-starter都试图自动配置DataSource发生 Bean 冲突。Spring Boot 3.x 的条件化配置更严格ConditionalOnMissingBean(DataSource.class)被两个 starter 同时触发。解决在application.yml中显式关闭动态数据源的自动配置spring: autoconfigure: exclude: com.baomidou.dynamic.datasource.spring.boot.autoconfigure.DynamicDataSourceAutoConfigure然后在ShardingConfiguration.java中用Primary标记ShardingSphereDataSourceBean。4.5 现象ORDER BY create_time DESC LIMIT 10返回结果乱序原因ShardingSphere 对LIMIT查询采用“归并排序”先从每个物理表取LIMIT 10再内存排序。若各表数据时间分布不均如order_info_00有最新 10 条order_info_01全是旧数据归并后前 10 名可能漏掉真正的最新记录。解决改用SELECT * FROM order_info WHERE user_id IN (/* 批量分片键 */) 应用层排序或启用props: query-with-cipher-column: false关闭加密列干扰终极方案是加create_time为分片辅助键需自定义复合分片算法。5. 二次开发实战如何把这套分库分表骨架安全接入你现有的 Spring Boot 项目现在你已经跑通了 Demo下一步是把它“缝”进你正在维护的电商系统。这不是简单复制粘贴而是要处理三类真实冲突已有数据源冲突、MyBatis-Plus 版本差异、分布式事务缺失。下面是我在线上项目落地时验证过的四步法。5.1 步骤一隔离数据源避免污染主数据源你的老项目大概率已有一个Primary DataSource比如masterDataSource。直接引入shardingsphere-jdbc会导致它被覆盖。正确做法是保留原数据源仅对特定 Mapper 接口启用分片。修改OrderInfoMapper.javaMapper DS(sharding) // ← 关键指定使用 dynamic-datasource 的 sharding 数据源组 public interface OrderInfoMapper extends BaseMapperOrderInfoEntity { }并在application.yml中声明数据源组spring: datasource: dynamic: primary: master # 主数据源仍是原来的 datasource: master: # 原有配置 sharding: # 分片专用数据源复用 shardingsphere-jdbc 的配置 driver-class-name: com.zaxxer.hikari.HikariDataSource hikari: >Configuration public class ShardingDataSourceConfig { Bean(shardingDataSource) ConfigurationProperties(spring.shardingsphere.datasource) public DataSource shardingDataSource() { return ShardingSphereDataSourceFactory.createDataSource( createDataSourceMap(), Collections.singletonList(createShardingRuleConfiguration()), new Properties() ); } private MapString, DataSource createDataSourceMap() { // 从 application.yml 读取 ds-0 ~ ds-7 的 HikariCP 配置创建 8 个 DataSource MapString, DataSource result new HashMap(); for (int i 0; i 8; i) { HikariDataSource ds new HikariDataSource(); ds.setJdbcUrl(jdbc:mysql://.../order_db_ String.format(%02d, i)); ds.setUsername(root); ds.setPassword(123456); result.put(ds- String.format(%02d, i), ds); } return result; } }这样彻底绕过 starter 的自动配置MP 版本不受影响。5.3 步骤三补全分布式事务Seata ShardingSphere分库后下单order_db 扣库存inventory_db需跨库事务。本项目默认不集成但预留了 Seata 接口。只需三步在pom.xml加入dependency groupIdio.seata/groupId artifactIdseata-spring-boot-starter/artifactId version1.7.0/version /dependencyapplication.yml中配置 Seataseata: tx-service-group: my_test_tx_group service: vgroup-mapping: my_test_tx_group: default grouplist: default: 127.0.0.1:8091在 Service 方法上加GlobalTransactionalGlobalTransactional public void createOrderAndDeductStock(OrderDTO dto) { orderInfoMapper.insert(dto.toOrderEntity()); // 走分片数据源 inventoryMapper.deduct(dto.getProductId(), dto.getCount()); // 走普通数据源 }注意Seata AT 模式要求所有参与库都有undo_log表且 ShardingSphere 的actual-data-nodes必须与 Seata 的dataSourceProxy代理对象对齐。建议先用 Seata 的ATMode测试单库事务再扩展到分片库。5.4 步骤四上线前必做的三件事清单检查项操作方式不做的后果分片键覆盖率审计运行SELECT table_name, column_name FROM information_schema.COLUMNS WHERE table_schema order_db_00 AND column_name user_id;确认所有order_info_XX表都有user_id字段缺失字段导致INSERT报Unknown column线上写入失败慢 SQL 归因开启sql-show: truespring.shardingsphere.props.sql-simple: true收集 1 小时日志用grep Actual SQL统计各库表执行频次某库表访问量是其他表 10 倍说明分片算法倾斜需调整哈希模数回滚预案验证手动删除order_db_00.order_info_00表触发CREATE TABLE自动重建确认mybatis-plus的auto-table机制生效上线后某库建表失败导致整个分片路由中断从那以后我每次给分库分表项目做上线评审都强制走一遍这三件事清单——哪怕多花 2 小时也比半夜被报警电话叫醒强。希望帮到你。本文还有配套的精品资源点击获取