做支付对账那块业务的时候，我第一次真正被多数据源按在地上摩擦。当时的场景很朴素：主库放交易流水，另外还有一个历史归档库和一个只读报表库，业务代码里要在一个请求里既写主库又查报表库。我一开始想得很简单，加个@DS注解不就完了，结果上线第一天就发现归档数据写进了主库，排查了两个多小时才定位到是切面顺序和事务边界打架。从那以后，凡是要在 Spring Boot 里做多数据源的项目，我都会先把需求边界、切换时机、事务归属这三件事捋清楚再动手。这篇就把我这些年踩过的路、用过的方案、写过的配置整理出来，从"到底该不该用多数据源"一路讲到"切面为什么静默失效"，适合正在做数据拆分、读写分离、历史库迁移或者多租户隔离的开发者，也适合只想搞清楚AbstractRoutingDataSource到底怎么跑的人。
1. 先确认这件事到底该不该做：多数据源的真实适用边界
多数据源在项目里是个典型的"用起来爽、维护起来疼"的东西。我在评审代码时见过太多明明一张表能解决、非要拆两个库的例子，最后带来的复杂度远超收益。所以在写第一行配置之前，值得花十分钟想清楚：你的场景属于哪一种，技术诉求差在哪里。
1.1 四类常见场景，诉求其实完全不同
我把遇到过的需求归成四类，每一类对应的实现路线都不太一样：
| 场景类型 | 典型诉求 | 推荐方案 | 主要风险 |
|---|---|---|---|
| 读写分离 | 主库写入、从库查询，分摊压力 | 动态路由 + 注解标记只读方法 | 主从延迟导致读不到刚写的数据 |
| 冷热数据分离 | 主库存近期数据，归档库查历史 | 独立 SqlSessionFactory 或动态路由 | 跨库分页、跨库统计做不了 |
| 多租户/多业务库 | 同一套代码服务不同库，结构一致 | 动态路由 + 租户上下文 | 租户上下文丢失、越权访问 |
| 异构数据接入 | 一个业务要同时连 MySQL 和另一类存储 | 独立数据源 + 独立 Mapper 包 | 事务无法统一，需要补偿 |
看清楚这张表你会发现，只有"结构一致、随时可切"的场景才适合动态路由。冷热分离和异构接入本质上是两套独立的持久层，硬塞进一个路由里，后面写 SQL 时到处判断方言、分页插件一换就崩，维护成本会指数级上升。
我当时那个项目就属于第二种，归档库的表结构和主库虽然相似但索引、字段长度都不一样。最开始用动态路由，结果一个联表统计的 SQL 在两个库之间切换时报字段不存在，改了半天才发现是归档库少了一列。后来改成两套独立的SqlSessionFactory，Mapper 接口按包名隔开，虽然啰嗦一点，但再也没出过这种问题。
1.2 什么情况下应该掉头就走
有两类情况我建议直接放弃多数据源方案。
第一类是数据量根本没到瓶颈。单表几百万行、QPS 几百的场景，加索引、优化慢 SQL、加一层本地缓存，收益比拆库高一个数量级，而且不引入任何分布式复杂度。我见过一个日活几千的系统拆了三个库，最后跨库查询全靠应用层内存拼装，一次列表接口要发十几条 SQL。
第二类是强一致要求高的跨库写入。比如扣款和记账必须同时成功，这种用两个数据源 + 本地事务是做不到的，只能上分布式事务或者改成同库不同表。分布式事务的代价（性能、运维、故障排查难度）在小团队里往往扛不住，用本地消息表 + 定时对账兜底，工程上更现实。
一句实话：多数据源解决的是"连接不同库"的问题，不是"数据一致性"的问题。这两件事经常被混为一谈，是很多线上事故的源头。
2. 三条技术路线怎么选：路由、独立工厂与现成中间件
确定要做之后，接下来是选型。市面上的做法基本就三条，我把它们的实现机制和代价摊开讲，方便你对着自己的场景做判断。
2.1 动态路由方案：一个 DataSource 伪装成多个
Spring 自带的AbstractRoutingDataSource是这个思路的核心。它本身是个DataSource，内部维护一个Map<Object, Object>存放真实数据源，每次调用getConnection()时会回调determineCurrentLookupKey()拿到一个 key，再从 map 里取出对应的真实数据源。
关键源码逻辑大致是这样：getConnection()调用determineTargetDataSource()，后者先取 lookupKey，再resolvedDataSources.get(lookupKey)，取不到就回退到defaultTargetDataSource。注意lenientFallback默认为true，所以 key 为 null 或者找不到时会静默走默认库——这一点非常容易埋雷，后面第 6 节会专门讲。
这个方案的好处是对上层完全透明。MyBatis、JPA、JdbcTemplate 都只认一个DataSource，你不用改任何持久层配置，事务管理器也只需要配一个（前提是不跨库）。代价是它只支持"切换"，不支持"并存"——一个事务里只能有一个库生效。
2.2 多套独立配置：啰嗦但边界清晰
每个数据源配一套DataSource+SqlSessionFactory+SqlSessionTemplate+MapperScannerConfigurer，Mapper 接口按包分开。代码量大概是动态路由的三倍，但换来的是：
- 每个库可以有独立的 MyBatis 配置、独立的分页方言、独立的 TypeHandler
- 编译期就能看出某个 Mapper 属于哪个库，不会出现"跑起来才知道连错库"
- 事务管理器天然分开，
@Transactional(transactionManager = "xxx")显式指定，不会误用
缺点也很明显：Mapper 不能复用，跨库 join 完全做不了，一旦业务要"从归档库查明细、从主库查状态"再拼装，代码会写得很碎。
我一般的判断标准是：结构一致用路由，结构不一致用独立配置。两边都想占，通常两边都不讨好。
2.3 中间件方案：省事，但要接受它的假设
现在比较流行的是直接在依赖里引入一个多数据源 starter，用注解标记方法走哪个库，配置写在 yml 里，切面、上下文、事务代理都帮你做好了。这类方案上手极快，一个注解就能跑通。
但用之前最好确认几件事：它的切面顺序是怎么排的、和@Transactional谁在外层、支不支持运行时动态加库、跨库事务是什么策略。我遇到过一次，框架默认把数据源切面排在事务切面之内，导致事务已经拿到连接了再切换，注解形同虚设——后来只能手动调整@Order值。
至于分库分表的中间件，那是另一个量级的东西，它解决的是"一张表拆到多个库"的问题，配置成本和学习曲线都高得多。如果只是"两个固定的库各查各的"，用它属于杀鸡用牛刀。
3. 手写动态数据源：从配置到切面的完整落地
这一节给一套我自己反复用过的实现，代码不多，但每个细节都有原因。生产环境直接用没问题，前提是把第 4 节的事务部分一起看完。
3.1 数据源 Bean 的注册方式与配置隔离
先定义配置结构，把每个库的参数分开写，避免键名冲突：
spring: datasource: master: jdbc-url: jdbc:mysql://db-master:3306/trade?useSSL=false&serverTimezone=Asia/Shanghai username: trade_rw password: ${MASTER_PWD} driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 3000 idle-timeout: 600000 max-lifetime: 1800000 report: jdbc-url: jdbc:mysql://db-report:3306/report?useSSL=false&serverTimezone=Asia/Shanghai username: report_ro password: ${REPORT_PWD} driver-class-name: com.mysql.cj.jdbc.Driver hikari: maximum-pool-size: 10 minimum-idle: 2 read-only: true注意这里用的是jdbc-url而不是url。如果用DataSourceBuilder+@ConfigurationProperties的方式构建，Hikari 认的是jdbc-url，写成url会在启动时报"jdbcUrl is required"，这是新手最容易卡住的第一个点。
然后是配置类：
@Configuration public class DataSourceConfig { @Bean("masterDataSource") @ConfigurationProperties(prefix = "spring.datasource.master") public DataSource masterDataSource() { return DataSourceBuilder.create().type(HikariDataSource.class).build(); } @Bean("reportDataSource") @ConfigurationProperties(prefix = "spring.datasource.report") public DataSource reportDataSource() { return DataSourceBuilder.create().type(HikariDataSource.class).build(); } @Bean("dynamicDataSource") @Primary public DataSource dynamicDataSource(@Qualifier("masterDataSource") DataSource master, @Qualifier("reportDataSource") DataSource report) { DynamicRoutingDataSource ds = new DynamicRoutingDataSource(); Map<Object, Object> targets = new HashMap<>(4); targets.put(DataSourceKey.MASTER, master); targets.put(DataSourceKey.REPORT, report); ds.setTargetDataSources(targets); ds.setDefaultTargetDataSource(master); return ds; } }@Primary必须加，否则 Spring 在自动装配DataSource时会因为存在多个候选而报错。同时建议把DataSourceAutoConfiguration排除掉，或者确保它不会覆盖你的配置——两者同时生效时，默认数据源可能把你手写的 Bean 顶掉。
3.2 路由键的持有方式：为什么用栈而不是普通变量
很多人用单个ThreadLocal<String>存当前数据源，一开始没问题，但一旦出现方法嵌套调用就麻烦了：A 方法切到 report，内部调用 B 方法切到 master，B 结束后应该回到 report，但单变量只能回到默认值。
所以我用双端队列做栈式管理：
public final class DataSourceContextHolder { private static final ThreadLocal<Deque<String>> HOLDER = ThreadLocal.withInitial(ArrayDeque::new); private DataSourceContextHolder() {} public static void push(String key) { HOLDER.get().push(key); } public static void poll() { Deque<String> deque = HOLDER.get(); if (!deque.isEmpty()) { deque.pop(); } if (deque.isEmpty()) { HOLDER.remove(); } } public static String peek() { Deque<String> deque = HOLDER.get(); return deque.isEmpty() ? null : deque.peek(); } }poll()里那句HOLDER.remove()很关键。线程池里的线程是复用的，如果只 pop 不清理，ThreadLocal会一直挂在线程上，虽然值是空的 deque，但ThreadLocalMap的 Entry 不会释放，长时间运行就是内存泄漏。而且万一某次异常导致没清干净，下一个复用这条线程的请求可能带着上一次的残留 key，表现就是"偶尔查错库"，这种 bug 极难复现。
路由数据源本身只做一件事：
public class DynamicRoutingDataSource extends AbstractRoutingDataSource { @Override protected Object determineCurrentLookupKey() { return DataSourceContextHolder.peek(); } }返回 null 时会走defaultTargetDataSource，这正好是我们想要的默认行为。
3.3 注解与切面的三个易错细节
注解定义很简单：
@Target({ElementType.METHOD, ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface DS { String value() default DataSourceKey.MASTER; }切面才是重点：
@Aspect @Component @Order(Ordered.HIGHEST_PRECEDENCE + 1) public class DataSourceAspect { @Around("@annotation(ds)") public Object around(ProceedingJoinPoint pjp, DS ds) throws Throwable { DataSourceContextHolder.push(ds.value()); try { return pjp.proceed(); } finally { DataSourceContextHolder.poll(); } } }三个细节值得展开说。
第一，@Order的值必须比事务切面小。Spring 的@Transactional背后是TransactionInterceptor，默认 order 是Ordered.LOWEST_PRECEDENCE（即Integer.MAX_VALUE）。切面的数字越小越靠外，所以数据源切面要配成一个小值，保证"先切数据源、再开事务"。如果反过来，事务已经通过DataSourceTransactionManager从默认库拿了连接并绑定到线程上，后面再切路由键，getConnection()返回的还是已经绑定的那个连接，切换直接失效。这个现象极其隐蔽——日志没有报错，代码看起来也没问题，就是数据写错了库。
第二，finally里一定要出栈。我见过用@After通知的写法，方法抛出异常时@After确实会执行，但如果切面内部本身抛异常，或者在异步线程里调用，行为就不确定了。try-finally是最稳的。
第三，只加@annotation不够，要考虑类级别注解。如果@DS打在类上，@annotation是匹配不到的，需要加上@within：
@Around("@annotation(ds) || @within(ds)")不过@within和@annotation一起用时，参数绑定要小心，两个切入点都可能有DS，Spring 会选择就近的那个。稳妥的做法是分开写两个方法，或者在切面里通过MethodSignature自己取注解。
3.4 上下文跨线程怎么传
这是第二个大坑。异步任务、@Async方法、CompletableFuture、线程池里提交的任务，全都拿不到父线程的ThreadLocal。InheritableThreadLocal只能解决"创建子线程时继承"，线程池里的线程是提前创建好复用的，继承机制完全失效。
我的处理方式分两种。简单场景就在提交任务前手动捕获并透传：
String key = DataSourceContextHolder.peek(); executor.submit(() -> { DataSourceContextHolder.push(key); try { // 业务逻辑 } finally { DataSourceContextHolder.poll(); } });任务多的时候这么写太啰嗦，就换成可传递的 ThreadLocal 实现，或者干脆用装饰器包装Executor，在execute和submit前后自动做 push/poll。不管哪种方式，原则都一样：跨线程的上下文必须显式传递，不能指望框架帮你兜底。
4. 事务：多数据源里最容易翻车的部分
前面反复提到事务边界，这一节把它讲透。我敢说，多数据源相关的线上问题里，至少七成出在事务上。
4.1 事务一旦开启，切换就变成了摆设
DataSourceTransactionManager在开启事务时做了两件事：从DataSource拿一个Connection，然后把它绑定到TransactionSynchronizationManager的ThreadLocal资源里。之后整个事务期间，任何DataSourceUtils.getConnection()拿到的都是这个已绑定的连接，根本不会再走determineCurrentLookupKey()。
所以下面这段代码是无效的：
@Transactional public void saveAll(Order order) { orderMapper.insert(order); // 走默认库，事务已开启，连接已绑定 historyService.archive(order); // 方法上标了 @DS(REPORT)，但连接还是那个 }archive里的写入会落到主库，而不是归档库。更麻烦的是，如果归档库的表在主库不存在，你会看到一个"表不存在"的错误，然后误以为是路由配置错了，实际是事务绑定导致的。
正确的做法只有一条：把跨库操作拆到事务之外。
@Transactional(rollbackFor = Exception.class) public void saveAll(Order order) { orderMapper.insert(order); } public void saveAndArchive(Order order) { saveAll(order); // 主库事务，独立提交 archiveService.archive(order); // 归档库操作，另一个事务 }代价是丧失了原子性。如果归档失败，主库的数据已经提交了。工程上的补偿办法是加一个归档状态字段 + 定时任务重试，或者写本地消息表异步投递。这比硬上分布式事务简单得多，也更可控。
4.2 多数据源下的多个事务管理器
如果用动态路由，并且不跨库，一个事务管理器就够了，因为它拿连接时走的是路由数据源，@DS生效的情况下会拿到对应库的连接。但要注意：一个事务内只能用一个库，这是路由方案的天花板。
如果用独立配置的多套SqlSessionFactory，就必须有多套事务管理器：
@Bean("masterTxManager") public PlatformTransactionManager masterTxManager( @Qualifier("masterDataSource") DataSource ds) { return new DataSourceTransactionManager(ds); } @Bean("reportTxManager") public PlatformTransactionManager reportTxManager( @Qualifier("reportDataSource") DataSource ds) { return new DataSourceTransactionManager(ds); }使用时必须显式指定：
@Transactional(transactionManager = "masterTxManager", rollbackFor = Exception.class)不指定会怎样？Spring 会去找标记了@Primary的那个，或者按类型唯一匹配。如果有多个候选又没有@Primary，启动就报错；如果有@Primary，就静默用默认那个——于是你以为在操作归档库事务，实际上全在主库上。这种"不报错但语义错误"的情况最消耗排查时间。
4.3 跨库写入的三种兜底思路
真要做跨库写入，我给三个方案，按实现成本从低到高排：
本地消息表：在业务库里建一张消息表，和业务数据在同一个事务里写入，然后由定时任务扫描未发送的消息，调用另一个库的写入接口，成功后标记完成，失败按退避策略重试。要求下游接口幂等。
对账补偿：两边各写各的，每天定时比对差异，人工或者自动修复。适合对实时性要求不高的归档、统计类场景。
分布式事务框架：AT 模式或者 TCC 模式，能保证最终一致性，但引入了额外的中间件依赖，性能损耗明显，运维复杂度也上去了。小团队慎用，除非业务真的到了那个量级。
我自己在归档场景用的是对账补偿，因为归档数据晚几分钟到完全能接受，而对账任务本身也顺便帮我发现了不少数据质量问题。
5. 连接池参数、敏感信息与可观测性
配完路由和事务，还有几个东西不调好，上线一样会出事。
5.1 HikariCP 的连接数不是拍脑袋定的
maximum-pool-size的常见误区是"设大点总没错"。数据库的连接数是有硬上限的，一个实例几百个连接就会开始抖动。我的估算方式是：
单库需要的连接数 ≈ QPS × 平均单次 SQL 耗时（秒）× 安全系数（1.5~2）
举个例子，报表库峰值 QPS 50，平均查询 20ms，那么 50 × 0.02 × 2 = 2，考虑到突发流量，设 10 完全够用。主库写入 QPS 200，平均耗时 5ms，200 × 0.005 × 2 = 2，但写入常伴随事务，事务持有连接的时间比单条 SQL 长，实际要按事务时长算，设 20 比较稳妥。
几个参数的取值建议：
| 参数 | 建议值 | 说明 |
|---|---|---|
maximum-pool-size | 按上式估算 | 不要超过数据库max_connections的 1/3 |
minimum-idle | 核心库设为 max 的 1/4 | 预热连接，减少冷启动延迟 |
connection-timeout | 3000ms | 拿不到连接就快速失败，别让请求堆积 |
max-lifetime | 1800000ms | 必须小于数据库或中间层的空闲超时，否则会拿到已断开的连接 |
read-only | 只读库设为 true | 让驱动层做一层保护，防止误写 |
max-lifetime那个坑我踩过。当时数据库侧配了 30 分钟空闲断连，连接池没设max-lifetime（默认也是 30 分钟），两边时间卡得太近，导致池里经常有已经被服务端关掉的连接，业务侧报"connection is closed"。后来把max-lifetime调到 25 分钟，问题消失。连接池的生命周期一定要比服务端短，这是硬规则。
5.2 密码别明文躺在 yml 里
配置文件进版本库是常态，明文密码等于裸奔。最省事的做法是用环境变量占位，配上${MASTER_PWD}这种写法，部署时注入。再进一步可以用配置中心或者密钥管理服务，但小团队用环境变量已经能挡住大部分风险。
还有一个细节：不同数据源最好用不同的数据库账号，并且最小权限。报表库的账号只给SELECT，归档库的账号只给INSERT和SELECT，主库才给完整权限。这样即使代码写错了路由，也会被数据库权限拦住，从"写错数据"降级成"报权限错误"，两者的排查成本差着量级。
5.3 出了问题怎么看出来
多数据源最怕的是"静默走错库"。我一般会加两层观测：
一是路由日志。在切面里打一行 debug 日志，记录方法名和路由键，出问题时打开日志就能看到每个方法实际走了哪个库。
log.debug("route -> {}, method: {}", ds.value(), pjp.getSignature().toShortString());二是连接池指标。Hikari 自带 Micrometer 支持，接入后能看到每个数据源的活跃连接数、等待队列长度、连接获取耗时。报表库的活跃连接数长期打满，说明池子小了或者有慢查询；主库的等待队列持续非零，说明连接不够用，请求在排队。
再配合 Actuator 的/actuator/health，把数据源健康检查打开，某个库挂了能第一时间从监控上看到，而不是等用户报错。
6. 几个真实踩过的坑和排查链路
最后这部分是我压箱底的记录，基本都是"现象诡异、排查费劲"的类型，按我实际的排查顺序写，方便你遇到类似问题时对着走一遍。
6.1 切面没生效：从现象反推的排查路径
现象：某个 Service 方法加了@DS("report")，但查出来的数据明显是主库的。
我的排查顺序是这样的：
第一步，看方法是不是被同类内部调用。Spring AOP 基于代理，this.method()这种调用绕过代理，注解直接失效。日志里如果连切面的 debug 输出都没有，基本就是这个原因。解决办法是注入自身代理、拆到另一个类，或者用AopContext.currentProxy()（需要开exposeProxy，不太推荐，污染代码）。
第二步，看@Order有没有排在事务之后。在前面加一行日志，打印TransactionSynchronizationManager.isActualTransactionActive()，如果进来时已经是true，说明事务先开了，切换无效。
第三步，看路由键到底传进去没有。在determineCurrentLookupKey()里打日志，如果打印的是 null，说明切面没 push 成功，回头查注解匹配条件；如果打印的是正确值但查的还是主库，那就是事务绑定的问题。
第四步，看是不是lenientFallback兜底了。路由键拼写错了（比如"reprot"），resolvedDataSources.get()返回 null，框架不报错，直接走默认库。我建议重写determineTargetDataSource()，key 找不到时直接抛异常，把静默失败改成显式失败：
@Override protected DataSource determineTargetDataSource() { Object key = determineCurrentLookupKey(); if (key != null && !getResolvedDataSources().containsKey(key)) { throw new IllegalStateException("未注册的数据源: " + key); } return super.determineTargetDataSource(); }这四步走完，基本没有定位不了的切换失效问题。
6.2 异步任务里切库失灵
现象：主流程查主库正常，通过@Async调用另一个方法标了@DS("report")，结果还是查主库。
原因很直接：@Async把方法扔到线程池执行，新线程的ThreadLocal是空的，peek()返回 null，走默认库。
这里有个容易混淆的点：@DS注解本身在异步线程里是能生效的，因为切面会在新线程里执行 push。所以如果异步方法自己加了@DS，是没问题的。出问题的是"父线程设置了上下文，指望子线程继承"这种用法。
排查时打印线程名就能确认：主线程http-nio-8080-exec-1，异步线程task-1，两个ThreadLocal完全隔离。
顺带提一个相关的问题：异步方法里如果还开了事务，事务管理器绑定的是当前线程的连接，跨线程传递连接是不允许的，会直接报错。所以异步方法里的数据库操作最好保持单条、无事务，或者自己管理事务边界。
6.3 分页插件和 SQL 方言的连带问题
现象：动态路由方案下，报表库的分页 SQL 报语法错误。
原因是分页插件在做 count 查询或者拼 limit 时，依赖配置的数据库方言。如果两个库的类型不同（比如一个 MySQL 一个其它），插件只认一个方言，另一个库自然报错。
即使两个库都是 MySQL，也可能出问题：报表库如果是只读的视图或者特殊的存储引擎，某些优化语句会失败。我的处理方式是给报表库的查询单独配置一个SqlSessionFactory，插件独立配置，不去共用。如果非得共用，那就放弃自动分页，在 Mapper 里手写分页 SQL，虽然土，但绝对不会出问题。
还有一个连带问题：MyBatis 的二级缓存是按 namespace 隔离的，但如果两个库共用同一个 Mapper 接口，缓存key 里不包含数据源信息，就会出现"从主库读到的缓存被报表库查询命中"的诡异现象。结论很明确——多数据源场景下，坚决关掉二级缓存，本地缓存用 Redis 或者在 Service 层自己做，别指望 MyBatis 的缓存机制。
再补充一个我在实际项目里养成的习惯：所有涉及多数据源的 Mapper 方法，我都会在方法名上加后缀区分，比如selectByIdFromReport、insertIntoArchive。名字难听，但比注释管用，代码评审时一眼就能看出这个方法走的是哪个库，也避免了后来接手的人误用。多数据源这东西，能靠命名约束就别靠记忆，人的记忆是最不可靠的一环。
6.4 动态加库时的一个细节
有些场景需要在运行时注册新数据源，比如多租户系统按租户动态接入。AbstractRoutingDataSource的targetDataSources是个普通的 Map，直接put进去还不够，必须重新调用一次afterPropertiesSet()，因为这个方法里会把targetDataSources解析到内部的resolvedDataSources，不调用的话新加的数据源根本不生效。
另外，动态添加时要考虑连接池的关闭。租户下线或者数据源被替换时，旧的数据源如果是HikariDataSource，记得调close()，否则连接会一直挂着，时间长了数据库连接数就被耗光了。我见过一次，测试环境反复重启压测，最后数据库报连接数超限，查下来是动态数据源没关。
我个人在实际操作中的体会是，多数据源这件事，代码量其实不大，难点全在边界判断上：哪些操作能在一个事务里、哪些必须拆开、上下文在哪里会丢、切换在什么时候会失效。把这四个问题在动手之前想清楚，剩下的配置和注解都是体力活。真正让人头疼的从来不是"怎么写"，而是"写了为什么不生效"——所以第 6 节那套排查链路，建议你直接存下来，下次遇到诡异现象时逐条对照，比从头读文档快得多。
