使用 RestTemplate 进行第三方Rest服务调用

1. 前言

RestTemplate 是 Spring 提供的一个调用 Restful 服务的抽象层，它简化的同 Restful 服务的通信方式，隐藏了不必要的一些细节，让我们更加优雅地在应用中调用 Restful 服务。但是在 Spring 5.0 以后RestTemplate处于维护模式，不再进行新特性的开发，仅仅进行一些日常维护。Spring 建议我们使用同时支持同步、异步和 Stream 的另一个 API —— WebClient 。但是在 Spring MVC 下目前我们还没有更好的选择。

2. RestTemplate 的使用场景

我们在项目中经常要使用第三方的 Rest API 服务，比如短信、快递查询、天气预报等等。这些第三方只要提供了 Rest Api ，你都可以使用 RestTemplate 来调用它们。

3. 初始化 RestTemplate

只要你的项目使用了 Spring MVC 就已经集成了RestTemplate 。但是通常情况下该类不会自动被注入 Spring IoC容器，因为很多 Rest API 都具有特殊性，为了更加灵活的进行定制，其构建类 RestTemplateBuilder被自动注入了 Spring IoC 容器。我们可以这样初始化它：

package cn.felord.rest.webclient;

import org.springframework.http.client.OkHttp3ClientHttpRequestFactory;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;

/**
 * @author felord.cn
 * @since 14:58
 **/
@Component
public class SomeWeb {

    private final RestTemplateBuilder restTemplateBuilder;

    public SomeWeb(RestTemplateBuilder restTemplateBuilder) {
        this.restTemplateBuilder = restTemplateBuilder;
    }

    public RestTemplate restTemplate() {
        // 通过 builder 定制
        return restTemplateBuilder.requestFactory(OkHttp3ClientHttpRequestFactory::new).
                build();
    }
}
复制代码

佳实践：针对每一个第三方服务尽量定制对应的 RestTemplate，尽量不公用，除非这些第三方的流程完全一致。

2.1 RestTemplate 底层

默认情况下，RestTemplate 使用 java.net.HttpURLConnection 作为实现，一但使用它时有异常响应状态（比如 401），就会引发异常，因此我们一般不使用它。我们可以切换到 Netty 、Apache HttpComponents、okHttp 默认实现的客户端库，参考 2 中的 requestFactory(ClientHttpRequestFactory factory) 接入方法，也可以自行实现 ClientHttpRequestFactory 对接其它第三方库进行接入。这里我使用 okHttp 。你可以定制这些第三方库提供的特性丰富你的 RestTemplate，比如设置请求超时。

3. 常用方法场景举例

RestTemplate 支持所有 Restful 风格方法，你可以根据需要进行选择，这里我们只介绍一些常用的方法。所有方法都支持URI 模板和 URI 参数，支持下面这种写法：

# 类似 spring mvc 中的 @PathVariable
https://api.apiopen.top/{method}
复制代码

3.1 {get|post}ForEntity

Get 请求后将响应映射为 ResponseEntity<T> 响应对象，一个响应体的包装对象。我们使用下列代码来随机请求 5 条漂亮小姐姐的照片，你可以打印进行查看：

    @Autowired
    RestTemplate restTemplate;

    void contextLoads() {
        String url = "https://api.apiopen.top/getImages?page=0&count=5";
        ResponseEntity<String> responseEntity = restTemplate
                .getForEntity(url,String.class);
        String body = responseEntity.getBody();
        System.out.println("body = " + body);
    }
复制代码

上面的方法改为按顺序的可变参数：

        String url = "https://api.apiopen.top/getImages?page={page}&count={count}";
        ResponseEntity<String> responseEntity = restTemplate
                .getForEntity(url,String.class,0,5);
        String body = responseEntity.getBody();
        System.out.println("body = " + body);
复制代码

或者使用 Map<String,Object>：

        String url = "https://api.apiopen.top/getImages?page={page}&count={count}";
        HashMap<String, Object> uriParams = new HashMap<>();
        uriParams.put("page", 0);
        uriParams.put("count", 5);
        ResponseEntity<String> responseEntity = restTemplate
                .getForEntity(url, String.class, uriParams);
        String body = responseEntity.getBody();
        System.out.println("body = " + body);
复制代码

post 请求额外会传入一个可能为 null 的 VO 对象，或者 MultiValueMap 来携带请求体参数，它们终会被封装入

org.springframework.http.HttpEntity 对象，该对象可包含以下两个部分：

请求体对象，可使用实体 VO、MultiValueMap
请求头对象， org.springframework.http.HttpHeaders

 String url = "https://api.apiopen.top/getImages?page={page}&count={count}";
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        HttpEntity<UserVO> httpEntity = new HttpEntity<>(new UserVO("userName"), headers);
        HashMap<String, Object> uriParams = new HashMap<>();
        uriParams.put("page", 0);
        uriParams.put("count", 5);
        ResponseEntity<String> responseEntity = restTemplate.postForEntity(url, httpEntity, String.class, uriParams);
复制代码

以上是一个调用 Post 请求并携带请求体和请求头的示例。

3.2 {get|post}ForObject

我们还可以将响应直接映射到 POJO, 当然你需要对响应结果的结构非常了解,建议先映射到 String 查看一下结构。我们给出一种示例，其他示例参考 3.1 :

        String url = "https://api.apiopen.top/getImages?page={page}&count={count}";
        HashMap<String, Object> uriParams = new HashMap<>();
        uriParams.put("page", 0);
        uriParams.put("count", 5);
        String forObject = restTemplate.getForObject(url, String.class, uriParams);
        System.out.println("forObject = " + forObject);
复制代码

3.3 headForHeaders

该方法用于获取所有的 URI 模板声明资源的 Header

        String url = "https://api.apiopen.top/getImages?page={page}&count={count}";
        HashMap<String, Object> uriParams = new HashMap<>();
        uriParams.put("page", 0);
        uriParams.put("count", 5);
        HttpHeaders httpHeaders = restTemplate.headForHeaders(url, uriParams);
        System.out.println(httpHeaders);
复制代码

结果为：

[Access-Control-Allow-Headers:"Content-Type, x-requested-with, X-Custom-Header, Authorization", Access-Control-Allow-Methods:"POST, GET, OPTIONS, DELETE", Access-Control-Allow-Origin:"*", Access-Control-Max-Age:"3600", Cache-Control:"private", Content-Length:"608", Content-Type:"application/json;charset=UTF-8", Date:"Tue, 14 Apr 2020 15:25:19 GMT", Expires:"Thu, 01 Jan 1970 00:00:00 GMT"]
复制代码

3.4 postForLocation

该 Post 操作不是返回完整的资源，而是返回新创建的资源 URI 。比如上传文件返回资源的请求路径。

3.5 put/delete

对应 put 请求和 delete 请求，参考前面的 api。

3.6 optionsForAllow

该方法获取该 URI 允许的所有请求方法比如 GET、POST、PUT、DELETE 中的一个或者几个。

3.7 exchange

该方法是通用的请求方式，支持 GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE，当上面的方式不能满足你可采用该方式定制，该方式提供了更加灵活的 API，比如你可以定制 GET 方法的请求头，放入 Jwt Token等操作，这是getForObject 无法比拟的。