Druid 连接池版本迁移：从 1.0.x 到 1.2.x 的完整升级实战

【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品，为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid

把 Druid 从 1.0.x 升到 1.2.x，构建是过了，日志里却开始刷 deprecated 警告，监控面板数据也说不清是坏在配置还是版本上——升级做了一半，心里没底。这篇指南带你走完 Druid 连接池版本迁移的完整流程：从动手前的检查清单，到依赖、配置、API 的逐项实操，再到踩坑排障和升级后的验证调优，照着做就能直接落地，不用自己翻源码拼凑信息。

一、版本差异速览：1.0.x 与 1.2.x 改了什么

影响最大的是前两项：容量配置从maxIdle迁移到minIdle+maxActive，以及监控数据获取方式的变化。这两处不改，升级后要么一直刷错误日志，要么监控页直接没数，后面所有调优都无从谈起。

二、动手前的检查清单

• 备份现网配置：把当前application.properties/ Spring XML / 数据源工厂的 properties 完整存档，作为回滚基线
• 确认 starter 版本匹配：Spring Boot 3 用druid-spring-boot-3-starter，Boot 2 用druid-spring-boot-starter，Boot 4 用druid-spring-boot-4-starter，版本错位会导致自动配置整体失效
• 扫描废弃 API 调用：全局搜索mergWallStat、maxIdle等旧写法，记录在案的先别急着删，迁移时统一处理
• 预留回滚窗口：升级与回滚放同一发布窗口，确认监控面板和 SQL 防火墙功能可快速验证
• 核对连接检测配置：确认testWhileIdle、validationQuery（或 JDBC4 校验）已就绪，升级后空闲连接行为会变，没有校验手段很容易埋雷

三、核心迁移实操

3.1 更新依赖：先换对 starter 再换核心包

版本号以仓库 core/src/main/java/com/alibaba/druid/VERSION.java 和官方发布说明为准，此处以 1.2.29 为例：

<dependency> <groupId>com.alibaba</groupId> <artifactId>druid</artifactId> <version>1.2.29</version> </dependency> <!-- Spring Boot 3 项目配套使用（Boot 2 换成 druid-spring-boot-starter） --> <dependency> <groupId>com.alibaba</groupId> <artifactId>druid-spring-boot-3-starter</artifactId> <version>1.2.29</version> </dependency>

注意：starter 与主包版本必须一致，且与你的 Spring Boot 主版本对应。starter 选错时症状是数据源静默退化成普通DataSource，监控与过滤器全部失效，比直接报错难查得多。

3.2 配置清理：maxIdle 的退场与容量参数定型

新版setMaxIdle()已被@Deprecated，每次调用都会向日志输出maxIdle is deprecated错误。旧配置里它和maxActive混着用，迁移后容量语义由minIdle+maxActive完全接管：

# 变更前（1.0.x 常见写法） druid.initialSize=5 druid.minIdle=5 druid.maxActive=20 druid.maxIdle=30 druid.maxWait=60000 # 变更后（1.2.x） druid.initialSize=5 druid.minIdle=5 druid.maxActive=20 druid.maxWait=60000

maxIdle直接删除即可，它不再参与容量计算。maxActive默认只有 8，从 1.0 升上来如果当初没显式配置过，这里一定要显式补齐。

Spring Boot 项目里同样的参数放在spring.datasource.druid前缀下：

spring.datasource.druid.url=jdbc:mysql://localhost:3306/db spring.datasource.druid.username=root spring.datasource.druid.password=password spring.datasource.druid.initial-size=5 spring.datasource.druid.min-idle=5 spring.datasource.druid.max-active=20 spring.datasource.druid.max-wait=60000 spring.datasource.druid.filters=stat,wall

3.3 API 迁移：监控统计接口的替换

自定义监控代码里如果还在用旧版工具方法，需要按废弃标记替换：

// 变更前：旧版拼写错误的方法，已标记 @Deprecated Map stat = DruidStatManagerFacade.mergWallStat(mapA, mapB); // 变更后：使用修正后的方法 Map stat = DruidStatManagerFacade.mergeWallStat(mapA, mapB);

另外注意JdbcSqlStat新增了isRemoved()状态标记：统计列表里会被标记为 removed 的 SQL 项，遍历时需要自行过滤，否则自定义报表里会出现已下线的脏数据。

四、高频踩坑与排障

问题一：启动后日志持续刷 "maxIdle is deprecated"

• 现象：日志里反复出现maxIdle is deprecated的 ERROR 级信息，业务无感知。
• 原因：配置文件或代码里仍残留maxIdle配置项，setMaxIdle()在新版被@Deprecated，每次赋值都会打日志。
• 解法：1) 全局搜索配置文件与代码，删除maxIdle相关设置；2) 用minIdle+maxActive按预期容量重设组合；3) 重启确认日志干净、连接数行为符合预期。

问题二：升级后 Stat View 监控页 404 或数据全空

• 现象：/druid/index.html打不开，或页面打开但数据源、SQL 统计全部为空。
• 原因：新版 starter 中 stat-view-servlet 由开关控制，且统计依赖filters=stat挂载的过滤器，两者缺一不可。
• 解法：1) 确认开启：

spring.datasource.druid.stat-view-servlet.enabled=true spring.datasource.druid.filters=stat,wall

2. 检查应用实际加载的 starter 与 Spring Boot 版本是否匹配；3) 重启后重新访问面板，确认数据源列表有数据。

问题三：空闲连接被数据库/防火墙侧掐断

• 现象：业务低峰期取连接偶发Communications link failure。
• 原因：旧版没有保活手段，空闲连接超过中间设备超时后被单方面关闭，Druid 不知情。
• 解法：1) 开启keepAlive=true并设置keepAliveBetweenTimeMillis；2) 确认testWhileIdle=true与timeBetweenEvictionRunsMillis配置合理，详见 doc/connection-pool-guide.md。

五、升级后的验证与调优

• 启动日志干净：无 deprecated 警告、无异常堆栈
• Stat View 面板可访问，数据源、SQL 监控、Web URI、SQL 防火墙各页签数据完整
• 压测连接获取耗时与旧版本基线持平或更优
• SQL 防火墙（wall filter）拦截行为符合安全基线
• 监控页确认removed的 SQL 统计项已被过滤，不污染报表

建议把上面的指标记录下来作为性能基线：每次升级或调整容量参数后都对照一次。日常把 Stat View 接入团队例行巡检，配合日志中timeBetweenLogStatsMillis输出的周期统计，异常能在第一时间暴露。

升级完成只是起点，不是终点。连接池参数和业务流量是动态博弈的，保持观察才能把 1.2.x 的能力吃透。

1. 一周内建立连接获取耗时、活跃连接数、SQL 耗时的基线数据
2. 把监控面板纳入发布检查流程，每次变更必过一遍
3. 有读写分离或分库分表场景的，评估引入 HighAvailableDataSource 做数据源层负载均衡

下一步，打开你的监控面板，看看迁移后的第一组数据吧 🚀

【免费下载链接】druid阿里云计算平台DataWorks(https://help.aliyun.com/document_detail/137663.html) 团队出品，为监控而生的数据库连接池项目地址: https://gitcode.com/gh_mirrors/druid/druid