Spring 6.1中的新功能：RestClient[译]
📅 2023-07-13 | 🖱️
Spring Framework 6.1 M2引入了RestClient，这是一个新的同步HTTP客户端。正如名称所示，RestClient提供了WebClient的fluent API，并结合了RestTemplate的基础设施。
十四年前，在Spring Framework 3.0中引入RestTemplate时，我们很快发现，在一个类似模板的类中公开HTTP的每个能力会导致方法过多。因此，在Spring Framework 5中，我们为响应式的WebClient使用了的fluent API。通过RestClient，我们引入了一个类似于WebClient的HTTP客户端，它使用RestTemplate的消息转换器、请求工厂、拦截器和其他底层组件。
创建一个RestClient #
可以使用其中一个静态的create方法创建一个RestClient。也可以使用RestClient::builder获取一个带有进一步选项的构建器，例如指定要使用的HTTP客户端、设置默认的URL、路径变量和请求头，或者注册拦截器和初始化程序(initializers)。
使用RestClient::create(RestTemplate)，您可以使用现有RestTemplate的配置来初始化一个RestClient。
Retrieve #
让我们创建一个RestClient，使用它来设置一个基本的GET请求，并使用retrieve方法将网站的内容作为字符串检索出来：
1RestClient restClient = RestClient.create();
2
3String result = restClient.get()
4 .uri("https://example.com")
5 .retrieve()
6 .body(String.class);
7System.out.println(result);
如果您对响应状态码和响应头信息感兴趣，而不仅仅是内容，您可以使用toEntity方法来获取一个ResponseEntity对象：
1ResponseEntity<String> result = restClient.get()
2 .uri("https://example.com")
3 .retrieve()
4 .toEntity(String.class);
5
6System.out.println("Response status: " + result.getStatusCode());
7System.out.println("Response headers: " + result.getHeaders());
8System.out.println("Contents: " + result.getBody());
RestClient还可以使用Jackson在后台将JSON转换为对象。事实上，它可以转换RestTemplate支持的所有类型，因为它使用相同的消息转换器。请注意URI变量的使用，并且将Accept请求设置为JSON。
1int id = ...
2Pet pet = restClient.get()
3 .uri("https://petclinic.example.com/pets/{id}", id)
4 .accept(APPLICATION_JSON)
5 .retrieve()
6 .body(Pet.class);
Post #
进行POST请求同样简单，可以像这样操作：
1Pet pet = ...
2ResponseEntity<Void> response = restClient.post()
3 .uri("https://petclinic.example.com/pets/new")
4 .contentType(APPLICATION_JSON)
5 .body(pet)
6 .retrieve()
7 .toBodilessEntity();
错误处理 #
默认情况下，当RestClient收到4xx或5xx状态码时，它会抛出RestClientException的子类异常。可以使用状态处理器来覆盖此行为，如下所示：
1String result = restClient.get()
2 .uri("https://example.com/this-url-does-not-exist")
3 .retrieve()
4 .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
5 throw new MyCustomRuntimeException(response.getStatusCode(), response.getHeaders())
6 })
7 .body(String.class);
Exchange #
RestClient提供了exchange方法，用于更高级的场景，因为它提供了对底层HTTP请求和响应的访问。当使用exchange方法时，之前提到的状态处理器不会被应用，因为exchange函数已经提供了对完整响应的访问，让您可以执行任何必要的错误处理：
1RestClient restClient = RestClient.create();
2restClient.get()
3 .uri("https://api.example.com/users/{id}", 123)
4 .exchangeToMono(response -> {
5 if (response.statusCode().is4xxClientError()) {
6 // Custom handling for 4xx errors
7 return response.bodyToMono(String.class)
8 .flatMap(errorBody -> Mono.error(new CustomRestClientException(errorBody)));
9 } else if (response.statusCode().is5xxServerError()) {
10 // Custom handling for 5xx errors
11 return response.createException().flatMap(Mono::error);
12 } else {
13 // Successful response
14 return response.bodyToMono(String.class);
15 }
16 })
17 .block();
以上代码创建了一个RestClient实例，并设置了一个GET请求，URI中的变量id为123。我们使用exchangeToMono方法来处理响应，并根据不同的状态码执行自定义的错误处理逻辑。在示例中，当收到4xx状态码时，我们将响应体转换为字符串类型，并通过Mono.error抛出自定义的CustomRestClientException异常。当收到5xx状态码时，我们使用createException()创建相应的异常，并通过Mono.error抛出。对于成功的响应，我们将响应体转换为字符串类型。
请注意，以上代码仅为示例，您需要根据您的具体需求进行适当的调整:
1Pet result = restClient.get()
2 .uri("https://petclinic.example.com/pets/{id}", id)
3 .accept(APPLICATION_JSON)
4 .exchange((request, response) -> {
5 if (response.getStatusCode().is4xxClientError()) {
6 throw new MyCustomRuntimeException(response.getStatusCode(), response.getHeaders());
7 }
8 else {
9 Pet pet = convertResponse(response);
10 return pet;
11 }
12 });
RestClient的支持 #
RestClient只是Spring Framework 6.1提供的众多功能之一。许多组件已经支持RestClient：您可以通过MockRestServiceServer来测试其用法，或将其用作@HttpExchange接口的后端。
此外，Spring Boot 3.2 M1将包含对RestClient的支持。