Flyway 从 9.x 升级到 10.x 版本时的兼容性问题解析

问题背景

在数据库迁移工具 Flyway 的版本升级过程中，从 9.x 系列升级到 10.x 系列时，用户可能会遇到一个典型的兼容性问题。这个问题主要表现为系统启动时抛出 ServiceConfigurationError 异常，提示无法获取 MySQLDatabaseType 的无参构造函数，深层原因是找不到 FlywayTeamsUpgradeRequiredException 类。

错误现象

当用户将 flyway-core 从 9.22.1 升级到 10.8.1 版本后，系统启动时会抛出以下异常栈：

java.util.ServiceConfigurationError: org.flywaydb.core.extensibility.Plugin: org.flywaydb.database.mysql.MySQLDatabaseType Unable to get public no-arg constructor
...
Caused by: java.lang.NoClassDefFoundError: org/flywaydb/core/internal/license/FlywayTeamsUpgradeRequiredException

问题根源

这个问题的根本原因在于 Maven 依赖管理的不一致性。虽然用户显式指定了 flyway-core 的版本为 10.8.1，但没有为 flyway-mysql 指定版本，导致 Maven 可能使用了旧版本的 flyway-mysql 依赖。

在 Flyway 10.x 版本中，flyway-mysql 模块的内部实现发生了变化，新增了对 FlywayTeamsUpgradeRequiredException 类的依赖。如果 flyway-mysql 的版本与 flyway-core 不匹配，就会出现类找不到的异常。

解决方案

解决这个问题的正确方法是确保所有 Flyway 相关依赖使用相同的版本号：

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
    <version>10.8.1</version>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
    <version>10.8.1</version>
</dependency>

最佳实践建议

1. 显式指定所有相关依赖版本：对于 Flyway 这种由多个模块组成的工具，应该显式指定所有相关模块的版本号，避免依赖管理工具自动解析可能带来的版本不一致问题。

2. 版本升级时的全面检查：在进行 Flyway 大版本升级时，应该检查项目中所有 Flyway 相关依赖，确保它们都升级到相同版本。

3. 清理 Maven 本地仓库：在解决版本冲突问题后，建议清理 Maven 本地仓库，确保获取的是指定版本的新依赖。

4. Spring Boot 用户注意事项：如果项目使用 Spring Boot，Flyway 版本可能会由 Spring Boot 的依赖管理控制。在这种情况下，应该通过 properties 统一管理 Flyway 版本，或者使用 Spring Boot 推荐的 Flyway 版本。

技术原理深入

Flyway 10.x 版本在架构上做了一些重要调整，特别是引入了更严格的模块化设计和团队版功能检查机制。FlywayTeamsUpgradeRequiredException 是 10.x 版本新增的异常类，用于处理团队版功能的使用检查。当 flyway-mysql 模块尝试加载但找不到这个类时，表明存在版本不匹配的问题。

这种设计体现了 Flyway 向更严格模块边界和功能检查方向的演进，但也带来了更严格的版本一致性要求。开发者在升级时需要特别注意这一点。

总结

Flyway 从 9.x 升级到 10.x 是一个重要的版本跨越，带来了架构上的改进但也引入了更严格的依赖管理要求。通过确保所有相关模块版本一致，可以避免这类兼容性问题。这个案例也提醒我们，在现代 Java 开发中，精确控制依赖版本是保证系统稳定性的重要一环。