简介：本资源是一份面向Java后端开发者与数据库架构初学者的分库分表实战教学包，聚焦企业级大数据量场景下的数据库水平扩展难题，以Sharding-JDBC为核心框架实现多数据源动态切换与透明化分片。资源共73个文件，涵盖18个Java业务与配置类、21个编译后class文件、18个XML配置与映射文件（含MyBatis映射及Sharding规则定义），以及SQL建表脚本、Maven项目配置（pom.xml）、Eclipse工程元数据（.project/.classpath）等关键开发资产，整体仅66KB，轻量易导入。已有2068人学习下载，适合快速搭建SSMDemo环境并理解分片路由、数据源初始化、YAML分片规则配置等核心实践环节。读者可直接复用项目结构，掌握从多数据源声明、分库分表策略配置到跨库CRUD调用的完整链路，尤其适用于Spring+MyBatis+Sharding-JDBC技术栈的中小规模分片落地参考。

1. 分库分表，多数据源的切换：不是加个注解就完事，而是让每个DAO层调用都清楚自己该连哪张表、哪个库

你刚接手一个日增300万订单的电商后台，MySQL单表已超2800万行，慢查询从“偶发”变成“每分钟必报”，DBA甩来一句：“上分库分表吧。”——结果你兴冲冲引入ShardingSphere，配置好逻辑表、分片键、分片算法，一跑测试发现：用户中心查user_info正常，但订单服务里一个带JOIN的报表SQL直接报错“无法路由到具体数据源”；更玄学的是，同一个Service方法里，前半段insert走的是ds0，后半段update却连到了ds1，事务根本没法提交。这不是配置没生效，而是分库分表的本质从来不是“自动拆分”，而是“显式声明+精准控制”。这个项目就是一套可落地、可调试、可验证的多数据源切换实战方案：它不依赖黑匣子中间件的自动路由，而是用Spring原生AbstractRoutingDataSource + 自定义ThreadLocal上下文 + 显式数据源标记，把“哪个线程该用哪个库”这件事，从配置文件里拽出来，写进代码里、打在日志里、压测时能一眼看穿。适合正在被跨库JOIN、读写分离、历史库归档、灰度发布数据隔离等问题卡住的后端开发者，尤其适合那些已经踩过ShardingSphere规则配置陷阱、想回归可控性的团队。

2. 架构设计与核心模块拆解：三层路由机制，让数据源选择不再靠猜

这个项目不是简单封装了一个DynamicDataSource，而是构建了上下文驱动 + 规则匹配 + 手动覆盖的三级路由体系。它把“用哪个库”这件事，拆成三个可独立验证、可组合使用的环节：最外层是业务语义标记（比如@TargetDataSource("write")），中间层是分片键自动识别（比如方法参数含userId，且当前策略为user_id分片），最内层是线程级强制绑定（比如开启事务时锁定主库）。三者优先级从高到低，冲突时以手动标记为准。这种设计避免了“全局默认库”带来的隐式耦合，也绕开了中间件对SQL语法的强约束——你写原生MyBatis XML，它照样能路由；你用JdbcTemplate手写复杂UNION，它也能按需切库。整个结构轻量（无额外jar依赖）、透明（所有路由决策可打日志）、可测试（Mock ThreadLocal即可覆盖全部分支）。

2.1 核心路由引擎：AbstractRoutingDataSource的深度定制

Spring原生的AbstractRoutingDataSource只提供一个determineCurrentLookupKey()抽象方法，返回String类型的key。但本项目在此基础上做了三处关键增强：

• key不再是简单字符串，而是自定义的DataSourceKey类，包含type(READ/WRITE)、shardId(如"shard_01")、sourceId(如"ds_master_v2")三个维度；
• determineCurrentLookupKey()内部不直接返回key，而是委托给RouterChain执行链式判断；
• 每次key生成后，自动记录到MDC中，供日志追踪（如[ds_key=WRITE:shard_01:ds_master_v2]）。

