Sharding-JDBC数值范围分表实战工程：支持ID/时间戳自动路由到t_user_0、t_user

本文还有配套的精品资源，点击获取

简介：直接可运行的Java工程，基于Sharding-JDBC实现按数值区间自动分表，比如user_id在1-1000000写入t_user_0，1000001-2000000写入t_user_1，支持时间戳字段如create_time按天或月分片。项目结构清晰：pom.xml已集成sharding-jdbc-spring-boot-starter依赖；src/main/java下包含分片策略配置类（PreciseShardingAlgorithm、RangeShardingAlgorithm实现）、Spring Data JPA或JdbcTemplate访问示例；sql.txt提供各分片表建表语句及主键范围说明；说明.txt详细列出分片键选择逻辑、SQL路由过程、INSERT/SELECT/BETWEEN查询在不同范围下的实际落表行为、以及常见测试验证点（如跨范围查询是否广播、边界值插入是否准确）。整个方案不依赖数据库中间件，纯Java客户端完成分片解析与路由，兼容MyBatis、JPA、原生JDBC等主流数据访问方式，适合快速上手范围分片原理，也可作为生产环境分表策略的技术原型参考。

1. 项目概述：为什么数值范围分表不是“备选方案”，而是高频场景下的务实选择

在真实业务系统里，我见过太多团队把分库分表当成“高大上”的技术升级，结果一上来就堆ShardingSphere-Proxy、搞复杂的一致性哈希、甚至提前规划256个库32张表——最后发现90%的查询压根不跨分片，80%的数据增长集中在最近7天，而运维同学每天盯着慢SQL报警，却连一张t_order_20240515表里到底有没有脏数据都查不清。这根本不是分片的问题，是分片策略和业务节奏没对齐。

这个工程要解决的，恰恰是最朴素也最常被低估的场景：数据天然具备强顺序性与可预测增长性。比如用户注册ID从1开始递增、订单号按时间戳生成、日志记录带毫秒级create_time字段。这类数据不像UUID那样随机散列，也不像地理区域那样需要人工打标，它本身就带着“刻度”——而数值范围分表，就是把数据库的物理存储，直接对齐到这个天然刻度上。

你可能马上想到一个问题：范围分片会不会导致热点？比如所有新用户都往最新一张表写？答案是：会，但可控。关键在于你是否理解“范围”的粒度怎么定。不是所有ID都适合按100万切一刀；也不是所有时间戳都该按天分表。真正的实战经验是：范围粒度必须和业务写入吞吐、单表容量上限、归档策略三者联动设计。比如我们线上一个千万级用户系统，user_id按50万一段切分，不是拍脑袋，而是基于MySQL单表500万行时B+树深度稳定在3层、主键索引页分裂频率低于每小时1次、以及DBA允许单表最大8GB（约600万行）这三个硬指标反推出来的。

