shardingsphere影子库通过流量染色实现sql路由分流，核心在于染色注入、识别与路由；需业务显式注入标识至shadowhintmanager，配置columnregexmatchshadowalgorithm匹配影子字段，并启用可观测比对闭环。
ShardingSphere 的影子库（Shadow Database）机制，本质是通过流量染色实现 SQL 路由分流，让特定请求不触达真实生产库，而是路由到影子库执行，从而支撑灰度验证、SQL 兼容性测试、新旧逻辑并行比对等场景。关键不在“建库”，而在“染色怎么打、怎么识别、怎么路由”。
流量染色：从入口到 SQL 的链路标识
ShardingSphere 本身不主动产生染色信息，需业务系统在请求发起时显式注入上下文标识（如 HTTP Header、RPC attachment、ThreadLocal）。常见做法：
- Web 层统一拦截器读取 X-Shadow-Flag: true 或 X-Env: shadow 等自定义 Header，并将该标记写入 ShardingSphere 提供的 ShadowHintManager
- 微服务间调用时，通过 Dubbo Filter 或 Spring Cloud Sleuth 的 MDC 透传染色键值，下游服务解析后同样调用 ShadowHintManager.setShadow(true)
- 避免依赖 Cookie 或 Session，因影子库测试常需压测工具直连或离线脚本触发，应支持无状态、可编程方式注入
影子规则配置：精准匹配 + 安全兜底
在 shadow-rule.yaml 中需明确三要素：影子表映射、影子数据源、以及最关键的 影子算法。推荐使用 ColumnRegexMatchShadowAlgorithm：
- 指定一个业务无关的字段（如 shadow_flag 列）作为染色载体，该列在真实表中存在但默认为 NULL 或 0，在影子表中可忽略或设为固定值
- 算法配置正则表达式匹配该字段值（如 ^true$），匹配成功即路由至影子库；不匹配走真实库
- 务必配置 allow-hint-disable: false，防止未染色流量误入影子库；同时开启 shadow-db-enabled: true 启用全局影子功能
灰度验证闭环：不只是“能跑”，还要“可信”
影子库不是摆设，需构建可观测、可比对、可回滚的验证闭环：
- SQL 执行日志中启用 shadow-sql-log-enabled: true，区分真实/影子 SQL 输出，便于排查路由是否符合预期
- 影子库与生产库结构必须严格一致（含索引、字符集、时区），建议通过 pt-table-checksum 或自研 DDL 同步工具保障
- 灰度期间同步采集两库的执行耗时、影响行数、异常堆栈，用轻量比对服务（如基于 Prometheus + Grafana）监控偏差率，超阈值自动告警
避坑提醒：几个高频失效点
影子库常在上线前夜“突然不生效”，多因以下细节疏漏：
- ShadowHintManager 是 ThreadLocal 实现，异步线程（如 CompletableFuture、@Async）中会丢失上下文，必须手动传递或使用 ShadowHintManager.clone()
- MyBatis 的 @SelectProvider 或动态 SQL 若拼接了 WHERE 条件，可能覆盖影子字段判断逻辑，建议影子字段始终放在 SQL 最外层 AND 条件中
- ShardingSphere-JDBC 与 Proxy 对影子规则加载时机不同：JDBC 在启动时加载，Proxy 需通过 DistSQL 动态生效，切勿混用配置方式
