使用Liquibase生成迁移时@MapsId导致classMapping空指针问题求助

问题重现 #

我有一个MasterSegment实体，使用复合主键关联BkrApplication实体，不使用Liquibase时表生成正常，运行无问题：

public class MasterSegment extends Auditable {

    @EmbeddedId
    private MasterSegmentId id;
    @OneToOne
    @MapsId("appId")
    private BkrApplication app;
    // getters setters omitted
}

@Embeddable
public class MasterSegmentId implements Serializable {
    @Column
    private String name;
    @Column(name = "app_id", nullable = false)
    private Long appId;
    // getters setters omitted
}

执行mvn clean install liquibase:diff生成迁移脚本时，报错：

Cannot invoke "org.hibernate.mapping.PersistentClass.getTable()" because "classMapping" is null

排查后确认是@MapsId注解导致该问题，但移除注解会引发映射异常。

可行解决方案 #

方案1：明确Liquibase的Hibernate配置参数 #

Liquibase的diff功能依赖Hibernate元数据解析，部分版本对@MapsId复合主键的支持存在缺陷，可在插件配置中明确指定Hibernate相关参数，确保元数据正确加载：

在pom.xml的liquibase插件配置里补充以下内容：

<plugin>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-maven-plugin</artifactId>
    <version>你的Liquibase版本</version>
    <configuration>
        <propertyFile>src/main/resources/liquibase.properties</propertyFile>
        <diffChangeLogFile>src/main/resources/db/changelog/changelog-diff.xml</diffChangeLogFile>
        <!-- 替换为你的数据库信息和实体包 -->
        <driver>com.mysql.cj.jdbc.Driver</driver>
        <url>jdbc:mysql://localhost:3306/你的数据库名</url>
        <username>数据库用户名</username>
        <password>数据库密码</password>
        <referenceUrl>hibernate:spring:你的实体根包名?dialect=org.hibernate.dialect.MySQL8Dialect</referenceUrl>
    </configuration>
    <dependencies>
        <!-- 添加与项目版本一致的Hibernate核心依赖 -->
        <dependency>
            <groupId>org.hibernate</groupId>
            <artifactId>hibernate-core</artifactId>
            <version>你的Hibernate版本</version>
        </dependency>
    </dependencies>
</plugin>

方案2：给@OneToOne显式添加关联列配置 #

保留@MapsId的同时，给@OneToOne注解补充@JoinColumn，帮助Liquibase正确识别关联关系：

public class MasterSegment extends Auditable {

    @EmbeddedId
    private MasterSegmentId id;
    @OneToOne
    @MapsId("appId")
    @JoinColumn(name = "app_id", referencedColumnName = "id", insertable = false, updatable = false)
    private BkrApplication app;
    // getters setters omitted
}

这里的insertable=false, updatable=false是因为app_id由嵌入式主键管理，避免重复操作字段导致冲突。

方案3：升级Liquibase和Hibernate版本 #

旧版本的Liquibase（如4.x早期版本）对Hibernate@MapsId复合主键的支持不完善，建议升级到稳定的新版本：

• Liquibase：推荐升级至4.20+版本
• Hibernate：使用5.6+或6.x的稳定版本，确保与Liquibase版本兼容

方案4：手动生成初始脚本，后续用增量更新 #

如果上述方案无效，可先手动生成初始表结构的迁移脚本，后续变更再用liquibase:diff生成增量：

1. 启动应用让Hibernate自动生成数据库表
2. 执行liquibase:generateChangeLog生成全量初始脚本
3. 后续的结构变更再使用liquibase:diff生成增量脚本

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