21 Spring Rest Template 常见错误 你好,我是傅健。
前面几节课,我们介绍了一个 Spring 微服务使用数据库过程中可能遇到的常见错误。而实际上,除了直接使用数据库外,使用其他微服务来完成功能也是一个常见的应用场景。
一般而言,微服务之间的通信大多都是使用 HTTP 方式进行的,这自然少不了使用 HttpClient。在不使用 Spring 之前,我们一般都是直接使用 Apache HttpClient 和 Ok HttpClient 等,而一旦你引入 Spring,你就有了一个更好的选择,这就是我们这一讲的主角 RestTemplate。那么在使用它的过程中,会遇到哪些错误呢?接下来我们就来总结下。
案例 1:参数类型是 MultiValueMap
首先,我们先来完成一个 API 接口,代码示例如下: @RestController public class HelloWorldController { @RequestMapping(path = “hi”, method = RequestMethod.POST) public String hi(@RequestParam(“para1”) String para1, @RequestParam(“para2”) String para2){ return “helloworld:” + para1 + “,” + para2; }; }
这里我们想完成的功能是接受一个 Form 表单请求,读取表单定义的两个参数 para1 和 para2,然后作为响应返回给客户端。
定义完这个接口后,我们使用 RestTemplate 来发送一个这样的表单请求,代码示例如下: RestTemplate template = new RestTemplate(); Map<String, Object> paramMap = new HashMap<String, Object>(); paramMap.put(“para1”, “001”); paramMap.put(“para2”, “002”); String url = “http://localhost:8080/hi”; String result = template.postForObject(url, paramMap, String.class); System.out.println(result);
上述代码定义了一个 Map,包含了 2 个表单参数,然后使用 RestTemplate 的 postForObject 提交这个表单。
测试后你会发现事与愿违,返回提示 400 错误,即请求出错:
具体而言,就是缺少 para1 表单参数。为什么会出现这个错误呢?我们提交的表单最后又成了什么?
案例解析
在具体解析这个问题之前,我们先来直观地了解下,当我们使用上述的 RestTemplate 提交表单,最后的提交请求长什么样?这里我使用 Wireshark 抓包工具直接给你抓取出来:
从上图可以看出,我们实际上是将定义的表单数据以 JSON 请求体(Body)的形式提交过去了,所以我们的接口处理自然取不到任何表单参数。
那么为什么会以 JSON 请求体来提交数据呢?这里我们不妨扫一眼 RestTemplate 中执行上述代码时的关键几处代码调用。
首先,我们看下上述代码的调用栈:
确实可以验证,我们最终使用的是 Jackson 工具来对表单进行了序列化。使用到 JSON 的关键之处在于其中的关键调用 RestTemplate.HttpEntityRequestCallback/#doWithRequest: public void doWithRequest(ClientHttpRequest httpRequest) throws IOException { super.doWithRequest(httpRequest); Object requestBody = this.requestEntity.getBody(); if (requestBody == null) { //省略其他非关键代码 } else { Class<?> requestBodyClass = requestBody.getClass(); Type requestBodyType = (this.requestEntity instanceof RequestEntity ? ((RequestEntity<?>)this.requestEntity).getType() : requestBodyClass); HttpHeaders httpHeaders = httpRequest.getHeaders(); HttpHeaders requestHeaders = this.requestEntity.getHeaders(); MediaType requestContentType = requestHeaders.getContentType(); for (HttpMessageConverter<?> messageConverter : getMessageConverters()) { if (messageConverter instanceof GenericHttpMessageConverter) { GenericHttpMessageConverter
上述代码看起来比较复杂,实际上功能很简单:根据当前要提交的 Body 内容,遍历当前支持的所有编解码器,如果找到合适的编解码器,就使用它来完成 Body 的转化。这里我们不妨看下 JSON 的编解码器对是否合适的判断,参考 AbstractJackson2HttpMessageConverter/#canWrite:
可以看出,当我们使用的 Body 是一个 HashMap 时,是可以完成 JSON 序列化的。所以在后续将这个表单序列化为请求 Body 也就不奇怪了。
但是这里你可能会有一个疑问,为什么适应表单处理的编解码器不行呢?这里我们不妨继续看下对应的编解码器判断是否支持的实现,即 FormHttpMessageConverter/#canWrite: public boolean canWrite(Class<?> clazz, @Nullable MediaType mediaType) { if (!MultiValueMap.class.isAssignableFrom(clazz)) { return false; } if (mediaType == null || MediaType.ALL.equals(mediaType)) { return true; } for (MediaType supportedMediaType : getSupportedMediaTypes()) { if (supportedMediaType.isCompatibleWith(mediaType)) { return true; } } return false; }
从上述代码可以看出,实际上,只有当我们发送的 Body 是 MultiValueMap 才能使用表单来提交。学到这里,你可能会豁然开朗。原来使用 RestTemplate 提交表单必须是 MultiValueMap,而我们案例定义的就是普通的 HashMap,最终是按请求 Body 的方式发送出去的。
问题修正
其实上面解释了那么多,相信你肯定知道怎么去解决这个问题了,其实很简单,把案例中的 HashMap 换成一个 MultiValueMap 类型来存储表单数据即可。修正代码示例如下: //错误: //Map<String, Object> paramMap = new HashMap<String, Object>(); //paramMap.put(“para1”, “001”); //paramMap.put(“para2”, “002”); //修正代码: MultiValueMap<String, Object> paramMap = new LinkedMultiValueMap<String, Object>(); paramMap.add(“para1”, “001”); paramMap.add(“para2”, “002”);
最终你会发现,当完成上述修改后,表单数据最终使用下面的代码进行了编码,参考 FormHttpMessageConverter/#write:
public void write(MultiValueMap<String, ?> map, @Nullable MediaType contentType, HttpOutputMessage outputMessage) throws IOException, HttpMessageNotWritableException { if (isMultipart(map, contentType)) { writeMultipart((MultiValueMap<String, Object>) map, contentType, outputMessage); } else { writeForm((MultiValueMap<String, Object>) map, contentType, outputMessage); } }
发送出的数据截图如下:
这样就满足我们的需求了。
实际上,假设你仔细看文档的话,你可能也会规避这个问题,文档关键行如下: The body of the entity, or request itself, can be a MultiValueMap to create a multipart request. The values in the MultiValueMap can be any Object representing the body of the part, or an HttpEntity
相信不用我讲,你也能看明白它说的正是我们刚刚费尽口舌去解释的事情。很多人还会犯错的原因大多都是没有耐心去看,或者懒得去看,更喜欢去“想当然”。在Spring 的使用上,这点是大忌。
案例 2:当 URL 中含有特殊字符
接下来,我们再来看一个关于 RestTemplate 使用的问题。我们还是使用之前类型的接口定义,不过稍微简化一下,代码示例如下: @RestController public class HelloWorldController { @RequestMapping(path = “hi”, method = RequestMethod.GET) public String hi(@RequestParam(“para1”) String para1){ return “helloworld:” + para1; }; }
不需要我多介绍,你大体应该知道我们想实现的功能是什么了吧,无非就是提供一个带“参数”的 HTTP 接口而已。
然后我们使用下面的 RestTemplate 相关代码来测试一下:
String url = “http://localhost:8080/hi?para1=1/#2”; HttpEntity<?> entity = new HttpEntity<>(null); RestTemplate restTemplate = new RestTemplate(); HttpEntity
当你看到这段测试代码,你觉得会输出什么呢?相信你很可能觉得是:
helloworld:1/#2
但是实际上,事与愿违,结果是:
helloworld:1
即服务器并不认为 /#2 是 para1 的内容。如何理解这个现象呢?接下来我们可以具体解析下。
案例解析
类似案例 1 解析的套路,在具体解析之前,我们可以先直观感受下问题出在什么地方。我们使用调试方式去查看解析后的 URL,截图如下:
可以看出,para1 丢掉的 /#2 实际是以 Fragment 的方式被记录下来了。这里顺便科普下什么是 Fragment,这得追溯到 URL 的格式定义: protocol://hostname[:port]/path/[?query]/#fragment
本案例中涉及到的两个关键元素解释如下:
- Query(查询参数)
页面加载请求数据时需要的参数,用 & 符号隔开,每个参数的名和值用 = 符号隔开。
- Fragment(锚点)
/#开始,字符串,用于指定网络资源中的片断。例如一个网页中有多个名词解释,可使用 Fragment 直接定位到某一名词的解释。例如定位网页滚动的位置,可以参考下面一些使用示例: http://example.com/data.csv/#row=4 – Selects the 4th row.- http://example.com/data.csv/#col=2 – Selects 2nd column.
了解了这些补充知识后,我们其实就能知道问题出在哪了。不过本着严谨的态度,我们还是翻阅下源码。首先,我们先看下 URL 解析的调用栈,示例如下:
参考上述调用栈,解析 URL 的关键点在于 UriComponentsBuilder/#fromUriString 实现: private static final Pattern URI_PATTERN = Pattern.compile( “^(“ + SCHEME_PATTERN + “)?” + “(//(“ + USERINFO_PATTERN + “@)?” + HOST_PATTERN + “(:” + PORT_PATTERN + “)?” + “)?” + PATH_PATTERN + “(\?” + QUERY_PATTERN + “)?” + “(/#” + LAST_PATTERN + “)?”); public static UriComponentsBuilder fromUriString(String uri) { Matcher matcher = URI_PATTERN.matcher(uri); if (matcher.matches()) { UriComponentsBuilder builder = new UriComponentsBuilder(); String scheme = matcher.group(2); String userInfo = matcher.group(5); String host = matcher.group(6); String port = matcher.group(8); String path = matcher.group(9); String query = matcher.group(11); String fragment = matcher.group(13); //省略非关键代码 else { builder.userInfo(userInfo); builder.host(host); if (StringUtils.hasLength(port)) { builder.port(port); } builder.path(path); builder.query(query); } if (StringUtils.hasText(fragment)) { builder.fragment(fragment); } return builder; } else { throw new IllegalArgumentException(“[” + uri + “] is not a valid URI”); } }
从上述代码实现中,我们可以看到关键的几句,这里我摘取了出来:
String query = matcher.group(11); String fragment = matcher.group(13);
很明显,Query 和 Fragment 都有所处理。最终它们根据 URI_PATTERN 各自找到了相应的值 (1和2),虽然这并不符合我们的原始预期。
问题修正
那么怎么解决这个问题呢? 如果你不了解 RestTemplate 提供的各种 URL 组装方法,那你肯定是有点绝望的。这里我给出了代码修正方法,你可以先看看:
String url = “http://localhost:8080/hi?para1=1/#2”; UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(url); URI uri = builder.build().encode().toUri(); HttpEntity<?> entity = new HttpEntity<>(null); RestTemplate restTemplate = new RestTemplate(); HttpEntity
最终测试结果符合预期:
helloworld:1/#2
与之前的案例代码进行比较,你会发现 URL 的组装方式发生了改变。但最终可以获取到我们预期的效果,调试视图参考如下:
可以看出,参数 para1 对应的值变成了我们期待的”1/#2”。
如果你想了解更多的话,还可以参考 UriComponentsBuilder/#fromHttpUrl,并与之前使用的 UriComponentsBuilder/#fromUriString 进行比较: private static final Pattern HTTP_URL_PATTERN = Pattern.compile( “^” + HTTP_PATTERN + “(//(“ + USERINFO_PATTERN + “@)?” + HOST_PATTERN + “(:” + PORT_PATTERN + “)?” + “)?” + PATH_PATTERN + “(\?” + LAST_PATTERN + “)?”) public static UriComponentsBuilder fromHttpUrl(String httpUrl) { Assert.notNull(httpUrl, “HTTP URL must not be null”); Matcher matcher = HTTP_URL_PATTERN.matcher(httpUrl); if (matcher.matches()) { UriComponentsBuilder builder = new UriComponentsBuilder(); String scheme = matcher.group(1); builder.scheme(scheme != null ? scheme.toLowerCase() : null); builder.userInfo(matcher.group(4)); String host = matcher.group(5); if (StringUtils.hasLength(scheme) && !StringUtils.hasLength(host)) { throw new IllegalArgumentException(“[” + httpUrl + “] is not a valid HTTP URL”); } builder.host(host); String port = matcher.group(7); if (StringUtils.hasLength(port)) { builder.port(port); } builder.path(matcher.group(8)); builder.query(matcher.group(10)); return builder; } else { throw new IllegalArgumentException(“[” + httpUrl + “] is not a valid HTTP URL”); } }
可以看出,这里只解析了Query并没有去尝试解析 Fragment,所以最终获取到的结果符合预期。
通过这个例子我们可以知道,当 URL 中含有特殊字符时,一定要注意 URL 的组装方式,尤其是要区别下面这两种方式: UriComponentsBuilder/#fromHttpUrl- UriComponentsBuilder/#fromUriString
案例 3:小心多次 URL Encoder
接下来,我们继续看一个案例,这里完全沿用之前的接口: @RestController public class HelloWorldController { @RequestMapping(path = “hi”, method = RequestMethod.GET) public String hi(@RequestParam(“para1”) String para1){ return “helloworld:” + para1; }; }
然后我们可以换一种使用方式来访问这个接口,示例如下:
RestTemplate restTemplate = new RestTemplate(); UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(“http://localhost:8080/hi”); builder.queryParam(“para1”, “开发测试 001”); String url = builder.toUriString(); ResponseEntity
我们期待的结果是”helloworld:开发测试 001”,但是运行上述代码后,你会发现结果却是下面这样:
helloworld:%E5%BC%80%E5%8F%91%E6%B5%8B%E8%AF%95001
如何理解这个问题呢?
案例解析
要了解这个案例,我们就需要对上述代码中关于 URL 的处理有个简单的了解。首先我们看下案例中的代码调用: String url = builder.toUriString();
它执行的方式是 UriComponentsBuilder/#toUriString:
public String toUriString() { return this.uriVariables.isEmpty() ? build().encode().toUriString() : buildInternal(EncodingHint.ENCODE_TEMPLATE).toUriString(); }
可以看出,它最终执行了 URL Encode:
public final UriComponents encode() { return encode(StandardCharsets.UTF_8); }
查询调用栈,结果如下:
而当我们把 URL 转化成 String,再通过下面的语句来发送请求时: //url 是一个 string- restTemplate.getForEntity(url, String.class);
我们会发现,它会再进行一次编码:
看到这里,你或许已经明白问题出在哪了,即我们按照案例的代码会执行 2 次编码(Encode),所以最终我们反而获取不到想要的结果了。
另外,我们还可以分别查看下两次编码后的结果,示例如下:
1 次编码后:
2 次编码后:
问题修正
如何修正? 直接上代码:
RestTemplate restTemplate = new RestTemplate(); UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(“http://localhost:8080/hi”); builder.queryParam(“para1”, “开发测试 001”); URI url = builder.encode().build().toUri(); ResponseEntity
其实说白了,这种修正方式就是避免多次转化而发生多次编码。这里不再赘述其内部实现,因为正确的方式并非这次解析的重点,你能意识到这个问题出在哪,我们的目的就达到了。
重新运行测试,结果符合预期: helloworld:开发测试 001
重点回顾
这节课我们学习了 RestTemplate 使用中经常遇到的 3 个典型问题,这里再次梳理下关键知识点:
-
当使用 RestTemplate 组装表单数据时,我们应该注意要使用 MultiValueMap 而非普通的 HashMap。否则会以 JSON 请求体的形式发送请求而非表单,正确示例如下: MultiValueMap<String, Object> paramMap = new LinkedMultiValueMap<String, Object>(); paramMap.add(“para1”, “001”); paramMap.add(“para2”, “002”); String url = “http://localhost:8080/hi”; String result = template.postForObject(url, paramMap, String.class); System.out.println(result)
-
当使用 RestTemplate 发送请求时,如果带有查询(Query)参数,我们一定要注意是否含有一些特殊字符(/#)。如果有的话,可以使用下面的 URL 组装方式进行规避: String url = “http://localhost:8080/hi?para1=1/#2”; UriComponentsBuilder builder = UriComponentsBuilder.fromHttpUrl(url); URI uri = builder.build().encode().toUri();
-
在 RestTemplate 中使用 URL,我们一定要避免多次转化而导致的多次编码问题。
以上即为这节课的重点,其实都不难,先掌握了然后灵活变通就好。
思考题
当我们比较案例 1 和案例 2,你会发现不管使用的是查询(Query)参数还是表单(Form)参数,我们的接口定义并没有什么变化,风格如下: @RestController public class HelloWorldController { @RequestMapping(path = “hi”, method = RequestMethod.GET) public String hi(@RequestParam(“para1”) String para1){ return “helloworld:” + para1; }; }
那是不是 @RequestParam 本身就能处理这两种数据呢?
期待你的思考,我们留言区见!
参考资料
https://learn.lianglianglee.com/%e4%b8%93%e6%a0%8f/Spring%e7%bc%96%e7%a8%8b%e5%b8%b8%e8%a7%81%e9%94%99%e8%af%af50%e4%be%8b/21%20Spring%20Rest%20Template%20%e5%b8%b8%e8%a7%81%e9%94%99%e8%af%af.md
更多学习
更多实时资讯,前沿技术,生活趣事。尽在【老马啸西风】
交流社群:[交流群信息](https://mp.weixin.qq.com/s/rkSvXxiiLGjl3S-ZOZCr0Q)