Resilience4j fallback方法匹配失败求助：如何定义正确的fallback方法？

问题场景 #

使用Resilience4j的@Bulkhead、@TimeLimiter、@CircuitBreaker注解修饰异步方法时，触发异常后提示找不到匹配的fallback方法，错误日志如下：

fallback.FallbackExecutor  : No fallback method match found
java.lang.NoSuchMethodException: class java.util.concurrent.CompletableFuture class com.test.Connector.fallbackRequestException(class org.springframework.http.HttpHeaders,class java.lang.String,class java.lang.Throwable)
        at io.github.resilience4j.spring6.fallback.FallbackMethod.create(FallbackMethod.java:93) ~[resilience4j-spring6-2.1.0.jar!/:2.1.0]

核心问题 #

1. 原方法返回值声明错误：异步方法标注@TimeLimiter后必须返回CompletableFuture类型，但原方法声明为ResponseEntity<Resources>，导致代理逻辑无法识别正确的返回类型
2. Fallback方法返回值不匹配：原方法实际返回CompletableFuture，但fallback直接返回ResponseEntity，类型不兼容

修正方案 #

1. 修正原方法的返回值声明 #

原方法的返回值必须明确为CompletableFuture<ResponseEntity<Resources>>，同时补全lambda表达式的返回语句：

@Bulkhead(name = "getToken", type = Bulkhead.Type.THREADPOOL)
@TimeLimiter(name = "getToken")
@CircuitBreaker(name = "getToken", fallbackMethod = "fallbackRequestException")
public CompletableFuture<ResponseEntity<Resources>> getByTokenPayload(HttpHeaders headers, String url) {
    return CompletableFuture.supplyAsync(() -> {
        ResponseEntity<Resources> result = service.getByTokenResource(headers, url);
        return result; // 补全返回语句
    }).thenApply(result -> result);
}

2. 调整Fallback方法的返回值与参数 #

Fallback方法必须返回和原方法一致的CompletableFuture类型，参数列表需与原方法参数完全匹配，最后追加Throwable参数接收异常：

private CompletableFuture<ResponseEntity<?>> fallbackRequestException(HttpHeaders headers, String url, Throwable e) throws BadRequestException {
    // 使用CompletableFuture.completedFuture包装响应结果
    return CompletableFuture.completedFuture(
        ResponseEntity.status(HttpStatus.OK).body("Fallback response")
    );
}

关键注意点 #

• 异步方法搭配@TimeLimiter时，返回值必须是CompletableFuture，否则Resilience4j的代理逻辑无法正确处理
• Fallback方法的返回值类型必须与原方法的返回值类型完全一致（包括泛型）
• Fallback方法的参数需包含原方法的所有参数，最后必须添加Throwable类型的参数用于接收触发降级的异常
• Fallback方法的访问修饰符建议使用protected或public，避免Spring代理无法访问（若为private需确保类内部可访问）

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