动态数据源切换核心代码实现手册文档说明本文档是《动态数据源切换架构设计》的实现篇深入剖析核心类的代码实现细节。建议先阅读架构设计文档以理解整体设计思想。一、核心类概览类名核心职责对应架构层级ConnectionConfigDTO承载外部数据库的连接信息URL/User/Pwd。L1 应用层DynamicSource注解标记需要进行数据源切换的方法。L1 应用层ContextSwitchAspectAOP切面拦截注解负责上下文的设置与清理。L2 拦截层DynamicRoutingEngine核心引擎继承 SpringAbstractRoutingDataSource管理连接池全生命周期。L3 路由层 / L4 资源层二、契约定义 (Contract)2.1 配置对象 (ConnectionConfig)这是一个纯粹的数据传输对象DTO利用 Lombok 简化了代码。它是业务层与底层数据源之间的“协议”。SuperBuilder(toBuildertrue)GetterAllArgsConstructorNoArgsConstructorpublicclassConnectionConfig{StringdriverClassName;// 驱动类如 com.mysql.cj.jdbc.DriverStringurl;// JDBC URLStringuserName;// 用户名Stringpassword;// 密码}2.2 切换注解 (DynamicSource)用于标记在 Service 或 DAO 层的方法上声明该方法需要连接到外部数据源。Target(ElementType.METHOD)Retention(RetentionPolicy.RUNTIME)publicinterfaceDynamicSource{StringDEFAULT_GROUPdefault_group;// 数据源分组用于日志或监控Stringvalue()defaultDEFAULT_GROUP;}三、切面拦截 (The Interceptor)ContextSwitchAspect是整个机制的入口。它利用 Spring AOP 环绕通知Around Advice接管了方法的执行。3.1 核心拦截逻辑 (around)Around(annotation(dynamicSource))publicObjectaround(ProceedingJoinPointjoinPoint,DynamicSourcedynamicSource)throwsThrowable{// 1. 【提取参数】从方法参数中寻找 Config 对象ConnectionConfigconfigfetchConfig(joinPoint);Assert.notNull(config,connection config is null);// 2. 【URL 转换】处理内网/外网地址映射可选逻辑configconfig.toBuilder().url(normalizeUrl(config.getUrl())).build();// 3. 【事务检查】关键安全机制ensureTransactionSafety(config.getUrl());try{// 4. 【激活数据源】创建连接池并绑定到 ThreadLocalroutingEngine.activateConnection(dynamicSource.value(),config);// 5. 【执行业务逻辑】returnjoinPoint.proceed();}finally{// 6. 【资源清理】必须执行防止 ThreadLocal 污染routingEngine.clearCurrentContext();}}3.2 事务安全检查 (ensureTransactionSafety)这是架构设计中“禁止跨库事务”的代码落地。 为什么必须禁止Spring 的事务管理器TransactionManager在事务开启时会将数据库连接Connection绑定到当前线程。如果在事务执行过程中尝试切换数据源Spring 可能会继续复用旧的连接导致数据写入错误的库或者抛出连接不可用的异常。因此必须在切面层提前拦截确保“在事务中不能切换数据源”。privatevoidensureTransactionSafety(StringtargetUrl){// 1. 如果当前不在事务中直接放行 (安全)if(!TransactionSynchronizationManager.isActualTransactionActive()){return;}// 2. 获取当前线程绑定的数据库连接资源ConnectionHolderconnectionHolder(ConnectionHolder)TransactionSynchronizationManager.getResourceMap().get(routingEngine);// 3. 校验如果已经持有连接必须保证 URL 一致if(connectionHolder!null){ConnectionconnconnectionHolder.getConnection();StringcurrentUrlconn.getMetaData().getURL();// 如果事务已经开启在 DB-A但当前方法请求 DB-B这是危险操作必须报错if(!Objects.equals(targetUrl,currentUrl)){thrownewRuntimeException(禁止在事务中切换数据源事务已绑定到 currentUrl但试图切换至 targetUrl);}}}四、动态路由引擎 (The Engine)DynamicRoutingEngine是最复杂的类它集成了Spring 路由、连接池工厂和LRU 缓存三大功能。4.1 线程上下文管理 (ThreadLocal) 为什么要用 ThreadLocalDynamicRoutingEngine继承自 Spring 的AbstractRoutingDataSource。它的核心路由方法determineCurrentLookupKey()是无参的。这意味着我们无法通过方法参数直接把“当前要用哪个数据库”传递进去。因此ThreadLocal成为了唯一的“隐式通道”用于将 AOP 层解析出的 Data Source Key 传递给底层的路由方法。// 存储当前线程的数据源 Key (MD5值)privatestaticfinalThreadLocalStringcontextHoldernewThreadLocal();// AOP 调用此方法设置 KeypublicvoidactivateConnection(Stringgroup,ConnectionConfigconfig){// ... 创建或获取连接池逻辑 ...contextHolder.set(context.getLookupKey());}// AOP 调用此方法清理 KeyvoidclearCurrentContext(){contextHolder.remove();MDC.remove(ds_name);// 清理日志上下文}4.2 Spring 路由钩子 (determineCurrentLookupKey)这是AbstractRoutingDataSource定义的抽象方法。ORM 框架如 MyBatis在请求DataSource.getConnection()时Spring 会自动回调此方法来决定返回哪个具体的 DataSource。OverrideprotectedObjectdetermineCurrentLookupKey(){// 1. 从 ThreadLocal 获取 KeyStringkeycontextHolder.get();// 2. 如果 Key 为空返回 null (Spring 会使用默认数据源)if(keynull){returnnull;}// 3. 简单的校验与日志RoutingContextcontextlookupKeyMap.get(key);if(context!null){// 刷新活跃时间用于 LRUcontext.refreshLastActiveTime();// 设置 MDC让日志中包含数据源名称MDC.put(MDC_KEY,context.getLookupKey());}returnkey;}4.3 双 Key 索引与连接池复用为了解决隐私安全与去重的矛盾我们设计了双 Key 机制。我们可以把它比作“身份证”与“房卡”的关系LongKey (身份证详细信息)内容category_url_username_password_driver包含密码等所有细节。作用只在“办理入住”创建连接池时使用。逻辑系统拿着这个详细清单去查“这位客人这个配置以前来过吗”。如果来过直接复用旧房间没来过才开新房间。LookupKey (房卡/房间号)内容MD5(LongKey)一串看不出原始信息的短字符。作用日常通行证。价值安全你拿着房卡LookupKey在系统里到处走存入 ThreadLocal、打印日志别人捡到了也无法反推出你的银行卡密码数据库密码。轻便MD5 长度固定做 Map 索引比长字符串更快。// Map 1: 全量 Key - Context (用于去重)privatefinalMapString,RoutingContextconfigMapnewConcurrentHashMap();// Map 2: MD5 Key - Context (用于路由查找)privatefinalMapString,RoutingContextlookupKeyMapnewConcurrentHashMap();publicvoidactivateConnection(...){// 1. 生成包含密码的全量 KeyStringlongKeygenerateUniqueKey(group,config);// 2. 先查缓存 (是否存在该连接池)RoutingContextcontextconfigMap.get(longKey);if(contextnull){// 3. 如果不存在创建新连接池DataSourcepoolcreateConnectionPool(config);// 4. 生成短 Key (MD5)用于后续的路由和日志StringlookupKeymd5(longKey);contextRoutingContext.builder().longKey(longKey).lookupKey(lookupKey).build();// 5. 注册到 Spring 的 targetDataSources Map 中registerDataSource(context,pool);}// 6. 绑定短 Key 到当前线程 (安全)contextHolder.set(context.getLookupKey());}五、生命周期管理 (Lifecycle LRU)为了防止无限创建连接池导致 OOM系统通过定时任务调用evictExpiredDataSources进行清理。5.1 LRU 驱逐逻辑privatebooleanisDataSourceAvailable(RoutingContextcontext,DataSourcepool){// 策略 1: 快速检查 (连接池自身状态)if(isPoolHealthy(pool)){returntrue;}// 策略 2: LRU 超时检查// 如果 (当前时间 - 最后活跃时间) maxIdleTime (默认30分钟)DurationidleTimeDuration.between(context.getLastActiveTime(),LocalDateTime.now());if(idleTime.compareTo(MAX_IDLE_TIME)0){returnfalse;// 标记为不可用 - 将被移除}// 策略 3: 物理连接探活 (异步执行 SQL: SELECT 1)// ...}六、代码使用示例6.1 定义 DAO 接口RepositorypublicclassDataRepository{AutowiredprivateSqlSessionsqlSession;// 核心打上注解第一个参数必须是 ConfigDynamicSourcepublicListMapString,ObjectqueryExternalData(ConnectionConfigconfig,Stringsql){// 这里的 sqlSession 会自动被路由到 config 指定的数据库returnsqlSession.selectList(com.example.mapper.selectBySql,sql);}}6.2 业务层调用publicvoidgenerateReport(){// 1. 构建配置ConnectionConfigmysqlConfigConnectionConfig.builder().url(jdbc:mysql://10.0.0.1:3306/bi_db).userName(admin).password(secret).driverClassName(com.mysql.cj.jdbc.Driver).build();// 2. 调用 DAO (切面会自动介入)ListMapString,ObjectresultdataRepository.queryExternalData(mysqlConfig,SELECT * FROM report LIMIT 10);// 3. 处理结果...}