【SpringBoot技术专题】「实战指南」从实战开发角度去分析操作RestTemplate的应用及使用技巧

前提介绍

当你的应用程序需要访问远程接口时，很容易被不同的浏览器和API调用协议弄晕。幸运的是，Spring框架已为我们提供了一个简单而功能强大的RestTemplate工具，它可以轻松地处理这些基础任务并提供一个简单的方式来访问各种API。

RestTemplate是Spring Framework中的一个用于RESTful Web Services的HTTP客户端，是Spring Web模块中的一部分。使用RestTemplate，我们可以消费Web服务，发送HTTP请求，并的到HTTP响应。它支持许多HTTP操作，如GET，POST，PUT，DELETE和PATCH，并可以通过各种协议访问不同的API和Web服务。

使用RestTemplate的好处包括：

1. 不需要自己编写低级别的HttpURLConnection代码，它已经为我们做好了这些工作。
2. RestTemplate默认使用Jackson JSON库进行对象序列化和反序列化。
3. RestTemplate在异常处理和错误处理方面提供了优秀的支持。
4. RestTemplate可以支持Ribbon，并且可以进行客户端负载平衡（如果有多个实例的话）。

接下来，我们将通过一个简单的示例来说明如何使用RestTemplate。

首先，让我们假设我们有一个可以向我们提供天气预报信息的RESTful Web服务。Web服务只支持HTTP GET请求，并返回JSON格式的数据。我们需要通过访问URL地址来获取数据。

现在，我们需要一个方式来访问这个Web服务，并通过RestTemplate将结果映射到我们的Java类中。下面是一个非常简单的代码块，您可以将其添加到您的应用程序中，以开始使用RestTemplate。

RestTemplate restTemplate = new RestTemplate();
WeatherReport report = restTemplate.getForObject("http://api.weather.com/report", WeatherReport.class);

使用RestTemplate的第一步是创建一个RestTemplate实例。在这个例子中，我们使用new关键字简单地实例化了一个RestTemplate对象。

接下来，在此示例中，我们使用getForObject方法来从URL中检索WeatherReport对象。当我们调用这个方法时，RestTemplate将自动使用Jackson JSON库将JSON响应映射到我们的WeatherReport类。需要注意的是，这里我们没有指定使用任何参数，也没有传递任何Http请求头，使用RestTemplate像这样发送数据是非常方便的。

使用RestTemplate，我们还可以执行POST，PUT，DELETE请求。例如，我们可以使用RestTemplate执行一个POST请求，以创建一个新记录：

RestTemplate restTemplate = new RestTemplate();
String addRecordUrl = "http://api.example.com/record";
Record record = // create new record
HttpEntity<Record> request = new HttpEntity<>(record, headers);
Record result = restTemplate.postForObject(addRecordUrl, request, Record.class);

在这个例子中，我们为创建请求提供了一个HttpEntity，并将其传递给postForObject方法。这将告诉RestTemplate我们想将一个对象提交到URL，同时还提供了一些Http请求头以满足API规范。RestTemplate将发送POST请求，并将请求体映射到我们提供的Record对象。最后一个参数是我们所期望的响应对象类型。根据我们的例子，我们期望响应是Record对象，所以我们将Record.class传递给postForObject方法。

总之，RestTemplate提供了一个可以轻松地访问RESTful Web服务的HTTP客户端，规避了复杂的低级HTTP访问代码，使我们可以为实现不同的HTTP操作节省大量的开发时间。希望这篇文章可以帮助您更好地了解如何使用RestTemplate。

RestTemplate的详细功能介绍

Spring提供了一种简单便捷的模板类RestTemplate来调用RESTful 接口。它提供了多种便捷访问HTTP服务的方法，能够大大提高客户端的编写效率。

RESTful API接口

@RestController
@Slf4j
public class RestfulController {
    
