如何引用JAR依赖包内的Liquibase changelog文件？

一、独立changelog模块的打包配置 #

首先要保证拆分出来的changelog模块，所有changelog文件都放在标准Maven资源目录下，否则打包时不会被纳入JAR：

• 所有xml、sql、yaml/json格式的changelog文件，统一放到src/main/resources目录下，建议按版本建子目录分类，参考结构：

your-liquibase-module
└── src
    └── main
        └── resources
            └── db
                └── changelog
                    ├── master.xml # 主changelog入口
                    ├── v1
                    │   ├── init-schema.xml
                    │   └── init-data.sql
                    └── v2
                        └── add-business-column.xml

• 如果模块自定义过资源打包规则，在pom.xml中显式包含changelog格式文件，避免资源被过滤掉：

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.xml</include>
                <include>**/*.sql</include>
                <include>**/*.yaml</include>
                <include>**/*.json</include>
            </includes>
        </resource>
    </resources>
</build>

• 模块执行mvn install安装到本地仓库后，建议解压对应JAR包校验，确认changelog文件的路径层级和resources下完全一致，没有多嵌套或者缺失。

二、业务模块引用JAR内changelog的配置 #

所有引用都必须通过classpath路径寻址，不要写文件系统相对路径，类加载器无法识别JAR内部的相对路径跳转。

1. Spring Boot自动配置场景 #

直接在配置文件中指定主changelog的classpath全路径即可：

spring:
  liquibase:
    enabled: true
    change-log: classpath:db/changelog/master.xml

2. 原生Spring手动配置Liquibase场景 #

定义SpringLiquibase Bean时指定classpath路径：

@Bean
public SpringLiquibase liquibase(DataSource dataSource) {
    SpringLiquibase liquibase = new SpringLiquibase();
    liquibase.setDataSource(dataSource);
    liquibase.setChangeLog("classpath:db/changelog/master.xml");
    return liquibase;
}

3. 跨JAR引用changelog片段场景 #

如果业务模块自身有changelog，需要include独立JAR中的changelog片段，在changelog文件中按如下格式编写：

<databaseChangeLog
        xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.20.xsd">
    <!-- 单文件引用，加classpath前缀 -->
    <include file="classpath:db/changelog/v1/init-schema.xml"/>
    <include file="classpath:db/changelog/v1/init-data.sql"/>
    <!-- 批量扫描目录下所有changelog，用classpath*:前缀匹配所有依赖JAR内的路径 -->
    <includeAll path="classpath*:db/changelog/v2/"/>
</databaseChangeLog>

三、常见踩坑点 #

• 路径必须从classpath根目录写全：比如文件在resources/db/changelog/a.xml，路径就写classpath:db/changelog/a.xml，不要写../changelog/a.xml这类相对路径
• 不要漏写classpath:前缀：漏写的话Liquibase只会从当前业务模块的resources目录找文件，不会遍历依赖JAR，必然报文件不存在
• changeSet唯一标识校验：所有changelog里的changeSet要保证id+author全局唯一，避免跨JAR重复导致执行报错
• Spring Boot胖JAR打包无需额外配置：官方插件默认会把所有依赖JAR的资源加入classpath，不需要额外做shade配置或者资源导出

内容的提问来源于stack exchange，提问作者jamesanthony