转载

使用 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 对象，该对象可包含以下两个部分：

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 无法比拟的。