本文将详细介绍 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<T> 时，即使服务器返回错误状态码，也不会直接抛出 HttpClientResponseException。
要使声明式客户端在错误状态码时抛出异常，需要将接口方法的返回类型改为 HttpResponse<T>。例如：
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<AuthorResource> getAuthor(Long id, @Header(name = "Authorization") String authorization); }
在这种情况下，如果服务器返回错误状态码，客户端将返回一个包含错误信息的 HttpResponse<AuthorResource> 对象，而不会抛出异常。开发者需要检查 HttpResponse 的状态码，并根据需要手动处理错误。
测试用例
以下是一个测试用例，展示了如何使用 HttpResponse<T> 来处理声明式客户端的异常：
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<AuthorResource> 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<T> 来处理。
总结
在 Micronaut 声明式客户端中，exceptionOnErrorStatus 配置项的作用是控制是否抛出 HttpClientResponseException。要使声明式客户端在错误状态码时能够正确处理异常，需要将接口方法的返回类型改为 HttpResponse<T>，并手动检查 HttpResponse 的状态码。理解声明式客户端与低级别客户端的差异，可以帮助开发者更好地使用 Micronaut 的 HTTP 客户端功能。
