Micronaut 4.6.1 与 Liquibase 集成问题分析及解决方案

问题背景

在将 Micronaut 框架从 4.5.1 版本升级到 4.6.1 版本后，开发者发现 Liquibase 数据库迁移功能出现了异常。具体表现为应用启动时 Liquibase 无法正确执行数据库脚本，并抛出"Invalid object name 'DATABASECHANGELOG'"的错误。

错误现象

当应用启动时，Liquibase 尝试检查数据库变更日志表时失败，错误堆栈显示：

1. 首先抛出 SQLServerException，提示"Invalid object name 'DATABASECHANGELOG'"
2. 随后引发 InvocationTargetException
3. 最终导致 UndeclaredThrowableException

问题根源分析

经过深入排查，发现问题并非直接由 Micronaut 或 Liquibase 引起，而是与 Apache Tomcat JDBC 连接池相关：

1. 在 Micronaut 4.6.1 中，默认使用的 Tomcat JDBC 连接池版本存在兼容性问题
2. 当连接池代理执行 SQL 查询时，异常处理机制出现异常
3. 该问题在 Tomcat JDBC 10.1.29 版本中已得到修复

解决方案

针对此问题，开发者可以采用以下任一解决方案：

方案一：升级 Tomcat JDBC 连接池

<dependency>
  <groupId>org.apache.tomcat</groupId>
  <artifactId>tomcat-jdbc</artifactId>
  <version>10.1.29</version>
</dependency>

方案二：回退 Micronaut 版本

如果暂时无法升级连接池，可以回退到 Micronaut 4.5.1 版本：

<parent>
  <groupId>io.micronaut.platform</groupId>
  <artifactId>micronaut-parent</artifactId>
  <version>4.5.1</version>
</parent>

技术细节

1. 异常链分析：问题源于连接池对 JDBC 异常的包装处理不当，导致原始 SQLServerException 被错误地转换为 UndeclaredThrowableException

2. Liquibase 工作机制：Liquibase 在启动时会首先查询 DATABASECHANGELOG 表来判断需要执行哪些变更脚本，这个初始检查失败导致整个迁移过程中止

3. 连接池代理机制：Tomcat JDBC 连接池通过动态代理包装 Statement 对象，在 10.1.29 之前的版本中，这种代理机制对异常的处理存在缺陷

最佳实践建议

1. 在使用 Micronaut 与 Liquibase 集成时，建议明确指定连接池版本以避免潜在的兼容性问题
2. 对于生产环境，应在升级框架版本前进行全面测试，特别是数据库迁移相关功能
3. 考虑在测试用例中加入 Liquibase 迁移的验证逻辑，确保数据库变更能够正确执行

总结

Micronaut 4.6.1 与 Liquibase 的集成问题主要源于底层连接池的异常处理机制。通过升级 Tomcat JDBC 连接池到 10.1.29 或更高版本，可以完美解决这一问题。这也提醒我们在微服务架构中，组件间的版本兼容性需要特别关注，特别是在涉及数据库操作等关键功能时。