Spring Boot中集成多Liquibase变更日志：外部库与主项目共存策略

本文探讨在Spring Boot应用中，如何有效管理来自主项目和外部库的多个Liquibase变更日志。通过配置多个SpringLiquibase Bean，利用Spring的依赖注入和属性绑定机制，实现各自独立或按序执行变更日志，确保数据库迁移的灵活性与可控性，尤其适用于包含共享组件的复杂项目结构。

引言

在复杂的Spring Boot应用中，项目结构可能包含主应用模块以及作为依赖引入的外部共享库。当主应用和外部库都使用Liquibase进行数据库版本管理时，如何确保两者的变更日志（例如main.xml和library.xml）都能被正确识别并执行，是一个常见的挑战。Spring Boot的自动配置通常只处理一个默认的SpringLiquibase实例，这不足以满足多变更日志的需求。本文将详细介绍两种有效策略，通过定义多个SpringLiquibase Bean来解决这一问题。

核心策略：定义多个SpringLiquibase Bean

Spring Boot在检测到Liquibase相关依赖时，会自动配置一个SpringLiquibase Bean来执行由spring.liquibase.change-log属性指定的变更日志。然而，当我们需要同时执行多个独立的变更日志文件时（例如，一个来自主应用，另一个来自外部库），就需要绕过或扩展Spring Boot的默认行为。核心思想是手动定义多个SpringLiquibase Bean，每个Bean负责一个特定的变更日志文件。

方法一：手动配置SpringLiquibase Bean（简洁方案）

这是最直接的解决方案，适用于变更日志路径相对固定且无需复杂属性配置的场景。我们可以在主项目的配置类中定义多个SpringLiquibase Bean，每个Bean都指向一个特定的变更日志文件。

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变更日志
     * @param dataSource 数据库数据源
     * @return SpringLiquibase 实例
     */
    @Bean
    public SpringLiquibase liquibaseLib(DataSource dataSource) {
        SpringLiquibase liquibase = new SpringLiquibase();
        liquibase.setDataSource(dataSource);
        liquibase.setChangeLog("classpath:library.xml"); // 指定外部库的变更日志路径
        return liquibase;
    }

    /**
     * 配置主项目的Liquibase变更日志
     * 当需要确保外部库的变更日志先于主项目执行时，可使用 @DependsOn
     * @param dataSource 数据库数据源
     * @return SpringLiquibase 实例
     */
    @Bean
    @DependsOn("liquibaseLib") // 确保 'liquibaseLib' 先执行
    public SpringLiquibase liquibaseMain(DataSource dataSource) {
        SpringLiquibase liquibase = new SpringLiquibase();
        liquibase.setDataSource(dataSource);
        liquibase.setChangeLog("classpath:main.xml"); // 指定主项目的变更日志路径
        return liquibase;
    }
}

说明：

• @Configuration：标记这是一个Spring配置类。
• @Bean：为每个变更日志文件定义一个SpringLiquibase Bean。
• setDataSource(dataSource)：将应用的数据源注入到每个SpringLiquibase实例中。
• setChangeLog("classpath:...")：明确指定每个Bean要执行的变更日志文件路径。
• @DependsOn("liquibaseLib")：如果主项目的变更日志依赖于外部库的表结构，可以使用@DependsOn注解来控制Bean的创建顺序，从而确保liquibaseLib先于liquibaseMain执行。

这种方法简单直观，但其缺点是变更日志路径是硬编码在代码中的，如果需要频繁更改或根据环境动态调整，则不够灵活。

方法二：利用@ConfigurationProperties实现高级配置（Spring Boot推荐）

为了更好地利用Spring Boot的外部化配置能力，我们可以结合@ConfigurationProperties来为每个SpringLiquibase Bean绑定独立的配置属性。这种方法更加灵活，推荐用于生产环境。

首先，在主项目的application.properties或application.yml中为每个Liquibase实例定义独立的配置前缀：

# 主项目 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.* 属性

接着，在主项目的配置类中，定义两个SpringLiquibase Bean，并分别使用不同的@ConfigurationProperties前缀进行绑定：

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;
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 DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    /**
     * 配置主项目的 Liquibase 实例
     * 绑定 'spring.liquibase' 前缀的属性
     */
    @Bean("liquibaseMain") // 
