从分钟到秒级 —— Amazon Advanced JDBC Wrapper 插件最佳实践

摘要：数据库的计划内变更（版本升级、打补丁、规格调整）和计划外故障（实例 Failover），都会让应用经历一段连接中断。多数团队会把优化目光投向数据库实例本身，却忽略了一个事实：客户端的连接行为往往是中断被放大的主因。Amazon Web Services Advanced JDBC Wrapper（下称 JDBC Wrapper）正是从这个角度切入——它包裹在现有 JDBC 驱动之外，让 Java 应用主动感知数据库拓扑变化、提前调度连接，把切换中断压到秒级。本文从原理到实测，拆解它是怎么做到的。

一、切换瞬间，连接到底发生了什么

先理解问题。当一次蓝绿切换或 Failover 发生时，从客户端看，连接经历了三重打击：

1. DNS 缓存指向旧节点。集群端点切换到新节点需要时间，操作系统和 Java 进程还缓存着旧 IP。
2. 连接池握着已失效的连接。HikariCP 这类连接池里的物理连接仍指向旧节点，下一次借用时才发现不可用。
3. 重连卡在 TCP 层。连接池补充新连接时，如果解析到尚未就绪的旧 IP，而又没有设置连接超时，TCP 的 SYN 握手会一直挂起，直到操作系统内核默认超时（Linux 约 30 秒）。

[图 1]

二、JDBC Wrapper 是什么

Amazon Web Services Advanced JDBC Wrapper 是对原 Amazon Web Services JDBC 驱动的重新设计。它不直接连接数据库，而是包裹在你现有的 JDBC 驱动之外，在原生驱动之上扩展能力，让应用充分用上 Amazon Aurora 这类集群数据库的特性，同时不必改变既有的开发习惯与驱动工具链。它兼容任意 JDBC 驱动，目前已验证支持 PostgreSQL、MySQL 与 MariaDB，其中 MariaDB 驱动有额外限制——它默认启用的 pipelining 与 Aurora 不兼容，需显式关闭 usePipelineAuth 和 useBatchMultiSend。项目以 Apache 2.0 协议开源，完整源码与文档见开源仓库。

能力以插件形式模块化提供——应用只加载用得到的部分，既减少依赖也降低开销。围绕”缩短切换中断”，有三个关键插件：

• bg：蓝绿部署快速感知
• failover2：故障转移快速感知
• efm2：节点健康监控（Enhanced Failure Monitoring）

bg 插件自 wrapper 2.6.0 起提供。本文实测用的是 3.3 版本，截至发稿 wrapper 已更新到 4.3.0，3.3 系列进入维护期，新项目建议直接用 4.x。

Wrapper 还提供 Amazon Web Services Identity and Access Management（IAM）认证、Amazon Web Services Secrets Manager 凭证管理等插件，本文聚焦与中断时间相关的高可用能力。

三、原理拆解：从感知到调度

3.1 bg 插件：蓝绿切换的”交通指挥”

蓝绿切换过程中，蓝节点会在某一时刻终止连接，集群与实例端点被重定向到绿节点，内部节点名与安全证书也随之变更。bg 插件的目标是尽量降低这些变更对应用的影响，主要通过以下机制实现（依据官方文档）：

1. 分级监控切换状态。插件以三档频率轮询数据库内的蓝绿元数据（以 MySQL 为例，查询 mysql.rds_topology 表）：常规阶段采用基线频率（默认 60 秒），临近切换时提高到 1 秒（可在 500-2000 毫秒间调整），切换进行中进一步提高到 100 毫秒（可在 50-500 毫秒间调整）。
2. 预先收集端点与 IP。在切换发起前，收集蓝、绿两侧集群与实例端点及其对应的 IP 地址。
3. 切换期间暂停对蓝节点的调用。暂停执行发往蓝节点的 JDBC 调用，可降低蓝节点负载、减少绿节点的事务延迟，从而缩短整体切换时间。此外 bgDropBlueConnections 默认为 true，切换一开始就主动断开全部蓝集群连接，让连接池尽早重建。
4. 以 IP 替换主机名建立连接。切换进行中，蓝端点的 DNS 尚未更新到新物理节点，插件使用步骤 2 预收集的 IP 地址直接建立连接，绕过过期的 DNS 缓存。
5. 切换后监测 DNS。持续检查蓝端点的 DNS 解析结果，确认其已指向新节点后，停止 IP 替换，恢复常规的 DNS 解析连接方式。
6. 拒绝过期的绿节点连接并处理回滚。切换完成后，绿环境的端点短暂仍可解析，但即将被废弃；插件自动拒绝指向绿节点的新连接请求。若切换发生回滚，则恢复到切换前的原有状态。