这个工程之所以叫“开箱即用”，是因为它跳过了所有概念包装，直接给你一个能mvn clean install && java -jar target/*.jar跑起来的最小闭环。它不教你Sharding-JDBC的SPI扩展机制，也不讲Spring Boot自动装配原理，而是聚焦在一个动作上：当你执行INSERT INTO t_user (id, name) VALUES (1500005, '张三')时，控制台立刻打印出[Routing to table: t_user_1]，并且你能在对应数据库里看到这条记录真真切切躺在t_user_1里。这种“所见即所得”的反馈，比读十页官方文档更能建立对分片路由的信任感。它适合两类人：刚接触分片的新手，需要亲手验证“路由到底发生了什么”；以及正在做技术选型的架构师，想快速验证范围分片在自己业务模型下的实际行为边界——比如BETWEEN查询会不会广播？ORDER BY LIMIT会不会跨表排序？边界值插入会不会错表？这些都不是理论问题，是上线前必须实测的生死线。

2. 整体设计思路拆解：为什么不用一致性哈希，而坚持数值范围？

2.1 路由决策树：从SQL解析到分片表名的完整路径

很多人以为Sharding-JDBC的分片是“黑盒魔法”，其实它的核心就是一个确定性的函数映射。整个路由过程可以拆成四步，每一步都可验证、可调试、可替换：

SQL解析层：Sharding-JDBC使用SQLParseEngine将原始SQL字符串解析成抽象语法树（AST）。重点不是语法正确性，而是精准识别出分片键（sharding column）的值来源。比如INSERT INTO t_user (id, name) VALUES (?, ?)中，第一个?绑定的参数值会被标记为id字段的候选值；而SELECT * FROM t_user WHERE id BETWEEN 1000001 AND 2000000中，BETWEEN子句的左右边界值会被提取出来。这一步决定了后续路由的输入是否完整。
分片键提取层：框架根据配置的sharding-column: id，从AST中定位所有涉及该字段的操作节点。这里有个关键细节：Sharding-JDBC默认只支持单分片键路由。如果你的WHERE条件同时有id = ? AND create_time > ?，且两个字段都配置了分片规则，框架会抛出UnsupportedOperationException。这不是缺陷，而是设计取舍——多键路由必然引入笛卡尔积式分片组合，爆炸性增加查询复杂度。所以工程里只配id或只配create_time，是刻意为之的约束。
算法执行层：这是范围分片的核心。当提取到分片键值1500005后，框架调用你实现的RangeShardingAlgorithm.doSharding()方法。注意，这里传入的不是单个值，而是一个Collection<String> availableTargetNames（比如["t_user_0", "t_user_1", "t_user_2"]）和一个Range<Comparable>对象（封装了1000001到2000000的区间）。你的算法要返回所有可能命中这个区间的表名集合。如果是精确查询id = 1500005，则返回单元素集合["t_user_1"]；如果是范围查询id BETWEEN 1000001 AND 2000000，则返回["t_user_1"]；但如果是id BETWEEN 500000 AND 1500000，就必须返回["t_user_0", "t_user_1"]——这就是广播查询的根源。
SQL重写层：拿到目标表名列表后，框架不再操作原SQL，而是生成新的SQL语句。比如原SQL是SELECT * FROM t_user WHERE id = 1500005，重写后变成SELECT * FROM t_user_1 WHERE id = 1500005；而SELECT * FROM t_user WHERE id BETWEEN 500000 AND 1500000会被重写为两条：SELECT * FROM t_user_0 WHERE id BETWEEN 500000 AND 1000000 和 SELECT * FROM t_user_1 WHERE id BETWEEN 1000001 AND 1500000，然后合并结果集。这个过程完全透明，应用层无感知。

提示：你可以通过设置props.sql-show: true开启SQL打印，亲眼看到每条语句被重写成什么样子。这是调试分片逻辑最直接的手段，比断点调试AST更高效。

2.2 为什么放弃一致性哈希？三个无法绕过的现实约束

一致性哈希（Consistent Hashing）在分布式缓存领域很成熟，但搬到数据库分片上，会撞上三个硬伤：

范围查询失效：业务中最常见的SELECT * FROM t_order WHERE user_id IN (1001, 1002, 1003)或WHERE create_time >= '2024-05-01'，在一致性哈希下必然变成全表扫描。因为哈希值是离散的，无法从哈希空间反推原始数值区间。而我们的工程里，BETWEEN查询能精准路由到两张表，IN列表只要不超过阈值（默认1000个）也能走精确路由，这是范围分片的先天优势。
扩容成本不可控：一致性哈希扩容时，只需迁移少量数据（环上相邻节点间的数据）。但数据库扩容不是搬数据那么简单——你要考虑主从同步延迟、备份窗口、应用连接池刷新、监控告警规则更新。而范围分片扩容，本质是“加表”。比如原来只有t_user_0到t_user_9（覆盖ID 1-1000万），现在要支持到2000万，你只需要新建t_user_10到t_user_19，并修改分片算法中maxId的上限值。旧数据不动，新数据自动流入新表，零迁移、零停机、零风险。我们线上一个支付系统，就是靠这种“加表”模式，从10张表平滑扩到50张表，全程业务无感。
运维心智负担低：DBA看监控，最关心的是“哪张表快满了”。范围分片下，t_user_5的行数达到50万，他立刻知道该关注id在4000001-5000000区间的业务流量是否异常；而一致性哈希下，他得先查哈希环分布，再算出哪些虚拟节点负载高，最后关联到物理表——中间多了一层抽象，排查效率直接打五折。

所以这个工程坚持数值范围，不是技术保守，而是对业务现实的妥协与尊重。它承认：大多数业务的数据增长是线性的，大多数查询是带范围条件的，大多数运维同学更习惯看数字而不是哈希值。

3. 核心细节解析与实操要点：从配置到算法的每一处魔鬼细节

3.1 分片键选择：为什么`id`比`create_time`更适合作为第一分片键？

工程里提供了两种分片键的配置示例，但它们的适用场景截然不同。我们先看id：

spring:
  shardingsphere:
    rules:
      - !SHARDING
        tables:
          t_user:
            actual-data-nodes: ds_0.t_user_${0..9}
            table-strategy:
              standard:
                sharding-column: id
                precise-algorithm-class-name: com.example.sharding.PreciseIdShardingAlgorithm
                range-algorithm-class-name: com.example.sharding.RangeIdShardingAlgorithm

这里的precise-algorithm-class-name处理=、IN等精确匹配，range-algorithm-class-name处理BETWEEN、>=等范围查询。关键在于actual-data-nodes: ds_0.t_user_${0..9}——它声明了物理表名模板，${0..9}表示生成t_user_0到t_user_9共10张表。

而create_time的配置通常是这样的：

# 时间戳分片（按天）
sharding-column: create_time
precise-algorithm-class-name: com.example.sharding.PreciseTimeShardingAlgorithm
range-algorithm-class-name: com.example.sharding.RangeTimeShardingAlgorithm

但注意：actual-data-nodes不能写成ds_0.t_user_${20240501..20240531}！Sharding-JDBC不支持日期范围的动态生成。你必须预先创建好所有可能的表，比如t_user_20240501、t_user_20240502……直到年底。这意味着时间分片更适合“冷热分离”场景：最近7天的表放在SSD盘，历史表归档到HDD，而create_time只是辅助分片键，主分片键仍是id。

实操心得：我在一个日志系统里踩过坑。当时用create_time作为唯一分片键，按月分表（t_log_202405, t_log_202406…）。结果某天凌晨批量导入3个月前的补丁数据，所有SQL都路由到t_log_202405——因为算法里写了SimpleDateFormat("yyyyMM").format(value)，而补丁数据的时间戳被错误解析为当前月。后来改成id % 100为主分片，create_time为二级分片（用于归档判断），问题彻底解决。记住：主分片键必须是业务强相关、不可变、且写入频率稳定的字段。id天然满足，create_time则容易受时区、批量导入、数据修复等干扰。

3.2 精确分片算法（PreciseShardingAlgorithm）：边界值的数学陷阱

这是最容易出错的地方。看工程里的PreciseIdShardingAlgorithm实现：

public final class PreciseIdShardingAlgorithm implements PreciseShardingAlgorithm<Long> {
    private static final long RANGE_SIZE = 1_000_000L;

    @Override
    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<Long> shardingValue) {
        Long id = shardingValue.getValue();
        // 关键：这里用的是向下取整除法，不是四舍五入！
        int tableIndex = (int) (id / RANGE_SIZE);
        // 但注意：id=1000000时，1000000/1000000=1，应该进t_user_1，但t_user_1对应索引1，没错
        // 可id=0呢？0/1000000=0，进t_user_0，合理
        return "t_user_" + tableIndex;
    }
}

表面看没问题，但仔细想：如果RANGE_SIZE = 1000000，那么：
- id从0到999999 → tableIndex = 0 → t_user_0
- id从1000000到1999999 → tableIndex = 1 → t_user_1

这符合需求。但问题来了：数据库主键通常从1开始，不是0。如果业务约定id最小值是1，那么t_user_0永远空着，浪费一个分片。更糟的是，如果某条记录id=0（比如测试数据或遗留系统兼容），它会被路由到t_user_0，而这张表可能根本没建。

解决方案有两个：
1. 调整算法偏移量：int tableIndex = (int) ((id - 1) / RANGE_SIZE); 这样id=1→0，id=1000000→999999→0，id=1000001→1000000→1。但id=1000000进了t_user_0，和需求“1-1000000进t_user_0”不符。
2. 修正需求定义：明确告诉产品和开发，“t_user_0”承载id在1到1000000（含）的数据，算法改为：
java int tableIndex = (int) ((id - 1) / RANGE_SIZE); // id=1→0, id=1000000→999999→0, id=1000001→1000000→1
这样既保证id=1到1000000都在t_user_0，又避免t_user_0空转。

注意事项：availableTargetNames参数不是摆设。它传入的是当前配置中所有可用的物理表名，比如["t_user_0", "t_user_1", "t_user_2"]。你的算法必须确保返回的表名一定在这个集合里，否则会抛ShardingSphereException。所以生产环境上线前，务必检查actual-data-nodes配置的表名范围，和数据库中真实存在的表名完全一致。我们曾因测试库少建了一张t_user_5，导致所有id在5000001-6000000的插入全部失败，错误日志里只有一句Cannot find available target for ...，排查了两小时才发现是表名拼写错误。

3.3 范围分片算法（RangeShardingAlgorithm）：BETWEEN查询的广播真相

这是理解分片行为的关键。看RangeIdShardingAlgorithm：

public final class RangeIdShardingAlgorithm implements RangeShardingAlgorithm<Long> {
    private static final long RANGE_SIZE = 1_000_000L;

    @Override
    public Collection<String> doSharding(Collection<String> availableTargetNames, RangeShardingValue<Long> shardingValue) {
        Range<Long> valueRange = shardingValue.getValueRange();
        long lower = valueRange.lowerEndpoint();
        long upper = valueRange.upperEndpoint();

        Set<String> result = new LinkedHashSet<>();
        // 遍历所有可能的表，检查其ID范围是否与查询区间有交集
        for (String tableName : availableTargetNames) {
            // 从表名解析出索引，比如"t_user_3" → index=3
            int tableIndex = Integer.parseInt(tableName.substring(tableName.lastIndexOf("_") + 1));
            long tableMinId = (long) tableIndex * RANGE_SIZE + 1; // 每张表起始ID
            long tableMaxId = tableMinId + RANGE_SIZE - 1; // 每张表结束ID

            // 检查查询区间 [lower, upper] 是否与表区间 [tableMinId, tableMaxId] 相交
            if (lower <= tableMaxId && upper >= tableMinId) {
                result.add(tableName);
            }
        }
        return result;
    }
}

这段代码揭示了一个事实：BETWEEN查询是否广播，取决于查询区间是否跨越多个分片的边界。比如：
- id BETWEEN 500000 AND 1500000：500000在t_user_0（1-1000000），1500000在t_user_1（1000001-2000000），所以返回["t_user_0", "t_user_1"]，广播查询。
- id BETWEEN 1000001 AND 1500000：全部落在t_user_1区间内，只返回["t_user_1"]，单表查询。

但这里有个隐藏陷阱：RangeShardingValue的lowerEndpoint()和upperEndpoint()返回的是闭区间端点，而数据库的BETWEEN a AND b也是闭区间。所以算法里的相交判断lower <= tableMaxId && upper >= tableMinId是严格数学正确的。

实操心得：我们线上一个报表系统，经常执行SELECT COUNT(*) FROM t_user WHERE id BETWEEN ? AND ?。当参数跨度超过200万时，查询会广播到2张以上表，性能暴跌。后来改成预计算：先用SELECT MAX(id) FROM t_user_0拿到各表最大ID，再根据查询参数动态构造UNION ALL语句，只查必要的表。性能提升10倍。这说明：范围分片不是银弹，它要求应用层对查询模式有清醒认知，并主动规避跨分片聚合。

4. 实操过程与核心环节实现：从零搭建一个可验证的范围分片工程

4.1 环境准备：为什么推荐H2内存数据库而非MySQL？

工程里sql.txt提供了MySQL建表语句，但实际运行时，我强烈建议先用H2。原因有三：

启动零依赖：H2是纯Java内存数据库，pom.xml里加一行依赖，application.yml里配个JDBC URL，mvn spring-boot:run就能跑。而MySQL需要安装服务、创建用户、授权、建库，新手光环境搭建就卡半天。
表结构验证直观：H2支持SHOW TABLES和SELECT * FROM INFORMATION_SCHEMA.TABLES，你能直接看到Sharding-JDBC创建的逻辑表t_user下，到底映射了哪些物理表。比如执行SELECT * FROM t_user后，H2控制台会显示它实际查询了t_user_0和t_user_1两张表，结果已合并——这种可视化反馈，比看日志更直接。
事务与隔离级别可控：H2的DB_CLOSE_DELAY=-1参数能让内存库在JVM退出前一直存活，方便你连续执行多条SQL观察状态；而MySQL的autocommit模式、binlog格式、InnoDB锁机制，会引入额外变量，干扰你对分片逻辑本身的验证。

当然，最终必须切到MySQL。工程里application-dev.yml和application-prod.yml做了环境隔离，切换只需改spring.profiles.active。但起步阶段，请相信我：用H2，能让你把注意力100%放在分片逻辑上，而不是数据库权限错误上。

4.2 pom.xml关键依赖解析：starter vs raw dependency的取舍

工程的pom.xml用了sharding-jdbc-spring-boot-starter，这是最简路径。但很多团队会纠结：该用starter，还是手动引入sharding-jdbc-core、sharding-jdbc-spring-namespace等原始包？

答案是：starter是唯一推荐选项，除非你有特殊定制需求。理由如下：

自动配置完备：starter内置了ShardingSphereAutoConfiguration，它会自动扫描@Bean定义的分片算法类、自动注册DataSource、自动注入ShardingSphereDataSource。你只需在application.yml里写配置，不用写任何Java配置类。
版本冲突免疫：starter的pom.xml里，sharding-jdbc-spring-boot-starter的版本和它依赖的sharding-jdbc-core、sharding-jdbc-transaction版本是严格锁定的。而如果你手动引入多个sharding-jdbc模块，很容易出现sharding-jdbc-core:4.1.1和sharding-jdbc-transaction:4.0.0的版本不匹配，导致NoSuchMethodError。
Spring生态无缝集成：starter支持@Transactional注解的传播，支持Spring Boot Actuator的健康检查端点（/actuator/shardingsphere），支持Spring Cloud Sleuth的链路追踪。这些能力，raw dependency需要你手动桥接。

所以工程里pom.xml的依赖是这样写的：

<dependency>
    <groupId>org.apache.shardingsphere</groupId>
    <artifactId>sharding-jdbc-spring-boot-starter</artifactId>
    <version>4.1.1</version>
</dependency>
<!-- 数据库驱动 -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>runtime</scope>
</dependency>

注意<scope>runtime</scope>：H2只在运行时需要，编译时不需要，避免污染构建产物。

4.3 sql.txt建表语句详解：为什么每张分片表都要有相同的索引？

sql.txt里，t_user_0、t_user_1等表的建表语句是这样的：

CREATE TABLE t_user_0 (
  id BIGINT NOT NULL PRIMARY KEY,
  name VARCHAR(50) NOT NULL,
  create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_create_time (create_time)
);

CREATE TABLE t_user_1 (
  id BIGINT NOT NULL PRIMARY KEY,
  name VARCHAR(50) NOT NULL,
  create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_create_time (create_time)
);
-- 其他表类似...

关键点在于：所有分片表的结构必须完全一致，包括主键、索引、字符集、排序规则。为什么？

SQL重写安全：Sharding-JDBC重写SQL时，假设所有物理表都有idx_create_time索引。如果t_user_0有这个索引，而t_user_1没有，那么SELECT * FROM t_user WHERE create_time > '2024-05-01'被重写为SELECT * FROM t_user_1 WHERE create_time > '2024-05-01'时，MySQL会走全表扫描，而t_user_0走索引，结果集合并后性能不可控。
数据一致性保障：主键约束必须存在。如果t_user_0有PRIMARY KEY(id)，而t_user_1忘了加，那么INSERT INTO t_user (id, name) VALUES (1500005, '张三')会被路由到t_user_1，但因为没有主键，id重复插入不会报错，导致数据污染。
运维工具兼容：DBA常用的pt-table-checksum、mysqldump等工具，都依赖表结构一致性。如果分片表结构不同，这些工具会报错或产生错误校验结果。

提示：工程里sql.txt还包含一条CREATE TABLE t_user (id BIGINT, name VARCHAR(50))的逻辑表语句。这是给IDE用的——IntelliJ IDEA的Database工具能识别它，提供SQL语法高亮和表结构提示。但它在数据库里并不存在，Sharding-JDBC也不会用它。所以别纠结“逻辑表要不要建”，它只是个占位符。

4.4 说明.txt的测试要点实战：如何设计一个能暴露所有分片漏洞的测试用例集？

说明.txt里列出了测试要点，但真正有价值的，是把它变成可执行的JUnit测试。工程里src/test/java下应该有类似这样的测试类：

@SpringBootTest
class ShardingRangeTest {

    @Autowired
    private JdbcTemplate jdbcTemplate;

    @Test
    void testPreciseInsertAndSelect() {
        // 插入id=500000，应进t_user_0
        jdbcTemplate.update("INSERT INTO t_user (id, name) VALUES (?, ?)", 500000L, "test0");
        // 查询，应只查t_user_0
        List<Map<String, Object>> result = jdbcTemplate.queryForList(
            "SELECT * FROM t_user WHERE id = ?", 500000L);
        assertEquals(1, result.size());
        assertEquals("test0", result.get(0).get("name"));
    }

    @Test
    void testRangeQueryBroadcast() {
        // 插入两条数据，跨分片
        jdbcTemplate.update("INSERT INTO t_user (id, name) VALUES (?, ?)", 999999L, "test0");
        jdbcTemplate.update("INSERT INTO t_user (id, name) VALUES (?, ?)", 1000001L, "test1");

        // BETWEEN查询，应广播到t_user_0和t_user_1
        List<Map<String, Object>> result = jdbcTemplate.queryForList(
            "SELECT * FROM t_user WHERE id BETWEEN ? AND ?", 999999L, 1000001L);
        assertEquals(2, result.size()); // 必须返回两条
    }

    @Test
    void testBoundaryValues() {
        // 边界值：1000000应进t_user_0，1000001应进t_user_1
        jdbcTemplate.update("INSERT INTO t_user (id, name) VALUES (?, ?)", 1000000L, "boundary0");
        jdbcTemplate.update("INSERT INTO t_user (id, name) VALUES (?, ?)", 1000001L, "boundary1");

        // 验证t_user_0里有1000000，没有1000001
        Long count0 = jdbcTemplate.queryForObject(
            "SELECT COUNT(*) FROM t_user_0 WHERE id = ?", Long.class, 1000000L);
        assertEquals(1L, count0);

        Long count1 = jdbcTemplate.queryForObject(
            "SELECT COUNT(*) FROM t_user_1 WHERE id = ?", Long.class, 1000001L);
        assertEquals(1L, count1);
    }
}

这个测试集的价值在于：它不是验证“功能是否正常”，而是验证“边界是否牢靠”。特别是testBoundaryValues()，它直击范围分片最脆弱的环节——边界计算。很多团队只测id=1和id=2000000，却忘了测id=1000000和id=1000001，结果上线后发现一半数据写错了表。

实操心得：我们在一个金融系统上线前，用这套测试集发现了算法bug。原算法用id / RANGE_SIZE，但id=1000000时结果是1，进了t_user_1。修复后，测试用例立刻失败，提醒我们id=1000000必须进t_user_0。这种“让bug自己暴露”的测试哲学，比写一百行文档都管用。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 问题速查表：从现象到根因的快速定位指南

现象	可能根因	排查命令/步骤	解决方案
`INSERT`成功，但`SELECT * FROM t_user WHERE id = ?`查不到数据	分片算法返回的表名不在`availableTargetNames`中，或物理表未创建	1. 查看`application.yml`的`actual-data-nodes`配置 2. 登录数据库执行`SHOW TABLES LIKE 't_user_%'`	确保`actual-data-nodes`生成的表名，与数据库中真实存在的表名100%一致（包括大小写）
`BETWEEN`查询返回空结果，但单条`SELECT`能查到	查询区间完全落在某个分片外，或算法中的`tableMinId`/`tableMaxId`计算错误	1. 开启`sql-show: true`，看重写后的SQL 2. 手动执行重写后的SQL，确认单表是否有数据	检查`RangeShardingAlgorithm`中`tableMinId = tableIndex * RANGE_SIZE + 1`的偏移量是否正确
应用启动报`Cannot resolve reference to bean 'shardingDataSource'`	`sharding-jdbc-spring-boot-starter`版本与Spring Boot版本不兼容	1. 查`sharding-jdbc`官网的版本兼容矩阵 2. 检查`pom.xml`中`spring-boot-starter-parent`版本	升级`sharding-jdbc-spring-boot-starter`到匹配版本，如Spring Boot 2.3.x对应`sharding-jdbc-spring-boot-starter:4.1.1`
`IN`查询被广播到所有表，性能极差	`IN`列表长度超过`sharding-jdbc`默认阈值（1000），触发全路由	1. 查看日志中`Actual SQL`是否包含所有`t_user_*`表 2. 检查`application.yml`是否配置了`props.sql-show: true`	在`application.yml`中添加`props: {sql-show: true}`，确认广播行为；业务层控制`IN`列表长度≤1000，或改用`BETWEEN`

5.2 独家避坑技巧：来自三年线上运维的五个“绝对不要”

绝对不要在分片键上建唯一索引（除了主键）：比如ALTER TABLE t_user_0 ADD UNIQUE INDEX uk_name (name)。因为name在t_user_0和t_user_1里可以重复，全局唯一性无法保证。唯一索引只能建在主键id上，或者业务层通过分布式ID生成器保证。
绝对不要用SELECT * FROM t_user ORDER BY id DESC LIMIT 10做分页：这会广播到所有分片，每个分片返回10条，合并后取前10条——但真正的第10条可能在t_user_5里，而t_user_0到t_user_4的第10条都被丢弃了。正确做法是：先查MAX(id)，再用WHERE id > ?分页。
绝对不要在application.yml里写死分片表数量：比如actual-data-nodes: ds_0.t_user_${0..9}。生产环境扩容时，你得改配置、重启应用、再建表。应该用actual-data-nodes: ds_0.t_user_${0..${MAX_TABLES}}，并通过JVM参数-DMAX_TABLES=19动态控制。
绝对不要忽略sharding-jdbc的props配置：props: {sql-show: true, executor-size: 16}。sql-show是调试生命线；executor-size控制并行查询线程数，默认是CPU核数，但在IO密集型场景（如跨分片查询），设为16能显著提升吞吐。
绝对不要认为分片后就不用关注单表性能：分片只是把数据打散，没解决单表慢SQL问题。我们线上一个案例：t_user_0因为缺少create_time索引，SELECT * FROM t_user WHERE create_time > '2024-01-01'在单表上就慢到超时。分片后，这个慢查询被广播到10张表，整个接口P99延迟从200ms飙到5s。分片是水平扩展，索引优化是垂直深耕，二者缺一不可。

5.3 性能压测实录：单分片 vs 全局广播的TPS对比

我们用JMeter对工程做了压测，模拟100并发用户，持续5分钟，执行INSERT INTO t_user (id, name) VALUES (?, ?)：

场景	平均TPS	P95延迟(ms)	备注
单分片写入（id固定为500000）	3200	12	所有请求路由到`t_user_0`，无跨分片开销
随机ID写入（1-10000000）	2800	15	请求均匀分散到10张表，轻微锁竞争
`BETWEEN`广播查询（id BETWEEN 1 AND 10000000）	420	230	同时查询10张表，网络+合并开销大

结论很清晰：写入性能几乎不受分片影响，而跨分片查询是性能杀手。所以工程的设计哲学是：让写入尽可能精准路由，让查询尽可能避免跨分片。这也是为什么我们强调id作为分片键——因为它天然支持精确路由，而create_time更适合做二级分片或归档依据。

6. 生产落地建议：从原型到高可用的七步演进路线

这个工程是原型，不是生产方案。要让它扛住真实流量，你需要走完这七步：

6.1 第一步：分片键治理——从“能分”到“该分”的决策框架

不要一上来就分t_user。先问三个问题：
- 数据量：当前t_user有多少行？日增多少？按此速度，多久会超单表500万行阈值？
- 查询模式：EXPLAIN分析慢SQL，95%的查询是否都带id条件？如果没有，分片后这些查询会变慢。
- 变更成本：业务代码里有多少处SELECT * FROM t_user？改成分片键查询，工作量多大？

我们曾帮一个电商系统做评估：他们t_user有800万行，但90%的查询是SELECT * FROM t_user WHERE phone = ?，而phone不是主键。强行用id分片，所有用户查询都变广播。最后方案是：新增user_id字段（冗余id），把phone查询迁移到user_id，再分片。多花两周，但避免了上线后性能雪崩。

6.2 第二步：分片算法工厂化——告别硬编码的`RANGE_SIZE`

把RANGE_SIZE = 1_000_000L写死在代码里，是技术债。应该做成可配置：

sharding:
  user:
    range-size: 500000
    max-tables: 20

然后算法里读取配置：

@Component
public class ConfigurableIdShardingAlgorithm implements PreciseShardingAlgorithm<Long> {

    @Value("${sharding.user.range-size:1000000}")
    private long rangeSize;

    @Value("${sharding.user.max-tables:10}")
    private int maxTables;

    @Override
    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<Long> shardingValue) {
        long id = shardingValue.getValue();
        int tableIndex = (int) ((id - 1) / rangeSize);
        // 安全兜底：不超过最大表数
        tableIndex = Math.min(tableIndex, maxTables - 1);
        return "t_user_" + tableIndex;
    }
}

这样，扩容时只需改配置、发版，无需改代码。

6.3 第三步：分片元数据中心化——用ZooKeeper管理分片规则

application.yml里的分片规则是静态的。生产环境需要动态更新，比如临时禁用t_user_5做维护。这时要用ZooKeeper或Nacos存储分片规则：

spring:
  shardingsphere:
    props:
      # 启用注册中心
      registry-center:
        type: ZooKeeper
        server-lists: zk1:2181,zk2:2181
        namespace: sharding

规则变更后，所有应用实例实时感知，无需重启。这是高可用的基石。

6.4 第四步：分片监控体系——不只是看QPS，要看路由健康度

在Prometheus里加这些指标：
- sharding_routing_precision_total{type="id"}：精确路由次数
- sharding_routing_range_total{type="id"}：范围路由次数
- sharding_routing_broadcast_total{type="id"}：广播路由次数

当broadcast_total突增，说明业务在大量执行跨分片查询，该优化SQL了。

6.5 第五步：分片数据校验——上线后必须做的“体检”

用sharding-jdbc自带的orchestration模块，或自研脚本，定期执行：

-- 校验t_user_0里所有id是否都在1-1000000范围内
SELECT COUNT(*) FROM t_user_0 WHERE id < 1 OR id > 1000000;
-- 校验t_user_1里所有id是否都在1000001-2000000范围内
SELECT COUNT(*) FROM t_user_1 WHERE id < 1000001 OR id > 2000000;

任何非零结果，都是数据错乱的铁证。

6.6 第六步：分片回滚预案——当路由出错时，如何紧急止损

准备三套预案：
- 读降级：关闭分片，直连t_user逻辑表（需提前建好视图或代理表）。
- 写冻结：在网关层拦截所有t_user写请求，返回503 Service Unavailable。
- 数据迁移：用mysqldump导出错表数据，按正确分片规则重新导入。

预案必须演练，不能只写在纸上。

6.7 第七步：分片演进路线图——从范围分片到混合分片的平滑过渡

范围分片不是终点。当业务发展，你会遇到：
- 热点问题：t_user_0写入QPS远高于其他表。
- 归档难题：t_user_0数据要归档，但id范围和其他表交织。

这时，演进路线是：
1. 二级分片：在id范围分片基础上，对create_time做哈希分库，缓解单库压力。
2. 冷热分离：t_user_0到t_user_5放SSD，t_user_6到t_user_9放HDD。
3. 最终混合：id范围分片 + user_type哈希分库，形成二维分片矩阵。