SpringCloud之RestTemplate的用法精讲

布满荆棘的人生 2021-11-22 06:46 422阅读 0赞

# 什么是RestTemplate #

RestTemplate 是从 Spring3.0 开始支持的一个 HTTP 请求工具，它提供了常见的REST请求方案的模版，例如 GET 请求、POST 请求、PUT 请求、DELETE 请求以及一些通用的请求执行方法 exchange 以及 execute。RestTemplate 继承自 InterceptingHttpAccessor 并且实现了 RestOperations 接口，其中 RestOperations 接口定义了基本的 RESTful 操作，这些操作在 RestTemplate 中都得到了实现。接下来我们就来看看这些操作方法的使用。

# 如何使用 #

首先我们创建一个普通的maven工程、然后分别创建eureka、provider、consumer三个SpringBoot子工程项目、然后分别在application.properties或者application.yml进行配置、配置参考可以参考上一个项目  
[服务中心与消费][Link 1]

创建好项目和我们可以看一下GET请求，在RestTemplate中GET请求有这几个方法  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70]  
这个请求中有两类方法，分别是getForEntity和getForObject，每一个类都有三个重载方法

**getForEntity**

我们要了解RestTemplate 发送的是Http请求，那么响应数据一定是有响应头的，如果需要获取响应头的信息，那么就可以使用getForEntity来发送Http请求，此时返回的就是一个ResponseEntity的实例，这个实例包含看响应头和响应的数据，例如下面的这个接口是来自provider 中的：

@RestController
    public class SayHelloController { 
        @GetMapping("/hello")
        public String sayHello(String name) { 
            return "hello " + name + " !";
        }
    }

我们需要在consumer 启动类中注入@RestTemplate

@SpringBootApplication
    public class ConsumerApplication { 
    
        public static void main(String[] args) { 
            SpringApplication.run(ConsumerApplication.class, args);
        }
    
        @Bean
        RestTemplate restTemplate() { 
            return new RestTemplate();
        }
    }

然后在consumer中添加一个SayUserHelloController ,并且提供一个/hello 来消费我们provider提供的服务

@RestController
    public class SayUseHelloController { 
        @Autowired
        RestTemplate restTemplate;
        @Autowired
        DiscoveryClient discoveryClient;
    
        @GetMapping("/hello")
        public String hello(String name) { 
            //拿到服务提供商
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            //拿到第一个实例
            ServiceInstance instance = list.get(0);
    
            //得到主机号
            String host = instance.getHost();
            //得到端口号
            int port = instance.getPort();
    
            //拼接完整的请求url
            String url = "http://" + host + ":" + port + "/hello?name={1}";
            //restTemple 实际返回的是一个ResponseEntity 的实例
            ResponseEntity<String> responseEntity = restTemplate.getForEntity(url, String.class, name);
    
            StrBuilder sb = new StrBuilder();
            //拿到状态码
            HttpStatus statusCode = responseEntity.getStatusCode();
            //拿到响应体
            String body= responseEntity.getBody();
            sb.append("statusCode:")
                    .append(statusCode)
                    .append("<br/>")
                    .append("body:")
                    .append(body)
                    .append("<br/>");
            //拿到响应头header
            HttpHeaders headers = responseEntity.getHeaders();
            Set<String> keySet = headers.keySet();
            for (String s : keySet) { 
                sb.append(s)
                        .append(":")
                        .append(headers.get(s))
                        .append("</br>");
            }
            return sb.toString();
        }
    }

关于 DiscoveryClient 那一段本文先不做讨论，主要来看 getForEntity 方法。第一个参数是 url ，url 中有一个占位符 \{1\} ,如果有多个占位符分别用 \{2\} 、 \{3\} … 去表示，第二个参数是接口返回的数据类型，最后是一个可变长度的参数，用来给占位符填值。在返回的 ResponseEntity 中，可以获取响应头中的信息，其中 getStatusCode 方法用来获取响应状态码， getBody 方法用来获取响应数据， getHeaders 方法用来获取响应头，在浏览器中访问该接口，结果如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 1]

