挑战背景：多模块项目的Liquibase集成
在复杂的Spring Boot应用中，我们常常会引入外部库（如以JAR包形式存在的公共模块），这些库可能也需要通过Liquibase管理自己的数据库结构。当主项目和外部库都各自拥有独立的Liquibase changelog文件（例如main.xml和library.xml），并且主项目通过spring.liquibase.change-log=main.xml配置时，默认的Spring Boot自动配置机制只会执行主项目指定的changelog。外部库的changelog（即使其内部配置了spring.liquibase.change-log=library.xml，这通常是用于其独立测试或作为独立应用时的配置）并不会被主应用自动识别和执行。
为了解决这一问题，我们需要一种机制，让Spring Boot应用能够同时识别并执行来自不同模块的多个Liquibase changelog文件。
解决方案概述
主要有两种策略可以实现Liquibase的多changelog管理：
- Liquibase include机制： 这是Liquibase原生的功能，允许在一个主changelog文件中通过include标签引用其他changelog文件。这种方法简单直接，但可能不适用于外部库作为一个完全独立的模块，不希望其changelog被主项目直接“包含”的情况。
- Spring Boot中定义多个SpringLiquibase Bean： 这是更符合Spring Boot习惯的解决方案，通过在Spring容器中注册多个SpringLiquibase实例，每个实例负责一个独立的changelog文件。本文将重点介绍此方法。
方法一：通过定义多个SpringLiquibase Bean实现（简洁版）
这种方法适用于对Liquibase配置要求不那么复杂，或者希望直接控制每个SpringLiquibase实例的场景。你可以在主项目的配置类中手动创建并注册多个SpringLiquibase Bean。
示例代码：
package com.example.app;
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 Bean
* @param dataSource 数据库数据源
* @return 外部库的SpringLiquibase实例
*/
@Bean
public SpringLiquibase liquibaseLib(DataSource dataSource) {
SpringLiquibase liquibase = new SpringLiquibase();
liquibase.setDataSource(dataSource);
// 指定外部库的changelog文件路径
liquibase.setChangeLog("classpath:library.xml");
// 可以根据需要设置其他属性，如默认模式、上下文等
// liquibase.setDefaultSchema("lib_schema");
return liquibase;
}
/**
* 为主项目定义Liquibase Bean
* @param dataSource 数据库数据源
* @return 主项目的SpringLiquibase实例
*/
@Bean
// 如果外部库的迁移必须在主项目之前执行，可以使用@DependsOn
// @DependsOn("liquibaseLib")
public SpringLiquibase liquibaseMain(DataSource dataSource) {
SpringLiquibase liquibase = new SpringLiquibase();
liquibase.setDataSource(dataSource);
// 指定主项目的changelog文件路径
liquibase.setChangeLog("classpath:main.xml");
// 可以根据需要设置其他属性
return liquibase;
}
}关键点说明：
- @Configuration： 确保Spring能够发现并处理这个配置类。
- @Bean： 声明两个独立的SpringLiquibase实例，Spring容器会管理它们的生命周期。
- DataSource： 通过方法参数注入应用程序的数据源。这两个Bean将使用同一个数据源进行数据库迁移。
- setChangeLog()： 为每个SpringLiquibase实例明确指定其对应的changelog文件路径。classpath:前缀表示从类路径中查找。
- @DependsOn (可选)： 如果不同changelog之间存在严格的执行顺序依赖（例如，外部库创建的表必须在主项目使用之前存在），可以使用@DependsOn注解来强制指定Bean的初始化顺序。例如，@DependsOn("liquibaseLib")表示liquibaseMain Bean的初始化依赖于liquibaseLib Bean。
方法二：利用Spring Boot自动配置和@ConfigurationProperties（进阶版）
这种方法更加灵活和强大，它允许你利用Spring Boot的属性绑定机制，通过application.properties或application.yml来配置多个Liquibase实例，就像配置默认的Liquibase一样。
1. 配置属性 (application.properties)
在主项目的application.properties中，为每个Liquibase实例定义一组独立的配置属性前缀。
# 主项目的Liquibase配置 spring.liquibase.change-log=classpath:/main.xml # 可以继续配置其他spring.liquibase.*属性，如 # spring.liquibase.default-schema=public # spring.liquibase.drop-first=false # 外部库的Liquibase配置，使用自定义前缀 'lib.liquibase' lib.liquibase.change-log=classpath:/library.xml # 同样可以配置其他lib.liquibase.*属性，如 # lib.liquibase.default-schema=library_schema
2. 主配置类 (Demo.java)
在你的主应用类或任何一个@Configuration类中，定义两个SpringLiquibase Bean，并利用@ConfigurationProperties将不同前缀的属性绑定到对应的Liquibase配置对象上。
package com.example.app;
import javax.sql.DataSource;
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; // 注意：这是Spring Boot内部类，使用时需谨慎
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;
@SpringBootApplication
@EnableConfigurationProperties({LiquibaseProperties.class}) // 启用LiquibaseProperties的绑定
public class Demo {
public static void main(String[] args) {
SpringApplication.run(Demo.class, args);
}
/**
* 配置主项目的Liquibase Bean
* @param dataSourceProvider 数据源提供者
* @param liquibaseDataSourceProvider Liquibase专用的数据源提供者（如果有）
* @param properties 主项目的Liquibase属性
* @return 主项目的SpringLiquibase实例
*/
@Bean // "main" liquibase
// 如果外部库的迁移必须在主项目之前执行，可以使用@DependsOn
// @DependsOn("liquibaseLib")
@ConfigurationProperties("spring.liquibase") // 绑定以"spring.liquibase"为前缀的属性
public SpringLiquibase liquibase(
ObjectProvider dataSourceProvider,
@LiquibaseDataSource ObjectProvider liquibaseDataSourceProvider,
LiquibaseProperties properties) {
return createSpringLiquibase(dataSourceProvider, liquibaseDataSourceProvider, properties);
}
/**
* 配置外部库的Liquibase Bean
* @param dataSourceProvider 数据源提供者
* @param liquibaseDataSourceProvider Liquibase专用的数据源提供者（如果有）
* @param properties 外部库的Liquibase属性
* @return 外部库的SpringLiquibase实例
*/
@Bean // lib liquibase
@ConfigurationProperties("lib.liquibase") // 绑定以"lib.liquibase"为前缀的属性
public SpringLiquibase liquibaseLib(
ObjectProvider dataSourceProvider,
@LiquibaseDataSource ObjectProvider liquibaseDataSourceProvider,
LiquibaseProperties properties) {
return createSpringLiquibase(dataSourceProvider, liquibaseDataSourceProvider, properties);
}
/**
* 辅助方法，用于创建SpringLiquibase实例，复用Spring Boot的内部逻辑
* 注意：LiquibaseConfiguration是Spring Boot的内部类，其API可能随版本变化。
* 在生产环境，如果担心兼容性，可以考虑手动设置SpringLiquibase的属性。
*/
private SpringLiquibase createSpringLiquibase(ObjectProvider dataSourceProvider,
ObjectProvider liquibaseDataSourceProvider, LiquibaseProperties properties) {
// 这里的LiquibaseConfiguration是Spring Boot内部用于创建SpringLiquibase的工具类
// 它将LiquibaseProperties中的配置应用到SpringLiquibase实例上
LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);
return helper.liquibase(dataSourceProvider, liquibaseDataSourceProvider);
}
} 关键点说明：
- @EnableConfigurationProperties({LiquibaseProperties.class})： 显式启用LiquibaseProperties的配置绑定。
- @ConfigurationProperties("spring.liquibase") 和 @ConfigurationProperties("lib.liquibase")： 这是核心所在。它们分别将application.properties中以spring.liquibase和lib.liquibase为前缀的属性绑定到两个独立的LiquibaseProperties对象上。
-
createSpringLiquibase 辅助方法： 这个方法封装了创建SpringLiquibase实例的逻辑。它利用了Spring Boot内部的LiquibaseConfiguration类（这是一个方便的工具类，用于将LiquibaseProperties的配置应用到SpringLiquibase实例上），避免了手动逐一设置属性的繁琐。
- 注意： LiquibaseAutoConfiguration.LiquibaseConfiguration是一个Spring Boot内部类。虽然它在这里被用于复用Spring Boot的内部逻辑，但使用内部API可能存在未来版本不兼容的风险。如果对兼容性有严格要求，可以考虑在createSpringLiquibase方法中，根据传入的LiquibaseProperties对象，手动设置SpringLiquibase实例的各个属性（如setChangeLog、setDefaultSchema等）。
-
ObjectProvider
和 @LiquibaseDataSource： Spring Boot在自动配置时会注入这些对象，以处理可能存在的多个数据源或特定Liquibase数据源的情况。
Liquibase include 机制（补充说明）
Liquibase自身提供了一个include标签，可以在一个changelog文件中引用另一个changelog文件。如果你希望将外部库的changelog视为主项目changelog的一部分，这会是一个非常简洁的方法。
示例：main.xml
优点： 配置简单，只需修改一个changelog文件。 局限性： 这种方式将外部库的changelog视为子模块，失去了其独立性。如果外部库的changelog需要独立管理其上下文、默认模式等，或者你希望它们作为完全独立的迁移流运行，那么定义多个SpringLiquibase Bean会是更好的选择。
总结与最佳实践
-
选择合适的方案：
- 如果外部库的changelog可以被视为你主项目changelog的组成部分，且不强调其独立性，使用Liquibase include机制是最简单的。
- 如果需要独立控制每个changelog的执行（例如，不同的上下文、不同的默认模式、独立的属性配置），或者希望外部库的changelog保持其模块的独立性，那么定义多个SpringLiquibase Bean是更优的选择。
- 简洁版的多个SpringLiquibase Bean适用于快速实现，配置直观。
- 进阶版的多个SpringLiquibase Bean结合@ConfigurationProperties，提供了更强大的配置能力和Spring Boot风格的集成，但代码相对复杂一些，且需注意内部API的使用。
- 执行顺序： 当存在多个SpringLiquibase Bean时，如果changelog之间有依赖关系，务必使用@DependsOn来控制它们的执行顺序。
- 外部库的spring.liquibase.change-log： 外部库中可能包含自己的application.properties或application.yml，其中配置了spring.liquibase.change-log。这通常是为该库在独立测试或作为独立应用时准备的。在主项目中集成时，主项目定义的多个SpringLiquibase Bean会接管Liquibase的执行，库内部的这些属性通常不会生效，除非你特别配置Spring Boot去加载和使用它们。
- Changelog路径： 确保changelog文件（如library.xml和main.xml）位于类路径中，以便Liquibase能够找到它们。通常，它们会放在src/main/resources目录下。
通过上述方法，你可以灵活地在Spring Boot应用中管理和执行来自不同模块的Liquibase数据库迁移，确保所有数据库变更都能被正确应用。