    // GET请求，不带参
    @GetMapping(value = "/getUser1", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public User getUser1() {
        return new User(1L, "zhaoxb");
    }
    // GET请求，带参。
    @GetMapping(value = "/getUser2", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public User getUser2(User user) {
        log.info("getUser2:{}", JSONUtil.toJsonPrettyStr(user));
        return user;
    }
    // POST请求，带参。
    @PostMapping(value = "/postUser", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public User postUser(User user) {
        log.info("postUser:{}", JSONUtil.toJsonPrettyStr(user));
        return user;
    }
    // POST请求，带有请求体。
    @PostMapping(value = "/postBody", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public User postBody(@RequestBody User user) {
        log.info("postBody:{}", JSONUtil.toJsonPrettyStr(user));
        return user;
    }
}

实体类，需要提供有参和无参构造。

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Long id;
    private String name;
}

RestTemplate配置类

@Configuration
public class RestConfig {
    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder) {
        RestTemplate restTemplate = restTemplateBuilder
                .setConnectTimeout(Duration.ofMillis(5000L))
                .setReadTimeout(Duration.ofMillis(30000L))
                .build();
        return restTemplate;
    }
}

发送GET请求

getForEntity方法，不带参

@ActiveProfiles("test")
@RunWith(SpringRunner.class)
@SpringBootTest
@Slf4j
public class RestfulGetTests {
    
    @Autowired
    private RestTemplate restTemplate;
    @Test
    public void getForEntity1() {
        ResponseEntity<String> responseEntity = restTemplate.
            getForEntity("http://127.0.0.1:31000/getUser1", String.class);
        log.info("响应码:{}", responseEntity.getStatusCodeValue());
        log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
    }
}

请求结果信息

响应码:200
响应体:{
    "name": "zhaoxb",
    "id": 1
}

getForEntity方法，数字占位符方式传参

@Test
public void getForEntity2() {
    ResponseEntity<String> responseEntity = restTemplate.
        getForEntity("http://127.0.0.1:31000/getUser2?id={1}&name={2}", String.class, 2, "zhaoxb");
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
}

用一个数字做占位符。最后是一个可变长度的参数，用来替换前面的占位符。

响应体:{
    "name": "zhaoxb",
    "id": 2
}

getForEntity方法，map占位符方式传参

@Test
public void getForEntity3() {
    Map<String, Object> map = new HashMap<>();
    map.put("id", 3);
    map.put("name", "zhaoxb");
    ResponseEntity<String> responseEntity = restTemplate.
        getForEntity("http://127.0.0.1:31000/getUser2?id={id}&name={name}", String.class, map);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
}

使用 name={name} 这种形式。最后一个参数是map，map的key为前边占位符的名字，value为实际参数值。

响应体:{
    "name": "zhaoxb",
    "id": 3
}

getForEntity方法，返回对象

@Test
public void getForEntity4() {
    ResponseEntity<User> responseEntity = restTemplate.getForEntity("http://127.0.0.1:31000/getUser1", User.class);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
}

响应体:{
    "name": "zhaoxb",
    "id": 1
}

getForObject方法，直接返回对象

@Test
public void getForObject() {
    User User = restTemplate.getForObject("http://127.0.0.1:31000/getUser1", User.class);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(User));
}

getForObject是对getForEntity函数的进一步封装，只关注返回消息的实体内容。

响应体:{
    "name": "zhaoxb",
    "id": 1
}

发送POST请求

用post方法发送带参的请求时，Map不能被定义为 HashMap、LinkedHashMap，而应被定义为 LinkedMultiValueMap，这样参数才能成功传递到后台。

postForEntity方法

@Test
public void postForEntity() {
    MultiValueMap<String, Object> multiValueMap = new LinkedMultiValueMap<>();
    multiValueMap.add("id", 5);
    multiValueMap.add("name", "zhaoxb");
    ResponseEntity<User> responseEntity = restTemplate.postForEntity("http://127.0.0.1:31000/postUser",
     multiValueMap, User.class);
    log.info("响应码:{}", responseEntity.getStatusCodeValue());
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
}

结果

响应体:{
    "name": "zhaoxb",
    "id": 5
}

postForObject方法

@Test
public void postForObject() {
    MultiValueMap<String, Object> multiValueMap = new LinkedMultiValueMap<>();
    multiValueMap.add("id", 6);
    multiValueMap.add("name", "zhaoxb");
    User user = restTemplate.postForObject("http://127.0.0.1:31000/postUser", multiValueMap, User.class);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(user));
}