除了上面这一种方法外，还有两种方法也就是getForEntity另外两个重载方法，使用map

Map<String,Object> map = new HashMap<>();
       map.put("name",name);
       ResponseEntity<String> responseEntity = restTemplate.getForEntity(url, String.class, map);

还有一种就是使用Uri对象

String url = "http://" + host + ":" + port + "/hello?name=" + URLEncoder.encode(name, "UTF-8");
    URI uri = URI.create(url);
    ResponseEntity<String> responseEntity = restTemplate.getForEntity(uri,String.class);

注意这里使用URL如果是带了中文字符串那么需要使用UTF-8

**getForObject**

getForObject 方法和 getForEntity 方法类似，getForObject 方法也有三个重载的方法，参数和 getForEntity 一样，因此这里我就不重复介绍参数了，这里主要说下 getForObject 和 getForEntity 的差异，这两个的差异主要体现在返回值的差异上， getForObject 的返回值就是服务提供者返回的数据，使用 getForObject 无法获取到响应头。例如，还是上面的请求，利用 getForObject 来发送 HTTP 请求，结果如下：

String url = "http://" + host + ":" + port + "/hello?name=" + URLEncoder.encode(name, "UTF-8");
    URI uri = URI.create(url);
    String s = restTemplate.getForObject(uri, String.class);

注意，这里返回的 s 就是 provider 的返回值，如果开发者只关心 provider 的返回值，并不关系 HTTP 请求的响应头，那么可以使用该方法。

**POST请求**  
和 GET 请求相比，RestTemplate 中的 POST 请求多了一个类型的方法，如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 2]  
可以看到，post 请求的方法类型除了 postForEntity 和 postForObject 之外，还有一个 postForLocation。这里的方法类型虽然有三种，但是这三种方法重载的参数基本是一样的，因此这里我还是以 postForEntity 方法为例，来剖析三个重载方法的用法，最后再重点说下 postForLocation 方法。

**postForEntity**  
在 POST 请求中，参数的传递可以是 key/value 的形式，也可以是 JSON 数据，分别来看：  
传递 key/value 形式的参数  
首先在 provider 的 SayHelloController 类中再添加一个 POST 请求的接口，如下：

@PostMapping("/hello2")
    public String sayHello2(String name) { 
        return "Hello " + name + " !";
    }

然后在consumer 中去调用provider 中提供的/hello2

@GetMapping("/hello5")
    public String hello5(String name) { 
        List<ServiceInstance> list = discoveryClient.getInstances("provider");
        ServiceInstance instance = list.get(0);
        String host = instance.getHost();
        int port = instance.getPort();
        String url = "http://" + host + ":" + port + "/hello2";
        MultiValueMap map = new LinkedMultiValueMap();
        map.add("name", name);
        ResponseEntity<String> responseEntity = restTemplate.postForEntity(url, map, String.class);
        return responseEntity.getBody();
    }

在这里， postForEntity 方法第一个参数是请求地址，第二个参数 map 对象中存放着请求参数 key/value，第三个参数则是返回的数据类型。当然这里的第一个参数 url 地址也可以换成一个 Uri 对象，效果是一样的。这种方式传递的参数是以 key/value 形式传递的，在 post 请求中，也可以按照 get 请求的方式去传递 key/value 形式的参数，传递方式和 get 请求的传参方式基本一致，例如下面这样：

@GetMapping("/hello6")
    public String hello6(String name) { 
        List<ServiceInstance> list = discoveryClient.getInstances("provider");
        ServiceInstance instance = list.get(0);
        String host = instance.getHost();
        int port = instance.getPort();
        String url = "http://" + host + ":" + port + "/hello2?name={1}";
        ResponseEntity<String> responseEntity = restTemplate.postForEntity(url, null, String.class,name);
        return responseEntity.getBody();
    }

此时第二个参数可以直接传一个 null。

# 如何传递JSON数据 #

