Spring Boot 中的 RestTemplate

简述：

• Spring Boot 中没有⾃动配置 RestTemplate
• Spring Boot 提供了 RestTemplateBuilder

• RestTemplateBuilder.build()

常⽤⽅法

• GET 请求

• getForObject() / getForEntity()

• POST 请求

• postForObject() / postForEntity()

• PUT 请求

• put()

• DELETE 请求

• delete()

构造 URI

• 构造 URI

• UriComponentsBuilder

• 构造相对于当前请求的 URI

• ServletUriComponentsBuilder

• 构造指向 Controller 的 URI

• MvcUriComponentsBuilder

RestTemplate

官网地址：https://docs.spring.io/spring-framework/docs/current/reference/html/web.html#webmvc-client

RestTemplate是执行HTTP请求的同步客户端。它是原始的Spring REST客户端，并在底层HTTP客户端库上公开了一个简单的模板方法API。

从5.0开始，RestTemplate处于维护模式，只接受少量的更改请求和bug。请考虑使用 WebClient，它提供了更现代的API并支持同步、异步和流场景。

可参阅REST Endpoints 了解详细信息。

RestTemplate在HTTP客户端库上提供了更高级别的API。它使在单行中调用REST endpoints变得容易。它公开了以下几组重载方法:

Initialization

默认构造函数使用java.net.HttpURLConnection执行请求。您可以切换到具有ClientHttpRequestFactory实现的不同HTTP库。内置支持以下功能:

• Apache HttpComponents
• Netty
• OkHttp

例如，要切换到Apache HttpComponents，可以使用以下代码:

RestTemplate template = new RestTemplate(new HttpComponentsClientHttpRequestFactory());

每个ClientHttpRequestFactory公开特定于底层HTTP客户端库的配置选项——例如：连接池或其他细节。

注意，在访问表示错误(例如401)的响应状态时，java.net对HTTP请求的实现可能会引发异常。如果这是一个问题，请切换到另一个HTTP客户端库。

URIs

许多RestTemplate方法接受URI模板和URI模板变量，要么作为String变量参数，要么作为Map。

下面的例子使用了String变量参数:

String result = restTemplate.getForObject(
        "https://example.com/hotels/{hotel}/bookings/{booking}", String.class, "42", "21");

下面的例子使用Map:

Map vars = Collections.singletonMap("hotel", "42");

String result = restTemplate.getForObject(
        "https://example.com/hotels/{hotel}/rooms/{hotel}", String.class, vars);

请记住URI模板是自动编码的，如下例所示:

restTemplate.getForObject("https://example.com/hotel list", String.class);

// Results in request to "https://example.com/hotel%20list"

可以使用RestTemplate的uriTemplateHandler属性来自定义uri的编码方式。或者，可以准备一个java.net.URI，并将它传递到一个能够接受URI的RestTemplate方法。

有关使用和编码URI的更多细节，请参见 URI Links

Headers

可以使用exchange()方法来指定请求头，如下例所示:

String uriTemplate = "https://example.com/hotels/{hotel}";
URI uri = UriComponentsBuilder.fromUriString(uriTemplate).build(42);

RequestEntity requestEntity = RequestEntity.get(uri)
        .header("MyRequestHeader", "MyValue")
        .build();

ResponseEntity response = template.exchange(requestEntity, String.class);

String responseHeader = response.getHeaders().getFirst("MyResponseHeader");
String body = response.getBody();

可以通过诸多返回ResponseEntity的RestTemplate方法变体获得响应头。

Body

传入RestTemplate方法和从RestTemplate方法返回的对象与原始内容进行转换是通过HttpMessageConverter实现的。

在POST中，输入对象被序列化到请求体中，如下例所示:

URI location = template.postForLocation("https://example.com/people", person);

一般来说，不需要显式地设置请求的Content-Type头。在大多数情况下，可以根据源Object类型找到一个适配的MessageConverter，所选的消息转换器也会设置对应的Content-Type。如果有必要，可以使用exchange方法显式提供Content-Type请求头，而这又会影响选择什么消息转换器。

在GET中，响应体被反序列化为Object，如下例所示:

Person person = restTemplate.getForObject("https://example.com/people/{id}", Person.class, 42);

一般来说，请求的Accept头也不需要显式设置。在大多数情况下，可以根据预期的响应类型找到兼容的MessageConverter，它会填充Accept请求头。如果需要，可以使用exchange方法显式地提供Accept头。

默认情况下，RestTemplate根据类路径检索并注册所有内置的 message converters，类路径检索也有助于确定存在哪些可选的转换库。也可以显示的设置要使用的消息转换器。

Message Conversion

spring-web模块包含HttpMessageConverter，用于通过InputStream和OutputStream读取和写入HTTP请求体和响应体。HttpMessageConverter实例克用于客户端(例如，RestTemplate)和服务器端(例如，Spring MVC REST controllers)。

框架中提供了主要的媒体(MIME)类型的具体实现，默认情况下，会注册到客户端的RestTemplate和服务器端的RequestMappingHandlerAdapter(可参阅Configuring Message Converters)。

下面几节将描述HttpMessageConverter的实现。对于所有converters，都会使用默认的媒体类型，但是可以通过设置supportedMediaTypes bean属性来覆盖它。下表描述了每个实现:

Jackson JSON Views

你可以指定 Jackson JSON View 来序列化对象属性的一个子集，如下例所示:

MappingJacksonValue value = new MappingJacksonValue(new User("eric", "7!jd#h23"));
value.setSerializationView(User.WithoutPasswordView.class);

RequestEntity requestEntity =
    RequestEntity.post(new URI("https://example.com/user")).body(value);

ResponseEntity response = template.exchange(requestEntity, String.class);

Multipart

要发送multipart data，需要提供MultiValueMap，其值可能是部分内容的Object，文件部分的Resource，或带有头的部分内容的HttpEntity。例如:

MultiValueMap parts = new LinkedMultiValueMap<>();

parts.add("fieldPart", "fieldValue");
parts.add("filePart", new FileSystemResource("...logo.png"));
parts.add("jsonPart", new Person("Jason"));

HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_XML);
parts.add("xmlPart", new HttpEntity<>(myBean, headers));

在大多数情况下，不必为每个部分指定Content-Type。内容类型可以根据选择序列化它的HttpMessageConverter自动确定；在Resource的情况下可以根据文件扩展名确定。如果需要，可以显式地用HttpEntity wrapper提供MediaType。

一旦MultiValueMap准备好了，你可以将它传递给RestTemplate，如下所示:

MultiValueMap parts = ...;
template.postForObject("https://example.com/upload", parts, Void.class);

如果MultiValueMap包含至少一个非String值，则内容类型被FormHttpMessageConverter设置为multipart/form-data。如果MultiValueMap仅有String值，则Content-Type默认为application/x-www-form-urlencoded。如果需要，还可以显式地设置Content-Type。

REST endpoints

Spring框架为调用REST endpoints提供了两种选择:

• RestTemplate: 带有同步、模板方法API的原始Spring REST客户端。
• WebClient: 一个支持同步和异步以及流场景的非阻塞的、响应式的替代方案。