SQL ShardingSphere-Proxy 的 SQL 解析引擎与 Hint 强制路由使用规范

shardingsphere-proxy 的 hint 在 sql 解析失败时不会生效，因路由前必须完成解析；表名大小写需严格匹配；批量 insert 中 hint 仅作用于首行；默认关闭需显式启用 sql-comment-parse-enabled。

ShardingSphere-Proxy 的 SQL 解析失败时 Hint 不生效

SQL 解析失败，/*+ SHARDING_HINT_TABLE=xxx */ 这类 Hint 就不会被识别——因为 ShardingSphere-Proxy 在路由前必须先完成 SQL 解析，解析失败直接走默认逻辑或报错，Hint 根本没机会执行。

常见错误现象：java.lang.UnsupportedOperationException: Cannot support DML operation with multiple tables 或 UnsupportedSQLException，尤其出现在含子查询、CTE（WITH）、窗口函数或非标准别名的语句中。

• 优先确认 SQL 是否能被 ShardingSphere 自带的 SQL 解析器支持：用 select 1、INSERT INTO t VALUES (?) 等简单语句测试，再逐步加复杂度
• ShardingSphere-5.3.2+ 默认使用 SQL92 解析器，对 mysql/postgresql 扩展语法兼容有限；若业务重度依赖 MySQL 特性（如 INSERT ... ON DUPLICATE KEY UPDATE），需显式配置 sql-show: true 并观察日志里的 Actual SQL 是否出现，没出现就说明卡在解析阶段
• 绕过解析限制的临时办法：把复杂逻辑拆到应用层，Proxy 层只做单表路由；或改用 sharding_hint + set sharding_hint_table = 'xxx' 的会话变量方式（但仅对 DML 有效，且需客户端保持连接）

Hint 强制路由到指定分片时表名大小写不匹配

MySQL 默认忽略表名大小写，但 ShardingSphere-Proxy 的 Hint 路由是严格字符串匹配——/*+ SHARDING_HINT_TABLE=user_info */ 和实际逻辑表名 USER_INFO 或 User_Info 不一致，就会路由失败，查不到数据或写入错误分片。

使用场景：多环境（开发/测试/生产）间逻辑表命名风格不统一，或 dba 建表时用了大写，而应用代码里写的是小写。

• 检查 schema.yaml 中 tables 下定义的逻辑表名，确保与 Hint 中写的完全一致（包括下划线、大小写）
• MySQL 配置项 lower_case_table_names=1 不影响 Proxy 的 Hint 匹配逻辑——Proxy 不读这个参数，它只认你配置里写的和 Hint 里写的是否字面相等
• 如果无法统一命名，可在 props: 下开启 sql-comment-parse-enabled: true（5.3.0+），并改用更健壮的注释格式：/* ShardingSphere hint: sharding_hint_table=user_info */（注意无加号、空格敏感）

Hint 在批量 INSERT 或 REPLACE 场景下只作用于第一条记录

ShardingSphere 对批量语句（INSERT INTO t VALUES (1),(2),(3)）的 Hint 处理有局限：它只提取第一条记录对应的分片值，后续记录沿用相同路由结果，不重新计算——这在分片键值不同时会导致数据错乱。

性能影响明显：看似用了 Hint 强制路由，实际部分数据进了错误分片，查不出来，还难以排查。

• 批量插入必须保证所有行的分片键值相同，否则不要依赖 Hint；应改用单条 INSERT + 多次执行，或改用 sharding_hint 会话变量（SET sharding_hint_database = 'ds_1'; SET sharding_hint_table = 't_order_0'）
• REPLACE INTO 本质是 delete + INSERT，ShardingSphere 会尝试解析为两条语句，Hint 只绑定在 INSERT 段，DELETE 可能路由到别的分片，造成数据残留
• 5.4.0 开始支持 sharding_hint 的事务级作用域，建议在事务开头 SET，结尾 RESET，比注释 Hint 更可靠

ShardingSphere-Proxy 启动后 Hint 不生效却无报错

最常被忽略的一点：Hint 功能默认关闭。即使配置了 props:，没显式启用 sql-comment-parse-enabled，所有 /*+ ... */ 注释都会被原样透传给后端数据库，Proxy 完全无视。

验证方法：开 sql-show: true，执行带 Hint 的语句，看日志里有没有 Actual SQL 行——没有就说明解析/路由根本没触发。

• 必须在 conf/server.yaml 的 props: 下添加：sql-comment-parse-enabled: true（5.3.0+）或 sql-show: true（用于调试，非必需）
• 旧版本（5.2.x）用的是 sql-comment-parse-enabled，5.3.x+ 改为 sql-comment-parse-enabled，拼写差一个字母就会静默失效
• 修改配置后必须重启 Proxy，热加载不生效；且要确认 schema.yaml 中对应逻辑库启用了 sharding 规则，纯 replica-query 库不处理任何 Hint

Hint 的边界很清晰：它不是万能路由开关，而是解析成功后的“最后一公里”控制。一旦 SQL 结构超出解析器能力，或配置漏了一处小开关，它就彻底隐身——这种失效没有报错，只有数据不对，查起来最费时间。