上面介绍的是 post 请求传递 key/value 形式的参数，post 请求也可以直接传递 json 数据，在 post 请求中，可以自动将一个对象转换成 json 进行传输，数据到达 provider 之后，再被转换为一个对象。具体操作步骤如下：

首先在 RestTemplate 项目中创建一个新的maven项目，叫做 commons ，然后在 commons 中创建一个 User 对象，如下：

@Data
    public class UserDTO { 
        private String nickname;
        private String address;
    }

然后分别在 provider 和 consumer 的 pom.xml 文件中添加对 commons 模块的依赖，如下：

<dependency>
                <groupId>cn.com.scitc</groupId>
                <artifactId>commons</artifactId>
                <version>1.0-SNAPSHOT</version>
     </dependency>

这样，在 provider 和 consumer 中就都能使用 UserDTO 对象了。首先在 provider 中创建一个添加用户的接口，如下：

@Controller
    @ResponseBody
    public class UserController { 
        @PostMapping("/user")
        public ResponseEntity<Object> userDTO(@RequestBody UserDTO userDTO) { 
            return new ResponseEntity<Object>(userDTO, HttpStatus.OK);
        }
    }

这里的接口很简单，只需要将用户传来的 User 对象再原封不动地返回去就行了，然后在 consumer 中添加一个接口来测试这个接口，如下：

@PostMapping("/hello7")
        public ResponseEntity<UserDTO> hello7(@RequestBody UserDTO userDTO) { 
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            ServiceInstance instance = list.get(0);
            String host = instance.getHost();
            int port = instance.getPort();
            String url = "http://" + host + ":" + port + "/user";
            UserDTO u = new UserDTO();
            u.setNickname(userDTO.getNickname());
            u.setAddress(userDTO.getAddress());
            ResponseEntity<UserDTO> responseEntity = restTemplate.postForEntity(url, u, UserDTO.class);
            return new ResponseEntity<UserDTO>(responseEntity.getBody(),HttpStatus.OK);
        }

我们访问localhost:4002/hello7并且传入如下参数

{ 
    "nickname": "技术无止境",
    "address": "四川成都"
    }

服务返回结果如下:  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 3]  
看到这段代码有人要问了，这不和前面的一样吗？是的，唯一的区别就是第二个参数的类型不同，这个参数如果是一个 MultiValueMap 的实例，则以 key/value 的形式发送，如果是一个普通对象，则会被转成 json 发送。

**postForObject**

postForObject 和 postForEntity 基本一致，就是返回类型不同而已，这里不再赘述。

**postForLocation**

postForLocation 方法的返回值是一个 Uri 对象，因为 POST 请求一般用来添加数据，有的时候需要将刚刚添加成功的数据的 URL 返回来，此时就可以使用这个方法，一个常见的使用场景如用户注册功能，用户注册成功之后，可能就自动跳转到登录页面了，此时就可以使用该方法。例如在 provider 中提供一个用户注册接口，再提供一个用户登录接口，如下：

@RequestMapping("/register")
        public String register(UserDTO userDTO) throws UnsupportedEncodingException { 
            return "redirect:/loginPage?username=" + URLEncoder.encode(userDTO.getNickname(),"UTF-8") + "&address=" + URLEncoder.encode(userDTO.getAddress(),"UTF-8");
        }
    
        @GetMapping("/loginPage")
        @ResponseBody
        public String loginPage(UserDTO userDTO) { 
            return "loginPage:" + userDTO.getNickname() + ":" + userDTO.getAddress();
        }

**注意：postForLocation 方法返回的 Uri 实际上是指响应头的 Location 字段，所以，provider 中 register 接口的响应头必须要有 Location 字段（即请求的接口实际上是一个重定向的接口），否则 postForLocation 方法的返回值为null，初学者很容易犯这个错误，如果这里出错，大家可以参考下我的源代码。**

### PUT请求 ###

只要将 GET 请求和 POST 请求搞定了，接下来 PUT 请求就会容易很多了，PUT 请求本身方法也比较少，只有三个，如下：

