1. 项目概述为什么我们需要Flyway和一套使用规范在任何一个需要与数据库打交道的Java项目中尤其是那些采用微服务架构、需要频繁迭代和部署的项目里数据库脚本的管理都是一个绕不开的痛点。我见过太多团队初期靠着开发人员手动执行SQL脚本勉强维持。但随着版本增多、人员流动问题开始集中爆发生产环境漏执行脚本导致功能异常、测试环境数据不一致、回滚时手忙脚乱忘记撤销DDL操作……这些“人肉运维”带来的混乱最终都会转化为线上事故和深夜加班。Flyway的出现就是为了将数据库的版本变更变得像管理应用代码一样可控和自动化。它的核心思想很简单将每一次数据库结构或数据的变更都编写成一个有版本号的SQL脚本或Java代码。Flyway会像Git管理代码版本一样追踪这些脚本的执行状态确保在任何环境开发、测试、生产中数据库都能被一致地、按顺序地迁移到目标版本。而“多数据源配置”和“使用规范”则是将这个好工具用对、用好的关键。很多团队引入了Flyway却因为配置不当或使用混乱反而引入了新的复杂度。比如一个服务需要连接多个业务数据库分库分表、读写分离、多租户等如何让Flyway精准地管理每一个数据源再比如团队成员随意命名脚本、在已发布的脚本上反复修改导致版本线混乱。因此今天我们不只讲怎么配更要讲怎么配得稳、用得顺分享一套经过多个生产项目验证的配置方案和团队协作规范。2. 核心思路与方案选型Flyway在多数据源场景下的设计考量2.1 Flyway的核心工作机制解析在深入配置之前我们必须理解Flyway是怎么工作的。它会在你配置的数据库中自动创建一个名为flyway_schema_history的表表名可配置。这张表是Flyway的“大脑”记录了所有已执行迁移脚本的详细信息version: 脚本的版本号是排序和判断是否执行的核心依据。description: 脚本的描述方便人类阅读。type: 脚本类型如SQL或JAVA。script: 脚本的文件名。checksum: 脚本内容的校验和用于检测脚本是否被篡改。installed_by: 执行人。installed_on: 执行时间。execution_time: 执行耗时毫秒。success: 是否执行成功。当应用启动并初始化Flyway时它会执行以下流程扫描在配置的路径如classpath:db/migration下扫描所有符合命名规范的SQL文件。排序根据文件名中的版本号对所有脚本进行排序。版本号必须全局唯一且递增。比对将扫描到的脚本列表与flyway_schema_history表中已成功执行的记录进行比对。执行按顺序执行所有“新的”即表中不存在的迁移脚本。记录每个脚本成功执行后立即向flyway_schema_history表插入一条成功记录。这是一个关键设计执行与记录在同一个数据库事务中。这意味着如果脚本执行到一半失败不仅数据库操作会回滚flyway_schema_history表也不会记录这条部分执行的脚本保证了状态的一致性。注意这个机制也带来了一个重要约束。对于DDL语句如CREATE TABLE,ALTER TABLE很多数据库如MySQL的InnoDB并不支持在事务中回滚。Flyway会尝试在一个事务中运行整个迁移但如果遇到不支持事务的DDL它可能会提交事务。因此对于重要的生产变更务必先在测试环境充分验证。2.2 多数据源配置的常见场景与方案抉择当你的Spring Boot应用需要连接多个数据库时Flyway的配置就需要仔细设计。主要场景和对应方案如下场景一主从数据库/读写分离需求通常只需要对主库写库进行结构迁移从库读库通过复制同步。方案这是最简单的场景。只需为指向主库的DataSource配置Flyway即可。确保Flyway的初始化在应用业务逻辑启动之前完成避免应用启动时去连接一个尚未完成迁移的从库。场景二垂直分库不同业务域使用独立数据库需求订单服务连接order_db用户服务连接user_db。两个数据库 schema 完全不同需要独立管理各自的迁移脚本。方案这是多数据源配置的典型场景。我们需要为每一个DataSource独立配置一个Flyway实例。关键在于隔离脚本的存放路径、flyway_schema_history表名或schema必须区分开避免互相干扰。场景三多租户每个租户一个独立Schema或Database需求所有租户共享相同的表结构但数据物理隔离。方案Schema级多租户配置一个基础的DataSource然后使用Flyway的schemas配置项或者在运行时动态为每个租户的Schema执行迁移。Flyway社区版对此支持有限可能需要结合自定义逻辑或使用Flyway Teams版本。Database级多租户等同于场景二为每个租户数据库配置独立的数据源和Flyway实例通常通过程序动态管理。场景四使用 dynamic-datasource-spring-boot-starter 等多数据源框架需求方便地进行数据源切换并希望集成Flyway。方案这是一个高频痛点。很多开发者配置后遇到Failed to configure a DataSource: ‘url’ attribute is not specified错误。其根本原因是Spring Boot的自动配置在多个DataSource共存时发生了冲突。核心思路是排除Spring Boot对DataSourceAutoConfiguration的自动配置然后手动、显式地创建每一个DataSourceBean和对应的FlywayBean。我们将在实操部分详细解决。方案选型背后的考量选择哪种方案取决于你的数据隔离级别和运维复杂度。对于大多数微服务间的垂直分库场景二采用“独立数据源 独立Flyway实例”是最清晰、最易维护的方式。它职责单一每个服务的数据库变更由其自身服务完全掌控符合微服务的设计原则。3. 核心配置解析与实操要点3.1 基础单数据源Flyway配置详解在Spring Boot中基础的Flyway配置极其简单这得益于其强大的自动配置。在application.yml中配置即可spring: datasource: url: jdbc:mysql://localhost:3306/my_db?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver flyway: enabled: true # 启用Flyway默认就是true locations: classpath:db/migration # 迁移脚本的位置默认值 table: flyway_schema_history # 元数据表名默认值 baseline-on-migrate: true # 当发现非空数据库且没有元数据表时自动执行基线迁移 baseline-version: 0 # 基线版本号 encoding: UTF-8 # 脚本编码 validate-on-migrate: true # 迁移时是否验证建议true out-of-order: false # 是否允许乱序执行生产环境务必设为false clean-disabled: true # 禁用flyway clean命令生产环境必须true关键参数解读与避坑指南baseline-on-migrate这个参数非常有用。想象一下你是在一个已有数据的旧项目上引入Flyway。数据库不是空的但又没有flyway_schema_history表。如果此参数为false默认Flyway会报错要求你手动执行baseline。设为true后Flyway会自动将当前数据库标记为baseline-version的版本然后开始执行比基线版本更新的迁移脚本。对于已有项目接入Flyway这个参数应设为true。out-of-order默认false。如果设为trueFlyway会执行那些版本号比当前已执行的最新版本低、但之前因为某种原因被跳过的脚本。这在某些协作场景下可能有用但在生产环境强烈建议保持false以确保严格按时间线执行迁移。clean-disabled这是最重要的安全配置之一。flyway clean命令会清除指定schema下的所有对象表、视图等相当于清空数据库。在任何生产或预发环境的配置中必须显式将其设置为true防止误操作导致灾难性后果。3.2 多数据源配置的完整实现与深度避坑现在我们重点解决最复杂的场景一个Spring Boot应用需要连接两个完全独立的业务数据库例如user_db和order_db并为它们分别配置Flyway。步骤一添加依赖确保你的pom.xml包含了必要的依赖。除了基础的Spring Boot Starter我们还需要数据库驱动和Flyway。dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-jdbc/artifactId /dependency dependency groupIdorg.flywaydb/groupId artifactIdflyway-core/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency !-- 如果使用其他数据库替换为对应的驱动 -- /dependencies步骤二排除自动配置准备手动配置在应用主类上排除DataSourceAutoConfiguration。这是解决多数据源冲突的关键第一步。SpringBootApplication(exclude {DataSourceAutoConfiguration.class}) public class MultiDatasourceApplication { public static void main(String[] args) { SpringApplication.run(MultiDatasourceApplication.class, args); } }步骤三编写主配置类定义两个数据源及其Flyway Bean这里我们创建一个DataSourceConfig配置类。我们将使用ConfigurationProperties来从application.yml读取配置这样更清晰。首先在application.yml中定义两个数据源的配置app: datasource: user: url: jdbc:mysql://localhost:3306/user_db?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/Shanghai username: root password: user_password driver-class-name: com.mysql.cj.jdbc.Driver order: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf-8useSSLfalseserverTimezoneAsia/Shanghai username: root password: order_password driver-class-name: com.mysql.cj.jdbc.Driver然后编写配置类Configuration public class DataSourceConfig { // ---------------- 用户数据源 ---------------- Bean ConfigurationProperties(app.datasource.user) public DataSource userDataSource() { // 使用 HikariCP Spring Boot 默认的连接池 return DataSourceBuilder.create().type(HikariDataSource.class).build(); } Bean public Flyway flywayUser(DataSource userDataSource) { return Flyway.configure() .dataSource(userDataSource) // 关键脚本路径隔离防止冲突 .locations(classpath:db/migration/user) // 关键元数据表名隔离两个库各自记录自己的执行历史 .table(flyway_user_schema_history) .baselineOnMigrate(true) .outOfOrder(false) .load(); } // 使用 DependsOn 确保 Flyway 在 EntityManagerFactory 之前执行 Bean DependsOn(flywayUser) public LocalContainerEntityManagerFactoryBean userEntityManagerFactory( EntityManagerFactoryBuilder builder) { return builder .dataSource(userDataSource()) .packages(com.yourcompany.domain.user) // 指定User实体所在的包 .persistenceUnit(userPersistenceUnit) .build(); } Bean public PlatformTransactionManager userTransactionManager( Qualifier(userEntityManagerFactory) LocalContainerEntityManagerFactoryBean userEntityManagerFactory) { return new JpaTransactionManager(userEntityManagerFactory.getObject()); } // ---------------- 订单数据源 ---------------- Bean ConfigurationProperties(app.datasource.order) public DataSource orderDataSource() { return DataSourceBuilder.create().type(HikariDataSource.class).build(); } Bean public Flyway flywayOrder(DataSource orderDataSource) { return Flyway.configure() .dataSource(orderDataSource) // 脚本路径隔离 .locations(classpath:db/migration/order) // 元数据表名隔离 .table(flyway_order_schema_history) .baselineOnMigrate(true) .outOfOrder(false) .load(); } Bean DependsOn(flywayOrder) public LocalContainerEntityManagerFactoryBean orderEntityManagerFactory( EntityManagerFactoryBuilder builder) { return builder .dataSource(orderDataSource()) .packages(com.yourcompany.domain.order) // 指定Order实体所在的包 .persistenceUnit(orderPersistenceUnit) .build(); } Bean public PlatformTransactionManager orderTransactionManager( Qualifier(orderEntityManagerFactory) LocalContainerEntityManagerFactoryBean orderEntityManagerFactory) { return new JpaTransactionManager(orderEntityManagerFactory.getObject()); } }实操心得与深度避坑DependsOn注解至关重要如果没有DependsOn(flywayUser)Spring可能会先初始化EntityManagerFactory。此时它会立刻尝试连接数据库并验证实体与表的映射关系。如果此时Flyway尚未运行数据库表可能不存在导致应用启动失败。DependsOn明确规定了Bean的初始化顺序。脚本路径与历史表名必须隔离这是多数据源Flyway配置的核心原则。locations和table属性必须为每个数据源唯一指定。如果两个Flyway实例扫描同一个路径或写入同一张历史表会导致脚本重复执行或状态错乱。关于DataSourceAutoConfiguration我们排除了它是因为当Spring Boot检测到多个DataSourceBean时它的自动配置机制会困惑不知道应该将FlywayAutoConfiguration绑定到哪个DataSource上从而可能引发‘url’ attribute is not specified错误。手动创建所有Bean给了我们完全的控制权。连接池选择示例中使用了HikariDataSource它是Spring Boot 2.x 后的默认连接池性能非常好。确保在type()方法中明确指定避免因类路径上有多个连接池实现而出现意外。3.3 迁移脚本的命名规范与内容编写指南Flyway对SQL脚本文件名有严格约定这是其版本管理的基础。规范命名是团队协作的基石。命名格式前缀 版本号 分隔符 描述 后缀前缀V版本化迁移只执行一次。U撤销迁移UndoFlyway社区版不支持商业版功能。R可重复迁移Repeatable每次校验和变化时都会重新执行。常用于创建视图、存储过程、插入静态数据。版本号推荐使用点分数字格式如11.12.0.3。也可以使用日期格式如2024.01.01.001。必须全局唯一且递增。分隔符双下划线__注意是两个下划线。描述使用下划线连接的小写英文单词简要描述本次迁移的目的。要求清晰、简洁。后缀.sql示例V1__Create_user_table.sqlV1.1__Add_email_to_user.sqlV20241010.001__Create_order_table.sqlR__Populate_initial_data.sql(可重复迁移没有版本号)脚本内容编写注意事项原子性每个脚本应该完成一个逻辑完整的变更单元。不要在一个脚本里创建10张不相关的表。这有利于问题定位和回滚虽然Flyway不支持自动回滚但小单元便于手动处理。幂等性尽量编写幂等的SQL语句。例如使用CREATE TABLE IF NOT EXISTS而不是CREATE TABLE使用INSERT IGNORE或ON DUPLICATE KEY UPDATE。这对于可重复迁移R前缀脚本尤其重要也能在手动执行时减少错误。避免在版本化迁移V中使用存储过程/视图定义如果存储过程的逻辑后续需要修改你会需要创建新的V脚本来DROP and CREATE这很笨拙。更好的做法是将存储过程/视图的定义放在可重复迁移R脚本中。当定义修改时只需更新同一个R脚本文件Flyway会在下次启动时检测到校验和变化并重新执行。注释在SQL脚本中使用--添加必要的注释说明变更原因、业务背景或复杂的逻辑。测试数据生产环境的迁移脚本绝对不要包含测试数据。测试数据的插入应通过其他途径如专门的测试数据脚本、调用API等在开发/测试环境完成。4. 完整工作流与团队协作规范4.1 从开发到上线的标准操作流程一个健康的Flyway工作流应该集成到团队的Git和CI/CD流程中。本地开发当需要修改数据库结构时绝不直接在数据库客户端工具里执行。在项目的src/main/resources/db/migration/或对应的多数据源子目录下创建一个符合命名规范的新SQL文件。在本地编写并测试SQL脚本。可以启动本地应用让Flyway自动执行验证脚本是否正确。重要一旦一个V前缀的脚本被提交到主分支或任何共享分支就视为已发布严禁修改其内容。因为其他开发者的本地数据库和历史表已经记录了它。修改会导致校验和不匹配Flyway校验会失败。如果脚本有错误必须创建新的版本化迁移脚本来修复。代码提交与Code Review将新创建的SQL脚本文件连同相关的业务代码一起提交到Git。在Pull Request中数据库变更脚本是必须Review的部分。Review重点命名规范、SQL语法、性能影响如索引添加、是否幂等、是否有数据丢失风险。持续集成在CI流水线如Jenkins、GitLab CI中应有一个步骤专门针对每个Pull Request或合并后的分支启动一个干净的测试容器如Testcontainers运行Flyway迁移然后执行集成测试。这能提前发现脚本错误或与代码不兼容的问题。预发与生产环境发布发布新版本应用时CI/CD流程应先执行数据库迁移再部署新版本应用。通常有两种模式捆绑式将Flyway集成在应用内应用启动时自动迁移如我们上述配置。这是最简单的方式但要确保应用的新版本与数据库变更向前兼容即旧版本应用也能在新版本数据库上运行一段时间以便于滚动发布和回滚。分离式在部署应用前使用独立的Flyway命令行工具或在一个专门的任务中执行迁移。这给了运维更多控制权但流程更复杂。黄金法则生产环境的迁移必须经过预发环境的完全验证且必须有回滚预案。回滚预案通常意味着准备好一个能兼容旧数据库 schema 的旧版本应用以及如何安全地回退数据变更的手动步骤因为Flyway不提供自动回滚。4.2 必须遵守的团队使用规范脚本命名权责统一规定只有负责该次功能迭代的主开发人员才有权创建和命名新的迁移脚本。避免多人同时创建导致版本号冲突。禁止修改已提交的V脚本这条规则需要刻在脑子里。如果发现已提交的V脚本有严重错误正确的做法是情况一错误脚本尚未在任何正式环境特别是生产环境执行。可以协商后在团队内同步让大家删除本地历史表记录或重置数据库然后修正脚本并强制推送git push -f。此操作风险极高仅适用于小团队且未扩散的情况。情况二错误脚本已经在某个环境执行。唯一正确的方式是创建一个新的V脚本来修复它。例如V1.0.1__Fix_incorrect_column_type.sql。使用R脚本管理视图和静态数据将数据库视图、存储过程、函数以及基础的国家/地区代码等静态数据定义在R__开头的可重复迁移脚本中。当需要修改时直接编辑原文件即可。大表变更需谨慎对于百万级以上数据表执行ALTER TABLE操作可能会锁表并导致服务中断。应在脚本中考虑使用在线DDL工具如pt-online-schema-change for MySQL或分步操作并在业务低峰期执行。文档化在项目的README或 Wiki 中明确记录Flyway的使用流程、命名规范、回滚策略和常见问题。新成员入职时应据此培训。5. 常见问题排查与实战技巧实录即使配置正确在实际使用中还是会遇到各种问题。下面是我在多个项目中总结的“踩坑记录”。5.1 典型错误与解决方案速查表错误现象可能原因解决方案Validate failed: Migration checksum mismatch已执行的迁移脚本内容被修改。严禁修改已发布的V脚本。如果是在开发环境可以执行flyway repair命令来修复校验和慎用。如果是生产环境创建新脚本修复。Found non-empty schema without metadata table在一个已有数据但无flyway_schema_history表的数据库上启用Flyway且未设置baseline-on-migrate: true。设置spring.flyway.baseline-on-migratetrue和spring.flyway.baseline-version通常设为0或1。或者手动执行flyway baseline命令。Failed to configure a DataSource: ‘url’ attribute is not specified多数据源配置冲突Spring Boot自动配置无法确定主数据源。如本文所述在主类上使用SpringBootApplication(exclude {DataSourceAutoConfiguration.class})并手动配置所有DataSource和FlywayBean。启动时Flyway没有执行任何脚本1.spring.flyway.enabled被设置为false。2.locations路径配置错误脚本未被扫描到。3. 脚本命名不符合规范。1. 检查配置。2. 检查locations路径确保是classpath:前缀且目录存在。3. 严格遵循V{版本}__{描述}.sql的命名格式。多数据源下脚本在错误的数据源上执行未正确隔离locations和table配置导致Flyway实例扫描了错误的路径或写入了同一张历史表。确保为每个FlywayBean 独立配置locations如classpath:db/migration/db1和table如flyway_db1_history。迁移过程中出现语法错误导致失败SQL脚本本身存在语法错误或使用了目标数据库不支持的语法。1. 在本地或测试环境充分测试脚本。2. 检查SQL方言。确保为MySQL编写的脚本不会在PostgreSQL上运行。3. 查看Flyway日志定位出错的具体行。java.lang.IllegalStateException: Cannot find migrations location通常发生在多模块项目中迁移脚本放在非主模块的resources目录下而主模块的类路径扫描不到。1. 确保脚本位于主应用类模块的resources目录下。2. 或者使用filesystem:前缀指定绝对路径不推荐不利于移植。3. 检查Maven/Gradle构建配置确保资源文件被正确打包。5.2 高级技巧与实战心得在测试中使用flyway.clean() 绝对不要有些开发者为了方便会在单元测试的BeforeEach方法中调用flyway.clean().migrate()来重置数据库。这非常危险因为clean()会删除所有对象。如果测试配置错误意外连接到了开发或共享测试数据库后果是灾难性的。安全的做法是使用内存数据库如H2或利用Testcontainers启动一个独立的数据库容器进行测试。如何管理不同环境的差异化配置例如你需要在开发环境插入一些测试数据但生产环境不需要。有几种方法使用Profile-specific配置在application-dev.yml中配置spring.flyway.locations包含一个额外的路径如classpath:db/testdata里面放置R__脚本用于插入测试数据。生产环境的配置则不包含这个路径。使用Flyway CallbacksFlyway提供了生命周期回调如beforeMigrate,afterMigrate。你可以编写Java回调类根据当前激活的Spring Profile在迁移后执行特定的数据初始化逻辑。处理大数据量初始化或迁移如果一个V脚本需要插入或更新大量数据例如初始化基础数据可能会非常慢甚至导致连接超时。建议将大数据操作拆分成多个小脚本分批提交。在脚本中禁用索引和约束数据插入完成后再重建可以大幅提升速度。考虑使用数据库原生的批量导入工具如MySQL的LOAD DATA INFILE编写脚本而不是成千上万的INSERT语句。与JPA Hibernate的ddl-auto共存强烈建议不要同时使用Flyway和Hibernate的spring.jpa.hibernate.ddl-auto尤其是create或create-drop。这会导致Hibernate尝试根据实体创建表与Flyway的脚本产生冲突。应该将ddl-auto设置为validate仅验证映射关系或none不执行任何DDL将数据库结构的定义权完全交给Flyway。版本号策略推荐对于长期项目我推荐使用日期序号的版本号例如V20241015.001__xxx.sql。这种方式的优势是一目了然地知道变更发生的时间线并且即使多个分支并行开发只要保证同一天内的序号不重复就很难产生版本号冲突。这比单纯使用1.0,1.1这样的数字更直观也更容易在团队中管理。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
