如何处理Quarkus异步Rest Client的UnknownHostException？

问题根源 #

你遇到的核心问题是：动态构建的Quarkus Rest Client在异步调用时，底层IO异常（如UnknownHostException、ConnectException）未被封装进Mutiny Uni的失败流，而是直接抛出导致测试失败。主要原因有两点：

1. 动态构建QuarkusRestClientBuilder时，未正确配置Mutiny异步组件和异常映射策略，导致底层IO异常逃逸出Uni上下文。
2. 客户端初始化或API调用逻辑未放在Uni的延迟执行上下文里，异常发生在Uni订阅前，无法被onFailure()捕获。

正确处理方案 #

1. 确保动态构建Rest Client时配置Mutiny异步组件

动态构建客户端时，必须注册Mutiny相关的过滤器，确保异步调用的异常被正确桥接到Uni流中：

MyClient myClient = QuarkusRestClientBuilder.newBuilder()
    .baseUri(URI.create("https://invalid-host.example.com"))
    .register(MutinyClientResponseFilter.class) // 关键：注册Mutiny异步支持组件
    .build(MyClient.class);

同时确保你的MyClient接口方法返回Uni类型：

@RegisterRestClient
public interface MyClient {
    @GET
    Uni<Response> callExternalApi();
}

2. 注册全局异常映射器统一处理IO异常

通过ClientExceptionMapper将底层IO异常转换为自定义异常，确保所有异常都能进入Uni的失败处理链：

public class RestClientExceptionMapper implements ClientExceptionMapper {
    @Override
    public RuntimeException toThrowable(Response response) {
        return new ExternalApiException("API调用失败，状态码: " + response.getStatus());
    }

    @Override
    public RuntimeException toThrowable(Throwable throwable) {
        // 捕获并转换IO异常
        if (throwable instanceof UnknownHostException) {
            return new ExternalApiUnreachableException("无法解析目标主机", throwable);
        } else if (throwable instanceof ConnectException) {
            return new ExternalApiUnreachableException("连接被拒绝", throwable);
        }
        return new ExternalApiException("外部API调用出错", throwable);
    }
}

动态构建客户端时注册该映射器：

MyClient myClient = QuarkusRestClientBuilder.newBuilder()
    .baseUri(URI.create("https://invalid-host.example.com"))
    .register(RestClientExceptionMapper.class)
    .register(MutinyClientResponseFilter.class)
    .build(MyClient.class);

3. 用Uni.deferred()延迟客户端创建与调用

如果客户端初始化或API调用可能在Uni订阅前抛出异常，使用Uni.createFrom().deferred()将逻辑包裹在Uni上下文里，确保异常被捕获：

public Uni<Response> callExternalApi() {
    return Uni.createFrom().deferred(() -> {
        // 延迟创建客户端，确保异常进入Uni失败流
        MyClient myClient = QuarkusRestClientBuilder.newBuilder()
            .baseUri(URI.create("https://invalid-host.example.com"))
            .register(RestClientExceptionMapper.class)
            .build(MyClient.class);
        return myClient.callExternalApi();
    }).onFailure().transform(t -> {
        // 这里可以捕获所有异常并转换
        if (t instanceof ExternalApiUnreachableException) {
            return new ServiceUnavailableException("外部服务不可用", t);
        }
        return new ServiceException("服务调用失败", t);
    });
}

4. 修正JUnit测试的订阅方式

测试时必须通过await()订阅Uni并等待结果，不能直接调用方法（否则异常会直接抛出）：

@QuarkusTest
public class MyServiceTest {
    @Inject
    MyService myService;

    @Test
    public void testInvalidHostCall() {
        Uni<Response> result = myService.callExternalApi();
        result.onFailure().invoke(t -> {
            assertThat(t).isInstanceOf(ServiceUnavailableException.class);
        }).await().atMost(Duration.ofSeconds(5));
    }
}

总结问题点 #

1. 动态构建Rest Client时未注册Mutiny异步组件，导致IO异常未被封装进Uni。
2. 客户端初始化或API调用逻辑未放在deferred()中，异常发生在Uni订阅前直接逃逸。
3. 测试未正确订阅Uni，未通过await()等待结果，导致异常直接抛出。

内容的提问来源于stack exchange，提问作者Joost den Boer