明确指定 Bean 名称
    @ConfigurationProperties("spring.liquibase") // 绑定 spring.liquibase.* 属性
    public SpringLiquibase liquibaseMain(
            ObjectProvider dataSource,
            @LiquibaseDataSource ObjectProvider liquibaseDataSource,
            LiquibaseProperties properties) { // 注入默认的 LiquibaseProperties
        // 使用 LiquibaseConfiguration 辅助类来创建 SpringLiquibase 实例
        // 避免重复的配置逻辑
        LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);
        return helper.liquibase(dataSource, liquibaseDataSource);
    }

    /**
     * 配置外部库的 Liquibase 实例
     * 绑定 'lib.liquibase' 前缀的属性
     * 同样可以使用 @DependsOn("liquibaseMain") 如果需要确保主项目变更日志先执行
     */
    @Bean("liquibaseLib") // 明确指定 Bean 名称
    @DependsOn("liquibaseMain") // 假设外部库依赖于主项目，确保主项目先执行
    @ConfigurationProperties("lib.liquibase") // 绑定 lib.liquibase.* 属性
    public SpringLiquibase liquibaseLib(
            ObjectProvider dataSource,
            @LiquibaseDataSource ObjectProvider liquibaseDataSource,
            LiquibaseProperties properties) { // 注入默认的 LiquibaseProperties
        // 同样使用 LiquibaseConfiguration 辅助类
        LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);
        return helper.liquibase(dataSource, liquibaseDataSource);
    }
}

说明：

• @EnableConfigurationProperties(LiquibaseProperties.class)：确保LiquibaseProperties类可以被Spring Boot的属性绑定机制使用。
• @ConfigurationProperties("spring.liquibase") 和 @ConfigurationProperties("lib.liquibase")：这两个注解分别将application.properties中以spring.liquibase和lib.liquibase开头的属性绑定到对应的SpringLiquibase Bean上。
• LiquibaseConfiguration helper = new LiquibaseConfiguration(properties);：这里利用了Spring Boot自动配置内部使用的LiquibaseConfiguration工具类。它是一个非Bean的工厂类，可以根据LiquibaseProperties对象和数据源来创建SpringLiquibase实例，避免了手动设置所有属性的繁琐。
• ObjectProvider 和 @LiquibaseDataSource ObjectProvider：这是Spring Boot处理数据源注入的推荐方式，ObjectProvider提供了更灵活的查找机制，而@LiquibaseDataSource则用于区分特定的Liquibase数据源（如果配置了多个数据源）。
• @DependsOn("liquibaseMain")：在这里，我们假设外部库的变更日志可能依赖于主项目的变更日志，因此设置liquibaseLib在liquibaseMain之后执行。实际应用中，请根据具体依赖关系调整。

关键注意事项

1. 变更日志执行顺序：
   • 如果不同的变更日志之间存在表结构依赖，务必使用@DependsOn注解来明确指定它们的执行顺序。例如，如果library.xml创建的表被main.xml引用，那么liquibaseLib应该先于liquibaseMain执行。
2. 数据源管理：
   • 确保所有SpringLiquibase Bean都绑定到正确的DataSource。在大多数单数据源应用中，直接注入DataSource即可。如果应用配置了多个数据源，需要使用@Qualifier或其他机制来指定正确的数据源。
3. 外部库的Liquibase配置：
   • 外部库本身不应依赖于其内部的spring.liquibase.change-log属性来自动执行变更日志。最佳实践是，外部库只提供library.xml文件，而由主应用负责加载和执行它。这样可以避免外部库在被不同主应用集成时产生冲突或不必要的数据库操作。库中的spring.liquibase.change-log属性通常只用于库的测试。
4. Liquibase include机制的对比：
   • Liquibase本身提供了include或includeAll机制，可以在一个主变更日志文件中引用其他变更日志文件。例如，在main.xml中包含library.xml。这种方法适用于将多个逻辑相关的变更日志合并为一个整体。
   • 然而，本文介绍的“多个SpringLiquibase Bean”方法，更适用于处理独立的、可能由不同模块或团队维护的变更日志集，它们可能需要独立配置或在不同的生命周期阶段执行。它提供了更细粒度的控制。

总结

在Spring Boot应用中管理来自不同来源（主项目和外部库）的多个Liquibase变更日志，可以通过定义多个SpringLiquibase Bean来实现。简洁方案适用于固定路径的场景，而利用@ConfigurationProperties的高级方案则提供了更强大的外部化配置能力和灵活性，是更推荐的做法。通过合理配置，并注意变更日志的执行顺序和数据源管理，可以确保数据库迁移的顺畅和项目的可维护性。