1. 引言：多模块Liquibase集成挑战
在Spring Boot项目中，当主应用程序需要引入一个外部的共享库（如JAR包）时，如果该外部库也使用Liquibase进行数据库版本管理，并且拥有自己的changelog文件（例如library.xml），而主应用程序也有自己的changelog文件（例如main.xml），就会面临一个挑战：如何让Liquibase同时执行这两个不同的changelog文件？
Spring Boot的Liquibase自动配置通常只会根据spring.liquibase.change-log属性加载一个主changelog。为了解决这一问题，我们需要通过自定义配置来定义多个SpringLiquibase实例，每个实例负责管理一个特定的changelog文件。
2. 核心思路：定义多个SpringLiquibase Bean
Liquibase在Spring Boot中通过SpringLiquibase类进行集成。默认情况下，Spring Boot会自动配置一个SpringLiquibase Bean。要管理多个changelog文件，最直接的方法就是手动定义额外的SpringLiquibase Bean。每个Bean都可以独立配置其数据源和changelog路径。
下面将介绍两种实现方式。
3. 方案一：基于@Configuration的简单多Liquibase配置
这种方法通过在一个配置类中手动创建并配置SpringLiquibase Bean来管理不同的changelog。它适用于对配置有明确控制需求，且不想过多依赖Spring Boot自动配置属性绑定的场景。
3.1 配置示例
创建一个Spring @Configuration类，并在其中定义多个SpringLiquibase Bean：
package com.example.app.config;
import liquibase.integration.spring.SpringLiquibase;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.DependsOn;
import javax.sql.DataSource;
@Configuration // 确保这个配置类被Spring扫描到
public class MultipleLiquibaseConfiguration {
/**
* 配置外部库的Liquibase实例
* 负责执行 library.xml 中的迁移
* @param dataSource 应用程序的数据源
* @return 配置好的 SpringLiquibase 实例
*/
@Bean
public SpringLiquibase liquibaseLib(DataSource dataSource) {
SpringLiquibase liquibase = new SpringLiquibase();
liquibase.setDataSource(dataSource);
liquibase.setChangeLog("classpath:library.xml"); // 指定库的 changelog 文件
// 可以根据需要设置其他属性，如默认模式、上下文等
// liquibase.setDefaultSchema("lib_schema");
return liquibase;
}
/**
* 配置主应用程序的Liquibase实例
* 负责执行 main.xml 中的迁移
* @param dataSource 应用程序的数据源
* @return 配置好的 SpringLiquibase 实例
*/
@Bean
@DependsOn("liquibaseLib") // 如果主应用的迁移依赖于库的迁移，则使用 @DependsOn
public SpringLiquibase liquibaseMain(DataSource dataSource) {
SpringLiquibase liquibase = new SpringLiquibase();
liquibase.setDataSource(dataSource);
liquibase.setChangeLog("classpath:main.xml"); // 指定主应用的 changelog 文件
// 可以根据需要设置其他属性
return liquibase;
}
}3.2 注意事项
- @Configuration: 确保你的配置类被Spring Boot应用扫描到。
- DataSource: 两个SpringLiquibase Bean都注入了同一个DataSource，这意味着它们将对同一个数据库执行迁移。如果需要对不同的数据库或不同的模式执行迁移，则需要注入或创建不同的DataSource实例。
- changeLog路径: 使用classpath:前缀确保Liquibase能够从类路径中找到changelog文件。library.xml应位于外部库的src/main/resources目录下，main.xml应位于主应用程序的src/main/resources目录下。
- 执行顺序: 如果外部库的数据库迁移必须在主应用程序的迁移之前执行（例如，主应用程序的表依赖于外部库创建的表），可以使用@DependsOn("liquibaseLib")注解来强制liquibaseMain Bean在liquibaseLib Bean之后初始化。
4. 方案二：利用@ConfigurationProperties进行高级多Liquibase配置
这种方案更加灵活，它允许你通过application.properties或application.yml文件来配置多个Liquibase实例的属性，类似于Spring Boot对默认Liquibase的自动配置方式。这在需要外部化配置或有多个模块需要独立配置Liquibase时非常有用。
4.1 属性配置 (application.properties)
在主项目的application.properties中，为每个Liquibase实例定义独立的属性前缀：
# 主应用程序的Liquibase配置 (通常由 spring.liquibase 自动配置) spring.liquibase.change-log=classpath:/main.xml spring.liquibase.enabled=true # ... 其他 spring.liquibase.* 属性 # 外部库的Liquibase配置，使用自定义前缀 'lib.liquibase' lib.liquibase.change-log=classpath:/library.xml lib.liquibase.enabled=true # ... 其他 lib.liquibase.* 属性
4.2 Java配置类
在主应用程序的启动类或一个配置类中，手动创建SpringLiquibase Bean，并使用@ConfigurationProperties绑定到对应的属性前缀：
package com.example.app; // 假设这是你的主应用包
import liquibase.integration.spring.SpringLiquibase;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.liquibase.LiquibaseAutoConfiguration.LiquibaseConfiguration;
import org.springframework.boot.autoconfigure.liquibase.LiquibaseDataSource;
import org.springframework.boot.autoconfigure.liquibase.LiquibaseProperties;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.DependsOn;
import javax.sql.DataSource;
@SpringBootApplication
// 启用对 LiquibaseProperties 的配置属性绑定，允许我们创建多个实例
@EnableConfigurationProperties(LiquibaseProperties.class)
public class DemoApplication { // 可以是你的主启动类或任何 @Configuration 类
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
/**
* 创建并配置主应用程序的Liquibase实例。
* 绑定到 'spring.liquibase' 前缀的属性。
*
* @param dataSource 主数据源
* @param liquibaseDataSource 特定于Liquibase的数据源 (如果定义)
* @param properties 绑定到 'spring.liquibase' 的 LiquibaseProperties
* @return 配置好的 SpringLiquibase 实例
*/
@Bean // "main" liquibase
// 如果需要，可以指定执行顺序：@DependsOn("liquibaseLib")
@ConfigurationProperties("spring.liquibase") // 绑定到 spring.liquibase.* 属性
public SpringLiquibase liquibaseMain(
ObjectProvider dataSource,
@LiquibaseDataSource ObjectProvider liquibaseDataSource,
LiquibaseProperties properties) {
// 使用 Spring Boot 内部的 LiquibaseConfiguration 辅助类来创建 SpringLiquibase 实例
// 这样可以复用 Spring Boot 自动配置的逻辑
LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);
return helper.liquibase(dataSource, liquibaseDataSource);
}
/**
* 创建并配置外部库的Liquibase实例。
* 绑定到 'lib.liquibase' 前缀的属性。
*
* @param dataSource 主数据源
* @param liquibaseDataSource 特定于Liquibase的数据源 (如果定义)
* @param properties 绑定到 'lib.liquibase' 的 LiquibaseProperties
* @return 配置好的 SpringLiquibase 实例
*/
@Bean // lib liquibase
@ConfigurationProperties("lib.liquibase") // 绑定到 lib.liquibase.* 属性
public SpringLiquibase liquibaseLib(
ObjectProvider dataSource,
@LiquibaseDataSource ObjectProvider liquibaseDataSource,
LiquibaseProperties properties) {
// 同上，使用辅助类
LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);
return helper.liquibase(dataSource, liquibaseDataSource);
}
} 4.3 注意事项
- @EnableConfigurationProperties(LiquibaseProperties.class): 这个注解是关键，它使得Spring能够识别并绑定LiquibaseProperties的多个实例。
- @ConfigurationProperties("prefix"): 每个SpringLiquibase Bean的创建方法都需要这个注解，以指定它应该从哪个属性前缀加载配置。
- LiquibaseAutoConfiguration.LiquibaseConfiguration: Spring Boot内部提供了一个LiquibaseConfiguration辅助类，它封装了从LiquibaseProperties创建SpringLiquibase实例的逻辑。直接使用它可以保持与Spring Boot自动配置行为的一致性。
-
ObjectProvider
: Spring Boot在自动配置时使用ObjectProvider来延迟和灵活地获取DataSource。这里也沿用了这种模式。@LiquibaseDataSource可以用于指定特定的数据源，如果你的应用有多个数据源。 - 默认SpringLiquibase Bean: 如果你使用了@SpringBootApplication，Spring Boot默认会创建一个spring.liquibase前缀的SpringLiquibase Bean。通过我们手动定义liquibaseMain Bean并使用@ConfigurationProperties("spring.liquibase")，我们的自定义Bean会覆盖或替换默认的Bean，从而获得完全控制。
5. 总结与最佳实践
-
选择合适的方案:
- 简单方案 (方案一)：适用于配置相对固定、数量不多的Liquibase实例，且希望直接在代码中控制所有细节的场景。
- 高级方案 (方案二)：适用于需要高度外部化配置、Liquibase实例数量可能变化，或者希望与Spring Boot自动配置机制更紧密结合的场景。它提供了更大的灵活性，但配置略显复杂。
- changelog路径: 始终使用classpath:前缀来指定changelog文件，确保它们可以从JAR包或文件系统中正确加载。
- 执行顺序: 如果不同模块的数据库迁移之间存在依赖关系，务必使用@DependsOn注解来明确指定SpringLiquibase Bean的初始化顺序，以避免潜在的数据库模式不一致问题。
- 数据源管理: 确保所有Liquibase实例都指向正确的数据源。如果应用程序有多个数据源，需要根据业务需求为每个SpringLiquibase实例分配正确的数据源。
- 库中的spring.liquibase.change-log: 如果外部库在其自身的application.properties中定义了spring.liquibase.change-log，这通常是用于库的独立测试或演示。在主应用程序集成时，主应用程序的配置将覆盖或管理这些属性，因此库中的该属性通常不会直接影响主应用程序的运行时行为，除非你明确地去加载和使用它。
通过上述方法，你可以灵活地在Spring Boot应用中管理来自多个源（主项目和外部库）的Liquibase数据库迁移，确保数据库模式的正确性和一致性。