![在这里插入图片描述][20190730095527981.jpeg]  
这三个重载的方法其参数其实和 POST 是一样的，可以用 key/value 的形式传参，也可以用 JSON 的形式传参，无论哪种方式，都是没有返回值的，我这里就举两个例子给大家参考下：

首先在 provider 的 UserController 中添加如下两个数据更新接口：

@PutMapping("/user/name")
    @ResponseBody
    public void updateUserByUsername(User User) { 
        System.out.println(User);
    }
    @PutMapping("/user/address")
    @ResponseBody
    public void updateUserByAddress(@RequestBody User User) { 
        System.out.println(User);
    }

这里两个接口，一个接收 key/value 形式的参数，另一个接收 JSON 参数。因为这里没有返回值，我直接把数据打印出来就行了。接下来在 consumer 中添加接口调用这里的服务，如下：

@GetMapping("/hello9")
        public void hello9() { 
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            ServiceInstance instance = list.get(0);
            String host  = instance.getHost();
            int port = instance.getPort();
            String url1 = "http://" + host + ":" + port + "/user/name";
            String url2 = "http://" + host + ":" + port + "/user/address";
            MultiValueMap map =  new LinkedMultiValueMap();
            map.add("nickname","技术无止境");
            map.add("address", "四川成都");
            restTemplate.put(url1, map);
            UserDTO u = new UserDTO();
            u.setNickname("独孤剑圣");
            u.setAddress("北上广");
            restTemplate.put(url2, u);
        }

我们访问hello9接口返回结果如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 4]  
**DELETE请求**  
和 PUT 请求一样，DELETE 请求也是比较简单的，只有三个方法，如下：  
![在这里插入图片描述][20190730103911132.png]

不同于 POST 和 PUT ，DELETE 请求的参数只能在地址栏传送，可以是直接放在路径中，也可以用 key/value 的形式传递，当然，这里也是没有返回值的。我也举两个例子：  
首先在 provider 的 UserController 中添加两个接口，如下：

@DeleteMapping("/user/{id}")
    @ResponseBody
    public void deleteUserById(@PathVariable Integer id) { 
        System.out.println(id);
    }
    @DeleteMapping("/user/")
    @ResponseBody
    public void deleteUserByUsername(String username) { 
        System.out.println(username);
    }

两个接口，一个的参数在路径中，另一个的参数以 key/value 的形式传递，然后在 consumer 中，添加一个方法调用这两个接口，如下：

@GetMapping("/hello10")
        public void hello10() { 
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            ServiceInstance instance = list.get(0);
            String host = instance.getHost();
            int port = instance.getPort();
            String url1 = "http://" + host + ":" + port + "/user/{1}";
            String url2 = "http://" + host + ":" + port + "/user/?nickname={nickname}";
            Map<String,String> map = new HashMap<>();
            map.put("nickname","技术无止境");
            restTemplate.delete(url1, 99);
            restTemplate.delete(url2, map);
        }

我们请求hello10返回结果如下:  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 5]  
99就是删除的id,技术无止境就是我们的nickname

# 如何设置请求头 #

有的时候我们会有一些特殊的需求，例如模拟 cookie ，此时就需要我们自定义请求头了。自定义请求头可以通过拦截器的方式来实现（下篇文章我们会详细的说这个拦截器）。定义拦截器、自动修改请求数据、一些身份认证信息等，都可以在拦截器中来统一处理。具体操作步骤如下：

首先在 provider 中定义一个接口，在接口中获取客户端传来的 cookie 数据，如下：

@GetMapping("diyheader")
    public String diyHeader(HttpServletRequest request) { 
         return request.getHeader("cookie");
     }

这里简单处理，将客户端传来的 cookie 拿出来后再返回给客户端，然后在 consumer 中添加如下接口来测试：

