ShardingSphere-JDBC 5.2整合Spring Boot时，分片规则不生效怎么办？

Question

**问题描述（198字）：** 在Spring Boot 2.7+项目中整合ShardingSphere-JDBC 5.2时，配置了标准分片策略（如`StandardShardingStrategy`），SQL执行后数据仍写入默认数据源、未按分片键路由，且`sql-show: true`日志中无分片重写痕迹。常见原因包括：① `shardingsphere.jdbc.props.sql-show=true` 未启用，导致无法观察分片行为；② 分片规则中`actual-data-nodes`格式错误（如误写为`ds.t_order_${0..1}`但实际表名是`t_order_0`/`t_order_1`，缺少下划线）；③ 分片键字段名与SQL中使用的列名不一致（如实体用`order_id`，但分片配置写成`orderId`）；④ Spring Boot自动配置冲突——未排除`DataSourceAutoConfiguration`，导致ShardingSphere的`ShardingSphereDataSource`被绕过；⑤ 使用了JPA/Hibernate，但未配置`spring.jpa.properties.hibernate.physical_naming_strategy=org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy`以兼容下划线命名。需逐项校验配置有效性与上下文一致性。

Answer 1

```html

一、现象确认与日志可观测性验证

首要动作是确认分片行为是否被ShardingSphere-JDBC实际捕获。启用SQL显示日志是诊断起点：shardingsphere.jdbc.props.sql-show=true（注意：YAML中需写为shardingsphere: jdbc: props: sql-show: true），且必须配合logging.level.org.apache.shardingsphere=DEBUG。若日志中完全缺失Actual SQL或Logic SQL输出，说明ShardingSphere未介入SQL执行链路——此时问题已不在分片逻辑本身，而在容器注入层面。

二、数据源装配完整性校验

Spring Boot 2.7+默认启用DataSourceAutoConfiguration，会优先加载HikariDataSource并注册为@Primary Bean，导致ShardingSphereDataSource被忽略。必须显式排除：

@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    JdbcTemplateAutoConfiguration.class
})

同时检查@Bean定义顺序：若手动声明DataSource Bean但未标注@Primary，而ShardingSphere的ShardingSphereDataSource未被Spring上下文识别为唯一数据源，则JPA/Hibernate仍会回退至原始数据源。

三、分片规则语法与命名一致性精查

以下为常见actual-data-nodes配置错误对照表：

配置项	正确示例	典型错误	后果
actual-data-nodes	ds.t_order_${0..1}	ds.torder_${0..1}（缺下划线）	路由时无法匹配物理表，降级至默认数据源
sharding-column	order_id	orderId（驼峰 vs 下划线）	分片键提取失败，ShardingCondition为空

四、ORM层适配深度解析

当使用JPA/Hibernate时，实体字段@Column(name = "order_id")与SQL生成强耦合。若未配置物理命名策略，Hibernate默认将orderId转为order_id，但ShardingSphere分片配置若写成sharding-column: orderId，则在SimpleRoutingEngine中无法从Parsed SQL AST中提取该列——因AST中列名为order_id。必须同步配置：

spring.jpa.properties.hibernate.physical_naming_strategy=\
  org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy

此策略确保Hibernate生成的SQL列名与数据库真实列名一致，使ShardingSphere能准确识别分片键。

五、运行时诊断流程图

graph TD
    A[SQL发出] --> B{ShardingSphereDataSource是否被注入？}
    B -- 否 --> C[检查@SpringBootApplication exclude]
    B -- 是 --> D{sql-show=true & DEBUG日志开启？}
    D -- 否 --> E[补全日志配置]
    D -- 是 --> F[解析Logic SQL中的sharding-column]
    F -- 列名不匹配 --> G[校验实体@Column与yml中sharding-column]
    F -- 匹配成功 --> H[检查actual-data-nodes模板语法]
    H -- 模板渲染失败 --> I[验证ds.t_order_0是否存在]
    H -- 渲染成功 --> J[路由完成，执行Actual SQL]

六、关键配置项交叉验证清单

• ✅ shardingsphere.jdbc.datasource.ds.type=com.zaxxer.hikari.HikariDataSource —— 数据源类型不可省略
• ✅ shardingsphere.jdbc.rules[0].tables.t_order.actual-data-nodes=ds.t_order_${0..1} —— 表名与数据库物理表严格一致
• ✅ shardingsphere.jdbc.rules[0].tables.t_order.table-strategy.standard.sharding-column=order_id —— 必须与INSERT INTO t_order(order_id, ...)中列名完全相同
• ✅ shardingsphere.jdbc.rules[0].tables.t_order.table-strategy.standard.sharding-algorithm-name=t-order-inline —— 算法名需在algorithms块中正确定义
• ✅ spring.shardingsphere.props.check-table-metadata-enabled=false —— 生产环境建议关闭元数据校验，避免启动失败

七、高级调试技巧：断点溯源法

在IDE中对以下核心类设置条件断点可快速定位失效环节：

• org.apache.shardingsphere.infra.route.engine.impl.StandardRoutingEngine#route：观察shardingConditions是否为空
• org.apache.shardingsphere.sharding.route.engine.condition.generator.ShardingConditionEngine#generate：检查column是否被正确解析为ColumnSegment
• org.apache.shardingsphere.infra.metadata.schema.builder.TableMetaDataBuilder#load：确认逻辑表元数据是否加载成功

若断点从未触发，说明ShardingSphere拦截器链未生效——90%概率为数据源Bean未被正确代理或AOP失效。

```