一次完整切换在插件内部依次经历以下状态：IN_PROGRESS（切换开始）→ POST → Green topology changed → Blue DNS updated → Green DNS removed → COMPLETED。插件依据这些状态在各阶段调整流量策略。

[图 2]

3.2 failover2 插件：故障转移的”集中调度”

Failover 场景下，难点是如何快速、准确地找到新的 Writer。早期 failover 插件让每条连接各自探测拓扑，几十条连接同时故障转移时会开出大量线程、给客户端造成额外负载。failover2 做了架构性改进：

• 集中式拓扑监控。探测新 Writer 的工作交给一个独立线程里的中央组件（MonitoringRdsHostListProvider），所有等待中的连接共享它的探测结果。连接线程在等待期间挂起，新 Writer 一旦确认就被统一唤醒、各自重连到目标节点。资源占用大幅下降，连接规模越大优势越明显。
• “Am I a writer?” 避免陈旧拓扑。Aurora 故障转移后，新 Writer 会率先反映真实拓扑，而从 Reader 读到的拓扑可能短暂滞后（仍把旧节点标记为 Writer）。failover2 因此不依赖 Reader 返回的拓扑，而是对各节点逐一发起”你是不是 Writer”的探测，优先从 Writer 直接获取拓扑。
• 并行探测 + 增频确认。需要确认拓扑时，监控组件为每个节点开一条独立线程并行连接探测。新 Writer 检测到之后的 30 秒内，拓扑仍以提高的频率刷新，确保所有 Reader 都正确出现在拓扑里再降回常规频率。

[图 3]

3.3 efm2 插件：连接健康的”探针”

efm2 用独立的监控线程定期向所连节点发送探针：先等待一段检测起始时间，再按固定间隔探测，连续若干次未得到响应就判定节点不健康，主动中止该连接、让查询快速失败，而不是被动等待到超时。它由此比传统超时机制更早发现故障，随后由 failover2 切换到健康节点。对应的三个参数——检测起始时间（failureDetectionTime）、探测间隔（failureDetectionInterval）、判定次数（failureDetectionCount）——直接决定故障检测速度，后面会看到过度调小它们会带来副作用。

四、实测：插件在不同场景下的中断时间

对比一：小于 100 TPS 低负载下，各连接方式的蓝绿切换中断

我们做了多轮 Amazon Aurora 蓝绿切换测试（覆盖跨版本升级与机型变更），用 5 种连接方式以低负载持续读写，记录每轮的写入中断时长。下表为多轮结果的区间：

对比二：3000 TPS 中等负载下的蓝绿切换

对比一为低负载结果。蓝绿切换的中断会不会随写入压力上升而变长？我们把写入负载提高到约 3000 TPS（混合读写），并采用同时应对故障的生产级插件组合（failover2、efm2、bg），对 Amazon Aurora 集群做了多轮蓝绿切换测试，结果如下：

相比对比一的 ~1s，中断略有增加，主要原因是负载越高，切换期间绿环境需要追赶的复制延迟越大，bg 插件暂停调用的等待时间相应拉长。但仍稳定在个位数秒级，未随负载线性增长。

对比三：三种切换场景的中断时间

在同样约 3000 TPS 的负载下，把视角扩展到三种切换场景，bg、failover2、efm2 协同工作时的写入中断如下：

几个值得记录的发现：

• failover2 不可省略。仅保留 bg 插件做 Failover 测试时，应用会连到尚处于只读状态的新节点，持续报错直到连接池 maxLifetime（60 秒）到期才恢复——中断从约 8 秒升至约 68 秒。failover2 提供的拓扑感知，是故障场景恢复的基础。
• 配置同样关键。缺少 JDBC 驱动层的 connectTimeout（MySQL Connector/J 参数，控制单次 TCP 连接建立的超时时间）时，重连到尚未就绪的旧 IP 会在 TCP 握手处挂起约 30 秒，把蓝绿中断从数秒拉长到数十秒；补上 1 秒的 connectTimeout 后，单次连接失败可快速放弃并重试，中断稳定在数秒区间。