@GetMapping("/hello11")
        public void hello11() { 
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            ServiceInstance instance = list.get(0);
            String host = instance.getHost();
            int port = instance.getPort();
            String url = "http://" + host + ":" + port + "/diyheader";
            restTemplate.setInterceptors(Collections.singletonList(new ClientHttpRequestInterceptor() { 
                @Override
                public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException, IOException { 
                    HttpHeaders headers = request.getHeaders();
                    headers.add("cookie","i love java");
                    return execution.execute(request,body);
                }
            }));
            String s = restTemplate.getForObject(url, String.class);
            System.out.println(s);
        }

这里通过调用 RestTemplate 的 setInterceptors 方法来给它设置拦截器，拦截器也可以有多个，我这里只有一个。在拦截器中，将请求拿出来，给它设置 cookie ，然后调用 execute 方法让请求继续执行。此时，在 /diyheader 接口中就获取到cookie了。  
访问hello11 执行结果：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 6]

**通用方法 exchange**  
在 RestTemplate 中还有一个通用的方法 exchange。为什么说它通用呢？因为这个方法需要你在调用的时候去指定请求类型，即它既能做 GET 请求，也能做 POST 请求，也能做其它各种类型的请求。如果开发者需要对请求进行封装，使用它再合适不过了，举个简单例子：

@GetMapping("/hello12")
        public void hello12() { 
            List<ServiceInstance> list = discoveryClient.getInstances("provider");
            ServiceInstance instance = list.get(0);
            String host = instance.getHost();
            int port = instance.getPort();
            String url = "http://" + host + ":" + port + "/diyheader";
            HttpHeaders headers = new HttpHeaders();
            headers.add("cookie","i love gir");
            HttpEntity<MultiValueMap<String,String>> request =  new HttpEntity<>(null,headers);
            ResponseEntity<String> responseEntity = restTemplate.exchange(url, HttpMethod.GET, request, String.class);
            System.out.println(responseEntity.getBody());
        }

这里的参数和前面的也都差不多，注意就是多了一个请求类型的参数，然后创建一个 HttpEntity 作为参数来传递。 HttpEntity 在创建时候需要传递两个参数，第一个上文给了一个 null ，这个参数实际上就相当于 POST/PUT 请求中的第二个参数，有需要可以自行定义。HttpEntity 创建时的第二个参数就是请求头了，也就是说，如果使用 exchange 来发送请求，可以直接定义请求头，而不需要使用拦截器。

访问hello12执行结果：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 7]

# 总结 #

本文主要向大家介绍了 RestTemplate 这样一个 HTTP 请求工具类的常见用法，一些比较冷门的用法本文并未涉及，读者有兴趣可以自行查找资料学习。由于 Spring、SpringMVC、Spring Boot、Spring Cloud 这些家族成员一脉相承，因此在 SpringMVC 中支持良好的 RESTful 风格的接口在后续的各个组件中都继续支持，在微服务接口设计时，大部分接口也都满足 RESTful 风格，使用 RestTemplate 则可以非常方便地发送 RESTful 风格的请求，因此这个工具的使用是我们后面学习的基础，常见的用法一定要熟练掌握。

# 源码地址 #

[github][]

[Link 1]: https://blog.csdn.net/qwe86314/article/details/97232360
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70]: /images/20211122/af8ab15425454e9fbd520a8c800e573c.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 1]: /images/20211122/c20c5ea266f54909aa4227f0e11b6645.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 2]: /images/20211122/140fd8a986b14ce8ac7226632d4c32b6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 3]: /images/20211122/786d12e76e274d9690a5ce60f99e005b.png
[20190730095527981.jpeg]: /images/20211122/03eed2d6bc82409fb78b7ff6c8f1a7ea.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 4]: /images/20211122/381f63d630884e2aaf31856027783529.png
[20190730103911132.png]: https://img-blog.csdnimg.cn/20190730103911132.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20190730101244981.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 6]: https://img-blog.csdnimg.cn/20190730102358845.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0_size_16_color_FFFFFF_t_70 7]: https://img-blog.csdnimg.cn/20190730102506238.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3F3ZTg2MzE0,size_16,color_FFFFFF,t_70
[github]: https://github.com/zhoubiao188/spring_cloud_study/tree/master/RestTemplate