如何在Java中搭建ShardingSphere分库分表环境_数据库进阶

shardingsphere 5.x起包路径变为org.apache.shardingsphere，需替换旧依赖、更新配置前缀、严格匹配分片键名，并确保数据源bean提前注册。

ShardingSphere-JDBC 启动就报 NoClassDefFoundError: io/shardingsphere/core/rule/ShardingRule

这是老版本 API 被彻底移除的典型表现。ShardingSphere 5.x 起已拆分为 shardingsphere-jdbc-core-spring-boot-starter，不再兼容 4.x 的包路径和类结构。

• 确认 Maven 引入的是 org.apache.shardingsphere 域名下的依赖，不是旧的 io.shardingsphere
• Spring Boot 2.7+ 用户必须用 ShardingSphere 5.3.2+，否则 spring.factories 加载失败
• 删掉所有 sharding-jdbc-spring-boot-starter 或 sharding-jdbc-core 这类 4.x 名称的依赖，它们和新版本类路径冲突
• 配置项前缀从 spring.shardingsphere. 变为 spring.shardingsphere.props.（如 sql-show）和 spring.shardingsphere.rules.（如分片规则）

分片键（sharding-column）设成 user_id，但 SQL 里用 WHERE id = ? 就路由不到正确库表

ShardingSphere 不会自动推导逻辑列和物理列的映射关系。它只认你明确定义的分片键字段名，且大小写、别名、函数包裹都会导致路由失效。

• SQL 中必须直接使用配置的分片列名，比如配置了 sharding-column: user_id，就不能写 WHERE u.user_id = ?（带表别名）或 WHERE UPPER(user_id) = ?（函数包裹）
• 如果业务用的是 id 字段，但分片规则写的是 user_id，那整个路由就失效，默认走默认库表
• 启用 props.sql-show=true 后观察日志里打印的 Actual SQL，能快速验证是否命中了分片逻辑
• 复合分片（ComplexKeysShardingAlgorithm）需自行实现 doSharding()，不能靠配置自动生成

用了 StandardShardingAlgorithm，但 INSERT 插入后查不到数据

常见于未配置绑定表（binding-tables）或广播表（broadcast-tables），导致主表分片后，关联查询时从表没同步路由，跨库 JOIN 失败。

AI角色脑洞生成器

一键打造完整角色设定，轻松创造专属小说漫画游戏角色背景故事

下载

• 若 t_order 和 t_order_item 是一对多关系，且都按 order_id 分片，必须在配置里声明 binding-tables: t_order,t_order_item，否则 JOIN 时 t_order_item 会按默认策略查全库
• 字典表（如 sys_config）必须设为 broadcast-tables，否则每个库都缺数据，JOIN 结果为空
• StandardShardingAlgorithm 的 sharding-jdbc 实现只支持 = 和 IN，BETWEEN 或 LIKE 会全库扫——这不是 bug，是设计限制
• 自定义算法返回的库/表名，必须和 actual-data-nodes 中声明的格式完全一致（比如 ds_0.t_order_0 不能写成 ds0.t_order0）

Spring Boot 配置里写了 actual-data-nodes: ds_0.t_order_${0..1}，启动时报 Invalid data node configuration

这个错误基本锁定在占位符语法或数据源未就绪。ShardingSphere 在启动早期就解析 actual-data-nodes，此时 Spring 上下文里的 DataSource bean 还没完成初始化。

立即学习“Java免费学习笔记（深入）”；

• ${0..1} 是合法的，但必须确保 ds_0 和 ds_1 已作为标准 HikariDataSource bean 注册到 Spring 容器；用 @ConfigurationProperties("spring.datasource.ds-0") 方式声明更稳妥
• 避免在 actual-data-nodes 里用 SpEL 表达式（如 ${system.env}），ShardingSphere 不解析 Spring EL
• 检查 YAML 缩进：actual-data-nodes 必须和 tables.t_order 同级，缩进错一位就会被忽略
• 如果用了多数据源动态注册（比如通过 AbstractRoutingDataSource），ShardingSphere 无法识别，必须改用原生 DataSource Bean 注入