SpringBoot3整合Resilience4j时Fallback方法不生效问题求助

一、依赖配置（Pom.xml）排查 #

• 确认引入适配SpringBoot3的Resilience4j依赖，需使用resilience4j-spring-boot3而非旧版resilience4j-spring-boot2，同时要包含对应功能的依赖（如使用断路器需引入resilience4j-circuitbreaker）。
• 检查是否存在spring-boot-starter-aop依赖，Resilience4j基于Spring AOP实现切面增强，缺少该依赖会导致注解完全不生效。
• 验证版本兼容性：Resilience4j 2.0+版本适配SpringBoot3，避免版本不匹配引发的隐性问题。

二、配置文件（Application.properties）排查 #

• 确保Resilience4j组件的实例配置与代码中指定的名称一致，例如代码中@CircuitBreaker(name = "userService")，配置需对应resilience4j.circuitbreaker.instances.userService.xxx=xxx，名称大小写、拼写必须完全匹配。
• 检查核心配置是否生效：比如断路器的失败率阈值（failure-rate-threshold）、开路等待时长（wait-duration-in-open-state）等，若配置错误可能导致断路器无法进入开路状态，fallback自然不会触发。
• 确认未禁用Resilience4j自动配置，SpringBoot3默认开启自动配置，若自定义配置需确保未添加@EnableAutoConfiguration(exclude = ...)排除相关类。

三、业务服务类（Service.java）排查 #

• Fallback方法签名必须严格匹配：返回值、参数列表需与原方法完全一致，且额外添加一个Throwable类型的参数（CircuitBreaker fallback要求）。例如原方法public String queryUser(String userId)，fallback需定义为public String queryUserFallback(String userId, Throwable e)。
• Fallback方法的访问修饰符需为public或protected，不能是private，否则无法被切面调用。
• 注解参数配置正确：@CircuitBreaker的fallbackMethod属性值需精准匹配fallback方法名，大小写、拼写不能出错；若使用其他组件（如Retry），需对应配置fallbackMethod。
• 原方法不能捕获所有异常：若原方法内部用try-catch吞掉了所有异常，Resilience4j无法感知调用失败，不会触发fallback，需确保异常能抛出到切面逻辑中。

四、控制器（Controller.java）排查 #

• 必须通过Spring代理对象调用Service方法：禁止在Service内部自调用注解修饰的方法（Spring AOP仅对外部调用生效），Controller需注入Spring管理的Service Bean，而非自行new对象（new的对象无代理增强）。

五、日志排查 #

• 将io.github.resilience4j包的日志级别调整为DEBUG，查看断路器状态变化、失败次数统计、fallback调用日志，直接定位是否触发了断路器逻辑，或fallback是否被执行。

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