Spring Boot集成Liquibase遇循环依赖错误求解决方案

问题现象 #

集成Liquibase后项目启动失败，核心报错为liquibase与entityManagerFactory存在循环依赖：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'liquibase' defined in class path resource [org/springframework/boot/autoconfigure/liquibase/LiquibaseAutoConfiguration$LiquibaseConfiguration.class]: Circular depends-on relationship between 'liquibase' and 'entityManagerFactory'
    at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:307) ~[spring-beans-6.1.4.jar:6.1.4]
    at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:199) ~[spring-beans-6.1.4.jar:6.1.4]
    at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:312) ~[spring-beans-6.1.4.jar:6.1.4]
    at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:199) ~[spring-beans-6.1.4.jar:6.1.4]
    at org.springframework.context.support.AbstractApplicationContext.getBean(AbstractApplicationContext.java:1231) ~[spring-context-6.1.4.jar:6.1.4]
    at org.springframework.context.support.AbstractApplicationContext.finishBeanFactoryInitialization(AbstractApplicationContext.java:949) ~[spring-context-6.1.4.jar:6.1.4]
    at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:624) ~[spring-context-6.1.4.jar:6.1.4]
    at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:146) ~[spring-boot-3.2.3.jar:3.2.3]
    at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:754) ~[spring-boot-3.2.3.jar:3.2.3]
    at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:456) ~[spring-boot-3.2.3.jar:3.2.3]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:334) ~[spring-boot-3.2.3.jar:3.2.3]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1354) ~[spring-boot-3.2.3.jar:3.2.3]
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1343) ~[spring-boot-3.2.3.jar:3.2.3]
    at com.dife.api.DifeApplication.main(DifeApplication.java:12) ~[main/:na]
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:na]
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77) ~[na:na]
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:na]
    at java.base/java.lang.reflect.Method.invoke(Method.java:568) ~[na:na]
    at org.springframework.boot.devtools.restart.RestartLauncher.run(RestartLauncher.java:50) ~[spring-boot-devtools-3.2.3.jar:3.2.3]

当前配置 #

application.yml 核心配置 #

spring:
    jpa:
        database-platform: org.hibernate.dialect.MySQLDialect
        show-sql: true
        hibernate:
            ddl-auto: update
        defer-datasource-initialization: false

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

    main:
        allow-circular-references: true

    sql:
        init:
          mode: always
          data-locations: classpath:import.sql

... 已配置数据源

Liquibase changelog 配置文件（resources/db/changelog/changelog-master.xml） #

<?xml version="1.0" encoding="UTF-8"?>
<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-latest.xsd">

    <changeSet id="1" author="my_name">
    </changeSet>

</databaseChangeLog>

Gradle 依赖 #

implementation 'org.liquibase:liquibase-core'

已尝试的无效操作 #

• 删除数据库重新初始化
• 添加错误配置：spring.jpa.defer-datasource-initialization: false、spring.jpa.main.allow-circular-reference: true

错误原因 #

1. DDL管理冲突：同时启用了Liquibase的版本化变更管理和Hibernate的ddl-auto: update自动建表，两者启动时都需要抢占数据源初始化，导致循环依赖。
2. 配置位置错误：尝试添加的循环引用允许配置spring.jpa.main.allow-circular-reference: true无效，正确配置应在spring.main节点下。
3. 初始化顺序矛盾：Spring Boot自动配置中，Liquibase与EntityManagerFactory默认存在依赖关联，两种DDL管理方式同时存在时，这个关联会变成循环依赖。

解决办法 #

方案一：禁用Hibernate自动DDL（推荐） #

既然采用Liquibase管理数据库版本，应完全交由Liquibase负责表结构变更，修改application.yml：

spring:
    jpa:
        hibernate:
            ddl-auto: none

此方案从根源消除冲突，是数据库版本管理的规范做法。

方案二：调整初始化顺序（兼容旧场景） #

若必须保留ddl-auto: update，可强制Liquibase优先执行：

spring:
    liquibase:
        depends-on: "" # 解除Liquibase对EntityManagerFactory的依赖
    jpa:
        defer-datasource-initialization: true # 延迟JPA初始化，等待Liquibase执行完成

注意：此方案可能导致表结构不一致，仅临时兼容使用。

方案三：修正循环引用配置（临时绕过） #

若需临时绕过循环依赖检查，确保配置位置正确：

spring:
    main:
        allow-circular-references: true

此方案仅解决启动报错，未处理根源冲突，不推荐长期使用。

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