五、配置最佳实践

• 务必设置驱动层的 connectTimeout（建议 1000ms，注意区别于 HikariCP 的 connectionTimeout）。这是避免长尾中断的关键配置，官方文档对此也有明确要求：使用 bg 插件时必须提供非零的 connectTimeout 或 socketTimeout。
• 插件链按场景裁剪。蓝绿场景下建议移除会主动剔除旧连接的 auroraConnectionTracker 插件——它在切换时逐个断开连接，反而拉长中断；故障转移场景则必须保留 failover2。
• efm2 参数是双刃剑。把检测时间从 6 秒压到 3 秒，纯重启中断能缩短约 2 秒，但自动 Failover 误触发概率会从 22% 升到 50%——检测过快时，Writer 尚未完成重启即被切换，反而引发多次中断。生产环境建议以稳定为先。
• 应用层加一次快速重试（间隔约 50ms），可大幅度降低业务错误。

5.1 配置示例（Java + HikariCP + JDBC Wrapper）

下面是一份可直接参考的连接配置，插件链与超时取值对应上面的最佳实践。应用代码无需改动——业务仍按标准数据源使用 dataSource 即可。

// 依赖：aws-advanced-jdbc-wrapper、mysql-connector-j、HikariCP
HikariConfig config = new HikariConfig();

// 用 aws-wrapper 的 JDBC URL 包裹原生 MySQL 驱动
config.setJdbcUrl("jdbc:aws-wrapper:mysql://<cluster-endpoint>:3306/<db>");
config.setUsername("<user>");
config.setPassword("<password>");
config.setDriverClassName("software.amazon.jdbc.Driver");

// 让 HikariCP 正确识别 Wrapper 抛出的异常
config.setExceptionOverrideClassName("software.amazon.jdbc.util.HikariCPSQLException");

Properties props = new Properties();
// 插件链：故障转移 + 节点健康监控 + 蓝绿（生产推荐组合）
props.setProperty("wrapperPlugins", "failover2,efm2,bg");
// 方言需与引擎匹配：Aurora MySQL 用 aurora-mysql，RDS MySQL 实例用 rds-mysql
props.setProperty("wrapperDialect", "aurora-mysql");

// 驱动层 TCP 连接超时（关键）：避免连到旧 IP 时握手挂起约 30 秒
props.setProperty("connectTimeout", "1000");
props.setProperty("socketTimeout", "3000");

// efm2 故障检测：默认值，兼顾检测速度与重启稳定性
props.setProperty("failureDetectionTime", "6000");
props.setProperty("failureDetectionInterval", "1000");
props.setProperty("failureDetectionCount", "3");

// bg 蓝绿：切换进行中的高频探测间隔
props.setProperty("bgHighMs", "50");
// bg 的监控连接可以单独设超时，与业务连接分开
props.setProperty("blue-green-monitoring-connectTimeout", "10000");
props.setProperty("blue-green-monitoring-socketTimeout", "10000");

config.setDataSourceProperties(props);

// 连接池：保持池满，切换后补连更快
config.setMaximumPoolSize(10);
config.setMinimumIdle(10);
config.setInitializationFailTimeout(-1);
config.setMaxLifetime(60000);
// 注意：HikariCP 的 connectionTimeout 是“从池中借连接的等待超时”，
// 与上面驱动层的 connectTimeout（TCP 连接超时）不是同一个参数
config.setConnectionTimeout(5000);

HikariDataSource dataSource = new HikariDataSource(config);

关于两个超时：connectTimeout（驱动层 TCP 连接超时）宜短，让单次连到错误 IP 时快速失败、立即重试；connectionTimeout（HikariCP 从连接池借连接的等待）宜稍长，让业务线程熬过几秒的切换窗口而不立即报错。两者目标相反，因此一短一长。

非管理员用户还需为连接账号授权读取蓝绿元数据表（见下一节）。

5.2 配置助手：让 AI 帮你审查 wrapper 配置

