Micronaut 声明式客户端异常处理配置详解

本文将详细介绍 Micronaut 声明式客户端中 exceptionOnErrorStatus 配置项的使用方法，并解释其在不同场景下的行为差异。通过实例代码和测试用例，阐述了如何正确配置和处理声明式客户端的异常，避免常见的误解和错误，帮助开发者更好地理解和使用 Micronaut 的声明式客户端功能。

在使用 Micronaut 的声明式客户端时，开发者可能会遇到希望在 HTTP 状态码大于等于 400 时抛出异常的需求。exceptionOnErrorStatus 配置项似乎能够满足这个需求，但实际使用中可能存在一些误解。本文将深入探讨该配置项的行为，并提供正确的异常处理方法。

exceptionOnErrorStatus 的作用

exceptionOnErrorStatus 配置项用于控制当 HTTP 响应状态码表示错误（大于等于 400）时，客户端是否应该抛出 HttpClientResponseException 异常。默认情况下，该配置项的值为 false，即不抛出异常。

配置 exceptionOnErrorStatus

可以通过创建一个继承自 DefaultHttpClientConfiguration 的配置类来配置 exceptionOnErrorStatus。例如：

import io.micronaut.context.annotation.ConfigurationProperties;
import io.micronaut.http.client.DefaultHttpClientConfiguration;

@ConfigurationProperties("httpclient.api")
class ApiClientConfiguration extends DefaultHttpClientConfiguration {
    @Override
    public boolean isExceptionOnErrorStatus() {
        return true;
    }
}

然后，在声明式客户端接口中使用 @Client 注解指定该配置类：

import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Header;
import io.micronaut.http.client.annotation.Client;

@Client(value = "/", configuration = ApiClientConfiguration.class)
interface Api {
    @Get("/author/{id}")
    AuthorResource getAuthor(Long id, @Header(name="Authorization") String authorization);
}

声明式客户端的异常处理

需要注意的是，即使配置了 exceptionOnErrorStatus 为 true，声明式客户端的行为也可能与预期不同。当声明式客户端接口的方法返回类型不是 HttpResponse 时，即使服务器返回错误状态码，也不会直接抛出 HttpClientResponseException。

Play.ht

根据文本生成多种逼真的语音

下载

要使声明式客户端在错误状态码时抛出异常，需要将接口方法的返回类型改为 HttpResponse。例如：

import io.micronaut.http.HttpResponse;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Header;
import io.micronaut.http.client.annotation.Client;

@Client(value = "/", configuration = ApiClientConfiguration.class)
interface Api {
    @Get("/author/{id}")
    HttpResponse getAuthor(Long id, @Header(name = "Authorization") String authorization);
}

在这种情况下，如果服务器返回错误状态码，客户端将返回一个包含错误信息的 HttpResponse 对象，而不会抛出异常。开发者需要检查 HttpResponse 的状态码，并根据需要手动处理错误。

测试用例

以下是一个测试用例，展示了如何使用 HttpResponse 来处理声明式客户端的异常：

import io.micronaut.http.HttpResponse;
import io.micronaut.http.HttpStatus;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;

public class ApiClientTest {

    @Test
    void testGetAuthorNotFound() {
        // 假设 api 是声明式客户端的实例
        HttpResponse response = api.getAuthor(badId, bearerAuth(token));

        assertEquals(HttpStatus.NOT_FOUND, response.status());
        assertTrue(response.getBody(ErrorResponse.class).isPresent());
        response.getBody(ErrorResponse.class).ifPresent(error -> {
            assertEquals("Author with id " + badId + " not found.", error.getMessage());
        });
    }
}

与低级别客户端的差异

需要注意的是，声明式客户端的行为与低级别客户端（例如使用 HttpClient.toBlocking().exchange()）不同。低级别客户端在遇到错误状态码时会直接抛出 HttpClientResponseException，而声明式客户端则需要通过 HttpResponse 来处理。

总结

在 Micronaut 声明式客户端中，exceptionOnErrorStatus 配置项的作用是控制是否抛出 HttpClientResponseException。要使声明式客户端在错误状态码时能够正确处理异常，需要将接口方法的返回类型改为 HttpResponse，并手动检查 HttpResponse 的状态码。理解声明式客户端与低级别客户端的差异，可以帮助开发者更好地使用 Micronaut 的 HTTP 客户端功能。