public class DynamicRoutingDataSource extends AbstractRoutingDataSource { @Override protected Object determineCurrentLookupKey() { // 1. 检查线程局部变量是否已强制绑定 DataSourceKey forcedKey = DataSourceContextHolder.getForcedKey(); if (forcedKey != null) { log.debug("Route forced: {}", forcedKey); return forcedKey; } // 2. 尝试从方法参数/注解提取分片上下文 DataSourceKey contextKey = ContextRouter.routeByContext(); if (contextKey != null) { log.debug("Route by context: {}", contextKey); return contextKey; } // 3. 回退到默认策略（如读写分离下的READ） DataSourceKey defaultKey = DefaultRouter.routeByDefault(); log.debug("Route by default: {}", defaultKey); return defaultKey; } }

提示：DataSourceKey必须实现equals()和hashCode()，否则Spring缓存的targetDataSource Map会失效——这是血泪经验，曾因忘记重写导致同一key反复创建新连接池，DB连接数暴增。

2.2 上下文管理器：ThreadLocal + MDC双保险

DataSourceContextHolder是整个路由的“开关中枢”。它不只存一个String，而是维护三个ThreadLocal变量：

• forcedKey: 用于@Transactional或@TargetDataSource注解触发的强制绑定；
• shardContext: 存储当前请求的分片标识（如userId=12345 → shardId="shard_03"）；
• routeTrace: 布尔值，开启后自动记录每次路由决策路径，用于排查“为什么没走预期库”。

public class DataSourceContextHolder { private static final ThreadLocal<DataSourceKey> FORCED_KEY_HOLDER = new NamedThreadLocal<>("forcedDataSourceKey"); private static final ThreadLocal<ShardContext> SHARD_CONTEXT_HOLDER = new NamedThreadLocal<>("shardContext"); private static final ThreadLocal<Boolean> ROUTE_TRACE_HOLDER = ThreadLocal.withInitial(() -> false); public static void setForcedKey(DataSourceKey key) { FORCED_KEY_HOLDER.set(key); // 同步写入MDC，确保日志可追溯 MDC.put("ds_key", key.toString()); } public static void setShardContext(ShardContext context) { SHARD_CONTEXT_HOLDER.set(context); MDC.put("shard_id", context.getShardId()); MDC.put("shard_key", context.getShardKey()); } public static void enableRouteTrace() { ROUTE_TRACE_HOLDER.set(true); MDC.put("route_trace", "enabled"); } }

NamedThreadLocal是自定义类，继承ThreadLocal并重写toString()，方便在Arthas或jstack线程dump中快速识别该ThreadLocal用途——这点在生产环境排查“某个线程死锁在数据库连接上”时极其关键。

2.3 分片上下文注入：从Controller到Mapper的全链路透传

分片键（如userId、orderId）通常来自HTTP请求参数或RPC上下文，不能靠DAO层自己猜。本项目采用“入口拦截+显式传递”模式：

• Web层：@ShardParam("userId")注解标注Controller方法参数，由ShardArgumentResolver解析并注入ShardContext；
• RPC层：Dubbo Filter或gRPC Interceptor从Attachment或Metadata中提取分片信息；
• 内部调用：Service方法签名强制要求传入ShardContext，杜绝“隐式上下文”。

@RestController public class OrderController { @GetMapping("/order/{orderId}") public OrderVO getOrder( @PathVariable Long orderId, @ShardParam("userId") Long userId) { // ← 此注解触发ShardContext注入 return orderService.getOrder(orderId, userId); } } @Service public class OrderServiceImpl implements OrderService { @Override public OrderVO getOrder(Long orderId, Long userId) { // 1. 主动构造ShardContext，确保下游能路由 ShardContext context = ShardContext.builder() .shardKey("userId") .shardValue(userId) .shardId(ShardAlgorithm.calculateShardId(userId)) // 如 userId % 4 → "shard_02" .build(); DataSourceContextHolder.setShardContext(context); // 2. 执行实际查询（此时DynamicRoutingDataSource已能获取shardId） return orderMapper.selectById(orderId); } }

注意：ShardAlgorithm.calculateShardId()必须是纯函数（无状态、无外部依赖），否则在多线程下可能产生不一致分片结果——这是分库分表最隐蔽的翻车点之一。

3. 数据源配置与初始化：YAML驱动 + 运行时热加载支持

项目摒弃了XML硬编码数据源的方式，采用Spring Boot原生@ConfigurationProperties绑定YAML配置，同时预留了运行时刷新接口（如POST /actuator/datasource/refresh），无需重启即可更新数据源连接池参数。配置结构清晰分层：顶层定义逻辑组（如master-slave-group），中层定义物理实例（如ds_master_v2），底层定义JDBC属性。这种结构天然支持灰度发布场景——你可以先将新库ds_master_v3加入配置但不启用，待压测通过后再修改group.default-write-source: ds_master_v3。

3.1 application.yml核心配置片段

# 多数据源基础配置 spring: datasource: dynamic: primary: master # 默认写库 strict: false # 非严格模式：未匹配到数据源时回退到primary datasource: # 主库（写） master: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-master:3306/order_db_v2?useSSL=false&serverTimezone=Asia/Shanghai username: app_rw password: ${DB_MASTER_PWD} hikari: maximum-pool-size: 20 minimum-idle: 5 # 从库集群（读） slave-01: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-slave-01:3306/order_db_v2?useSSL=false&serverTimezone=Asia/Shanghai username: app_ro password: ${DB_SLAVE_PWD} hikari: maximum-pool-size: 15 slave-02: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-slave-02:3306/order_db_v2?useSSL=false&serverTimezone=Asia/Shanghai username: app_ro password: ${DB_SLAVE_PWD} hikari: maximum-pool-size: 15 # 分片库（历史订单） shard-01: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-shard-01:3306/order_history_shard_01?useSSL=false&serverTimezone=Asia/Shanghai username: app_hist password: ${DB_HIST_PWD} shard-02: driver-class-name: com.mysql.cj.jdbc.Driver url: jdbc:mysql://db-shard-02:3306/order_history_shard_02?useSSL=false&serverTimezone=Asia/Shanghai username: app_hist password: ${DB_HIST_PWD}

3.2 动态数据源工厂：支持运行时新增/删除数据源

DynamicDataSourceFactory负责将YAML配置转化为Map<Object, DataSource>，并注册到DynamicRoutingDataSource中。关键点在于：

• 使用ConcurrentHashMap存储targetDataSources，保证put/remove线程安全；
• 每次refresh时，先关闭旧数据源（调用HikariDataSource.close()），再注入新实例；
• 提供getDataSource(String key)方法供其他组件（如Druid监控）按需获取特定数据源。

@Component public class DynamicDataSourceFactory { private final Map<Object, DataSource> targetDataSources = new ConcurrentHashMap<>(); @PostConstruct public void init() { loadFromConfig(); // 从YAML加载初始数据源 } public void refresh(Map<String, DataSourceProperties> newConfigs) { // 1. 关闭所有旧数据源 targetDataSources.values().forEach(this::closeDataSource); targetDataSources.clear(); // 2. 创建新数据源并注入 newConfigs.forEach((key, props) -> { HikariDataSource ds = createHikariDataSource(props); targetDataSources.put(key, ds); }); // 3. 通知DynamicRoutingDataSource更新 dynamicRoutingDataSource.afterPropertiesSet(); } private void closeDataSource(DataSource ds) { if (ds instanceof HikariDataSource) { ((HikariDataSource) ds).close(); } } }

注意：dynamicRoutingDataSource.afterPropertiesSet()必须显式调用，否则Spring不会重新初始化resolvedDataSources缓存——这是热加载失败最常见的原因。

3.3 分片策略配置：YAML定义规则，Java实现算法

分片逻辑不写死在代码里，而是通过YAML声明规则，再由Java类按需加载。例如：

shard: rules: - table: order_info key: user_id algorithm: mod4 sources: [shard-01, shard-02, shard-03, shard-04] - table: order_detail key: order_id algorithm: hash16 sources: [shard-01, shard-02, shard-03, shard-04]

对应Java端，ShardRuleLoader解析YAML后，生成ShardRule对象存入内存，并由ShardAlgorithmFactory根据algorithm字段返回具体实现：

public interface ShardAlgorithm { String calculateShardId(Object shardValue); } @Component public class Mod4ShardAlgorithm implements ShardAlgorithm { @Override public String calculateShardId(Object shardValue) { if (!(shardValue instanceof Number)) { throw new IllegalArgumentException("Mod4 requires numeric shard value"); } long value = ((Number) shardValue).longValue(); int shardIndex = (int) (Math.abs(value) % 4); // 避免负数取模问题 return "shard-" + String.format("%02d", shardIndex + 1); // shard-01 ~ shard-04 } }

这种解耦让DBA可独立修改分片规则（改YAML），而开发只需维护算法实现，双方无需协同发布。

4. 避坑指南：5个真实踩过的坑，省下你三天排查时间

分库分表不是配置完就能跑通的银弹，而是处处埋雷的精细活。以下是我在某高校实验室模拟项目X中，连续两周压测时踩出的5个典型问题，每一条都附带复现条件、根因分析和可立即验证的修复方案。

4.1 现象：事务内跨库操作不报错，但部分SQL实际执行在错误库上

原因：@Transactional默认传播行为是REQUIRED，当方法A调用方法B时，若B未声明事务，其数据源路由会脱离A的事务上下文，导致B的SQL走默认库而非事务绑定库。
解决：在@Transactional方法内，所有子调用必须显式声明@Transactional(propagation = Propagation.REQUIRED)，或统一使用TransactionTemplate手动控制。更彻底的方案是：在DataSourceInterceptor中检测当前是否在事务中，若在则强制将forcedKey设为事务起始时的key。

4.2 现象：MyBatis二级缓存命中，但返回的数据却是旧库里的脏数据

原因：MyBatis的CachingExecutor在查询前会先查缓存，而缓存key未包含数据源标识（如ds_key），导致从shard-01查到的数据被缓存，后续请求即使路由到shard-02也会命中该缓存。
解决：自定义CacheKey，在org.apache.ibatis.cache.CacheKey.update()中加入DataSourceContextHolder.getForcedKey()的哈希值。或者——更推荐的做法——禁用跨库场景的二级缓存，在Mapper XML中添加<cache eviction="FIFO" flushInterval="60000" size="1000" readOnly="true" blocking="false"/>并设置useCache="false"。

4.3 现象：Druid监控页面显示连接池活跃数为0，但应用日志疯狂打印“getConnection timeout”

原因：DynamicRoutingDataSource的determineCurrentLookupKey()方法抛出异常（如NullPointerException），导致Spring fallback到defaultTargetDataSource，而该项目未配置defaultTargetDataSource，最终返回null，Druid拿到null后静默失败。
解决：在DynamicRoutingDataSource构造时，强制设置setDefaultTargetDataSource(defaultDs)，并在determineCurrentLookupKey()最外层加try-catch，捕获所有异常并返回默认key，同时记录ERROR日志：“Failed to determine data source key, fallback to default”。

4.4 现象：单元测试中@Test方法能正确路由，但集成测试（@SpringBootTest）总是走默认库

原因：Spring Boot Test默认使用Mockito代理，而DataSourceContextHolder的ThreadLocal在线程切换（如@Async、CompletableFuture）时未做透传，导致异步线程丢失上下文。
解决：在测试配置中注入TaskExecutorBean，并重写execute()方法，在提交任务前拷贝ThreadLocal：

@Bean public TaskExecutor taskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); executor.setBeanName("testTaskExecutor"); executor.setTaskDecorator(runnable -> () -> { // 拷贝主线程的DataSource上下文 DataSourceKey key = DataSourceContextHolder.getForcedKey(); if (key != null) { DataSourceContextHolder.setForcedKey(key); } try { runnable.run(); } finally { DataSourceContextHolder.reset(); } }); return executor; }

4.5 现象：分库后SELECT COUNT(*) FROM order_info返回结果比单库少一半

原因：该SQL未带WHERE条件，ShardAlgorithm无法提取分片键，路由引擎按默认策略（如READ）随机选一个库执行，而非广播到所有分片库。
解决：对这类全量聚合SQL，必须显式使用@TargetDataSource("broadcast")注解，并在BroadcastRouter中实现：遍历所有匹配分片库，分别执行SQL，再合并结果集。注意COUNT(*)需用SUM()聚合，GROUP BY需用UNION ALL去重。

5. 运行与验证：从启动到压测，五步确认路由完全受控

光跑通不算成功，必须验证每条SQL都落在预期库上。本项目提供了一套开箱即用的验证流水线，不依赖外部工具，全部基于Spring Boot Actuator和自研Endpoint实现。

5.1 启动检查：确认数据源已正确加载

启动应用后，访问GET /actuator/datasource/info，返回应包含所有配置的数据源及其状态：

{ "status": "UP", "details": { "master": {"status":"UP","active":0,"idle":5}, "slave-01": {"status":"UP","active":0,"idle":3}, "shard-01": {"status":"UP","active":0,"idle":2}, "shard-02": {"status":"UP","active":0,"idle":2} } }

若某个数据源状态为DOWN，检查日志中是否有HikariPool-1 - Failed to validate connection，常见原因是密码错误或网络不通。

5.2 路由追踪：开启MDC日志，实时观察key生成过程

在logback-spring.xml中配置pattern，确保输出%X{ds_key}和%X{shard_id}：

<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level [%X{ds_key}|%X{shard_id}] %logger{36} - %msg%n</pattern> </encoder> </appender>

发起一次请求，日志应类似：

14:22:05.123 [http-nio-8080-exec-1] DEBUG [WRITE:shard_03:ds_master_v2|shard_03] c.e.o.s.OrderServiceImpl - getOrder called with orderId=1001, userId=12345 14:22:05.125 [http-nio-8080-exec-1] DEBUG [WRITE:shard_03:ds_master_v2|shard_03] c.e.o.m.OrderMapper.selectById - ==> Preparing: SELECT * FROM order_info WHERE id = ?

若ds_key为空或与预期不符，说明DataSourceContextHolder.setForcedKey()未被调用。

5.3 SQL拦截验证：确认MyBatis执行的确实是目标库

启用MyBatis日志（logging.level.org.apache.ibatis=DEBUG），观察JDBC Connection日志：

Creating a new SqlSession SqlSession [org.apache.ibatis.session.defaults.DefaultSqlSession@7a8b9c0d] was not registered for synchronization because synchronization is not active JDBC Connection [HikariProxyConnection@123456789 wrapping com.mysql.cj.jdbc.ConnectionImpl@987654321] will not be managed by Spring ==> Preparing: SELECT * FROM order_info WHERE id = ?

关键看wrapping com.mysql.cj.jdbc.ConnectionImpl@xxxxx后的hashcode，对比/actuator/datasource/pools返回的各数据源连接池中活跃连接的hashcode——必须一致才证明路由正确。

5.4 压测验证：用JMeter模拟混合流量，观测分片倾斜度

编写JMeter脚本，按比例发送请求：

• 70%请求：userId在1~100000区间（应均匀分布到4个shard）；
• 20%请求：userId固定为12345（应100%落到shard_03）；
• 10%请求：无userId参数（应走默认master库）。

压测10分钟后，执行：

-- 查看各分片库的order_info表行数 SELECT COUNT(*) FROM order_info; -- 在shard-01库执行 SELECT COUNT(*) FROM order_info; -- 在shard-02库执行 ...

理想结果：shard-01 ~ shard-04行数比值接近70%:70%:70%:70%，而非出现shard-01: 10w, shard-02: 500的严重倾斜。

5.5 故障注入测试：模拟单库宕机，验证降级能力

手动停掉shard-02数据库容器，然后发送原本应路由到shard-02的请求（如userId=20001）。预期行为：

• 若配置spring.datasource.dynamic.strict=false，应自动fallback到primary库（master），并记录WARN日志：“Shard 'shard-02' unavailable, fallback to primary”；
• 若配置strict=true，应抛出DataSourceUnavailableException，由上层业务捕获并返回友好提示。

此测试验证了系统在部分分片不可用时的容错能力，而非直接雪崩。

6. 二次开发与扩展：如何安全地接入新业务、新分片规则、新数据源类型

这个项目的设计初衷就是“可演进”，而不是一次性交付。我把它用在模拟项目X的三个迭代周期中，每次新增需求都只改3个类以内，从未动过核心路由引擎。以下是我沉淀下来的四条改造铁律，以及对应的具体操作模板。

6.1 接入新业务表：三步完成分片配置

假设要为新表user_behavior_log添加分库分表，分片键为user_id，按mod8分到8个历史库：

Step 1：扩展YAML配置
在application-prod.yml中追加：

shard: rules: - table: user_behavior_log key: user_id algorithm: mod8 sources: [shard-log-01, shard-log-02, ..., shard-log-08] spring: datasource: dynamic: datasource: shard-log-01: url: jdbc:mysql://db-log-01:3306/log_db_01?... # ... 共8个数据源定义

Step 2：实现新分片算法

@Component public class Mod8ShardAlgorithm implements ShardAlgorithm { @Override public String calculateShardId(Object shardValue) { long value = Math.abs(((Number) shardValue).longValue()); int index = (int) (value % 8); return "shard-log-" + String.format("%02d", index + 1); } }

Step 3：在Mapper接口上声明分片意图

@Mapper public interface UserBehaviorLogMapper { @Insert("INSERT INTO user_behavior_log (...) VALUES (...)") @TargetDataSource("shard-log") // ← 告诉路由引擎：此Mapper只走shard-log系列库 void insert(UserBehaviorLog record); }

注意：@TargetDataSource("shard-log")中的值必须与YAML中sources列表的前缀一致，路由引擎会自动匹配shard-log-01等具体实例。

6.2 支持新数据源类型：无缝接入PostgreSQL分片库

项目当前只支持MySQL，但某模块需对接PostgreSQL历史库。无需修改DynamicRoutingDataSource，只需：

• 新增PostgreSqlDataSourceFactory，继承AbstractDataSourceFactory，重写createDataSource()方法；
• 在DynamicDataSourceFactory.refresh()中，根据driver-class-name自动选择工厂类；
• PostgreSQL分片算法与MySQL完全复用（Mod8ShardAlgorithm不依赖数据库特性）。

public class PostgreSqlDataSourceFactory extends AbstractDataSourceFactory { @Override protected DataSource createDataSource(DataSourceProperties props) { HikariConfig config = new HikariConfig(); config.setJdbcUrl(props.getUrl()); config.setUsername(props.getUsername()); config.setPassword(props.getPassword()); config.setDriverClassName("org.postgresql.Driver"); // PostgreSQL特有参数 config.addDataSourceProperty("reWriteBatchedInserts", "true"); return new HikariDataSource(config); } }

6.3 审计增强：记录每次路由决策的完整证据链

生产环境需要审计“某次订单查询为何走了shard-03”，项目预留了RouteTrace扩展点。启用方式：

// 在Controller中 @GetMapping("/order/{id}") public OrderVO getOrder(@PathVariable Long id) { DataSourceContextHolder.enableRouteTrace(); // ← 开启追踪 return orderService.getOrder(id); }

启用后，日志自动追加route_path字段：

[ds_key=READ:shard_03:slave-01|shard_id=shard_03|route_path=ANNOTATION→CONTEXT→DEFAULT]

其中ANNOTATION→CONTEXT→DEFAULT表示：先检查了@TargetDataSource注解（未找到），再尝试从参数提取shardContext（成功），最后未触发默认策略。

6.4 灰度发布支持：按用户ID范围动态切流

上线新分片库shard-05时，希望先让userId在1000000~1000010之间的用户走新库，其余走老库。只需扩展ShardAlgorithm：

@Component public class GrayShardAlgorithm implements ShardAlgorithm { @Override public String calculateShardId(Object shardValue) { long userId = ((Number) shardValue).longValue(); if (userId >= 1_000_000 && userId <= 1_000_010) { return "shard-05"; // 灰度库 } // 兜底：走原有mod4算法 return new Mod4ShardAlgorithm().calculateShardId(shardValue); } }

然后在YAML中将user_id表的algorithm改为gray即可。灰度结束后，删掉这段if逻辑，全程无需改SQL、不发版。

从那以后我每次接入新业务表，都强制走一遍这四步模板：配YAML → 写算法 → 打注解 → 压测验证。哪怕凌晨三点上线，只要日志里看到[ds_key=WRITE:shard_05:ds_master_v3]，心里就踏实。希望帮到你。

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