上面这些参数彼此牵连，加上插件对部署形态、引擎版本、账号权限各有前置要求，手工核对很容易漏掉一两处。官方仓库提供了一个配置助手 skill——JDBC-WRAPPER-CONFIGURATION-ASSISTANT.md，单个 Markdown 文件，把全部插件、参数、默认值、dialect、failover mode 和兼容性约束都写在里面。加载到 AI 编程工具的知识库后，AI 不用读 wrapper 源码就能回答配置问题。

以 Kiro 为例，把文件放进项目的 .kiro/skills/ 就能生效，放到用户级的 ~/.kiro/skills/ 则对所有工作区生效。Cursor、Amazon Bedrock agent、ChatGPT 也可以把它当作知识文件或系统提示词加载。

它派得上用场的场景有三种：让它按你的运行环境生成一份初始配置（”Give me a default configuration for Aurora MySQL with Spring Boot, HikariCP, and failover support.”）；把现有的 application.yml 或 Properties 片段贴给它做审查；描述故障现象让它定位配置原因（”My pool drains to zero connections right after Aurora failover. I’m using HikariCP and the failover2 plugin. What’s wrong?”）。它面向 wrapper 4.0 及以上版本，可以用做判断“参数是否合法、插件组合有没有冲突、当前部署形态支不支持、必需的授权有没有漏”，遇到不确定的内容会直接说不知道并指向官方文档。

六、适用边界

同样需要明确它的能力边界：

• bg 插件当前支持 Amazon Aurora MySQL/PostgreSQL 集群与 Amazon RDS MySQL/PostgreSQL 实例。但不支持 RDS Multi-AZ DB Cluster、Aurora Global Database for MySQL/PostgreSQL。更多前置条件详见官方文档 Prerequisites。
• 要求客户端能直连集群与实例端点，不支持通过 CNAME 别名连接。
• 引擎版本限制：完整的蓝绿支持依赖数据库内的一张元数据表，因此要求：Aurora MySQL 3.07 及以上；Aurora PostgreSQL 17.5、16.9、15.13、14.18、13.21 及以上；RDS PostgreSQL 需 rds_tools v1.7（对应 17.1、16.5、15.9、14.14、13.17、12.21）及以上，并手动执行 CREATE EXTENSION rds_tools;。RDS MySQL 不受此约束。版本不够时驱动会自己发现元数据表不存在并回退到旧版行为，蓝绿处理仍然可用。
• 非 admin（管理员）数据库用户需额外授权，否则元数据表对该账号不可见，bg 插件无法正常工作。各引擎授权方式不同，详见官方文档 Connecting with non-admin users。以 MySQL 为例：GRANT SELECT ON mysql.rds_topology TO 'your_user'@'%'; FLUSH PRIVILEGES;

七、结语

综合这三个插件，JDBC Wrapper 的核心作用可以归结为一点：把数据库的高可用能力，从实例侧延伸到客户端的连接层。当中断从不可预测的近一分钟收敛到稳定的个位数秒级，靠的不是更换组件，而是把连接行为的每一个环节都验证清楚。

参考文档

➡️ 下一步行动：

相关产品：

• Amazon Aurora — 适用于 PostgreSQL、MySQL 和 DSQL 的无服务器关系数据库服务
• Amazon RDS — 完全托管的关系数据库服务
• Amazon Connect — AI 客户体验解决方案
• Amazon Bedrock — 用于构建生成式人工智能应用程序和代理的端到端平台
• Amazon IAM — 身份管理和访问权限

相关文章：

• AWS Direct Connect 故障演练实战指南
• 构建无服务器Kiro调度平台：用Kiro CLI + EventBridge + ECS Fargate实现定时AI任务
• 使用 AWS Transform Custom轻松完成 Java 应用升级
• Apache SeaTunnel 创新加速 ：AIDLC 方法论实践
• 使用 AWS Route 53 构建高可用 DNS 解析服务：从多主多备到智能健康检测的最佳实践

*前述特定亚马逊云科技生成式人工智能相关的服务目前在亚马逊云科技海外区域可用。亚马逊云科技中国区域相关云服务由西云数据和光环新网运营，具体信息以中国区域官网为准。

本篇作者

AWS 架构师中心：云端创新的引领者 探索 AWS 架构师中心，获取经实战验证的最佳实践与架构指南，助您高效构建安全、可靠的云上应用