和 getForObject 相对应，只关注返回的消息体。

响应体:{
    "name": "zhaoxb",
    "id": 6
}

postForObject方法，带有请求体body

@Test
public void postForObject2() {
    User reqUser = new User(10L, "zhaoxb");
    User user = restTemplate.postForObject("http://127.0.0.1:31000/postBody", reqUser, User.class);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(user));
}

RestTemplate底层实现序列化和反序列化。

响应体:{
    "name": "zhaoxb",
    "id": 10
}

exchange方法

@Test
public void exchange() {
    MultiValueMap<String, Object> multiValueMap = new LinkedMultiValueMap<>();
    multiValueMap.add("id", 7);
    multiValueMap.add("name", "zhaoxb");
    HttpEntity<MultiValueMap<String, Object>> httpEntity = new HttpEntity<>(multiValueMap);
    HttpEntity<MultiValueMap<String, Object>> httpEntityWithHeaders = new HttpEntity<>(multiValueMap, new HttpHeaders());
    ResponseEntity<User> responseEntity = restTemplate.exchange("http://127.0.0.1:31000/postUser", HttpMethod.POST, httpEntity, User.class);
    log.info("响应体:{}", JSONUtil.toJsonPrettyStr(responseEntity.getBody()));
}

HttpEntity还支持带有HTTP请求头的构造方法。

响应体:{
    "name": "zhaoxb",
    "id": 7
}

用RestTemplate发送PUT、PATCH、DELETE方法与GET、POST方法非常类似，这里不做展开。

自定义template

自定义HTTP源

• ClientHttpRequestFactory是Spring定义的一个接口，用于生产ClientHttpRequest对象，RestTemplate只是模板类，抽象

了很多调用方法，而底层真正使用何种框架发送HTTP请求是通过ClientHttpRequestFactory指定的。

• RestTemplate默认使用的是SimpleClientHttpRequestFactory，其内部使用的是JDK的java.net.HttpURLConnection创建

底层连接，默认是没有连接池的。可以通过 setRequestFactory 函数设置不同的HTTP源，比如 Apache HttpComponents、Netty

和OkHttp。

<dependencies>
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
    </dependency>
</dependencies>

@Configuration
public class RestConfig {
    @Bean
    public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder) {
        RestTemplate restTemplate = restTemplateBuilder
                .setConnectTimeout(Duration.ofMillis(5000L))
                .setReadTimeout(Duration.ofMillis(30000L))
                .requestFactory(() -> clientHttpRequestFactory())
                .build();
        return restTemplate;
    }

    @Bean
    public ClientHttpRequestFactory clientHttpRequestFactory() {
        HttpClientBuilder httpClientBuilder = HttpClientBuilder.create();
        //开始设置连接池
        PoolingHttpClientConnectionManager poolingHttpClientConnectionManager = new PoolingHttpClientConnectionManager();
        poolingHttpClientConnectionManager.setMaxTotal(100);  //最大连接数
        poolingHttpClientConnectionManager.setDefaultMaxPerRoute(20);  //同路由并发数
        httpClientBuilder.setConnectionManager(poolingHttpClientConnectionManager);

        HttpClient httpClient = httpClientBuilder.build();
        // httpClient连接配置
        HttpComponentsClientHttpRequestFactory clientHttpRequestFactory = new HttpComponentsClientHttpRequestFactory(httpClient);
        // 设置超时，如果 RestTemplateBuilder 已经设置，这里就不需要设置
//        clientHttpRequestFactory.setConnectTimeout(5 * 1000); // 连接超时
//        clientHttpRequestFactory.setReadTimeout(30 * 1000); // 数据读取超时时间
        clientHttpRequestFactory.setConnectionRequestTimeout(30 * 1000); //连接不够用的等待时间
        return clientHttpRequestFactory;
    }
}

自定义messageConverter

• RestTemplate默认使用 jackson 来实现序列化和反序列化，默认情况下会注册MIME类型的转换器，但可以通

过 setMessageConverters 函数指定其他类型的转化器。

• 这里其实也可以用FastJson库的FastJsonHttpMessageConverter4类来做转换器，只是近些年FastJson屡爆漏洞，还是建议

用默认的jackson来实现。