ContentNegotiation内容协商机制(一)---Spring MVC内置支持的4种内容协商方式【享学Spring MVC】

墨蓝 2024-04-17 05:34 29阅读 0赞

#### 每篇一句 ####

> 十个光头九个富，最后一个会砍树

#### 前言 ####

不知你在使用`Spring Boot`时是否对这样一个现象"诧异"过：`同一个`接口（同一个URL）在接口报错情况下，若你用rest访问，它返回给你的是一个`json`串；但若你用浏览器访问，它返回给你的是一段`html`。恰如下面例子（`Spring Boot`环境~）：

@RestController
    @RequestMapping
    public class HelloController { 
        @GetMapping("/test/error")
        public Object testError() { 
            System.out.println(1 / 0); // 强制抛出异常
            return "hello world";
        }
    }

使用浏览器访问：`http://localhost:8080/test/error`  
![在这里插入图片描述][20190824122527790.png]  
使用Postman访问：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70]  
同根不同命有木有。`RESTful`服务中很重要的一个特性是：**同一资源可以有多种表述，这就是我们今天文章的主题：内容协商(`ContentNegotiation`)。**

## HTTP内容协商 ##

虽然本文主要是想说`Spring MVC`中的内容协商机制，但是在此之前是很有必要先了解`HTTP`的内容协商是怎么回事（`Spring MVC`实现了它并且扩展了它更为强大~）。

##### 定义 #####

一个`URL资源`服务端可以以多种形式进行响应：即MIME（`MediaType`）媒体类型。但对于**某一个**客户端（浏览器、APP、Excel导出…）来说它只需要一种。so这样客户端和服务端就得有**一种机制**来保证这个事情，这种机制就是内容协商机制。

##### 方式 #####

`http`的内容协商方式大致有两种：

1.  服务端将可用列表（自己能提供的MIME类型们）发给客户端，客户端选择后再告诉服务端。这样服务端再按照客户端告诉的MIME返给它。（缺点：多一次网络交互，而且使用对使用者要求高，所以**此方式一般不用**）
2.  （**常用**）客户端发请求时就指明需要的`MIME`们（比如`Http`头部的：`Accept`），服务端根据客户端指定的要求返回合适的形式，并且在响应头中做出说明（如：`Content-Type`）  
    1. 若客户端要求的MIME类型服务端提供不了，那就406错误吧~

##### 常用请求头、响应头 #####

请求头  
`Accept`：告诉服务端需要的MIME（一般是多个，比如`text/plain`，`application/json`等。\*/\*表示可以是任何MIME资源）  
`Accept-Language`：告诉服务端需要的语言（在中国默认是中文嘛，但浏览器一般都可以选择N多种语言，但是是否支持要看服务器是否可以协商）  
`Accept-Charset`：告诉服务端需要的字符集  
`Accept-Encoding`：告诉服务端需要的压缩方式（gzip,deflate,br）  
响应头  
`Content-Type`：告诉客户端响应的媒体类型（如`application/json`、`text/html`等）  
`Content-Language`：告诉客户端响应的语言  
`Content-Charset`：告诉客户端响应的字符集  
`Content-Encoding`：告诉客户端响应的压缩方式（gzip）

###### 报头`Accept`与`Content-Type`的区别 ######

有很多文章粗暴的解释：`Accept`属于请求头，`Content-Type`属于响应头，其实这是不准确的。  
在前后端分离开发成为主流的今天，你应该不乏见到前端的request请求上大都有`Content-Type：application/json;charset=utf-8`这个请求头，因此可见`Content-Type`并不仅仅是响应头。

HTTP协议规范的格式如下**四部分**：

1.  ＜request-line＞(请求消息行)
2.  ＜headers＞(请求消息头)
3.  ＜blank line＞(请求空白行)
4.  ＜request-body＞(请求消息体)

`Content-Type`指**请求消息体**的数据格式，因为**请求和响应中都可以有消息体**，所以它即可用在请求头，亦可用在响应头。  
关于更多Http中的`Content-Type`的内容，我推荐参见此文章：[Http请求中的Content-Type][Http_Content-Type]

--------------------

## Spring MVC内容协商 ##

`Spring MVC`实现了`HTTP`内容协商的同时，又进行了扩展。它支持4种协商方式：

1.  `HTTP`头`Accept`
2.  扩展名
3.  请求参数
4.  固定类型（producers）

> 说明：以下示例基于Spring进行演示，而非`Spring Boot`

#### 方式一：HTTP头`Accept` ####

@RestController
    @RequestMapping
    public class HelloController { 
        @ResponseBody
        @GetMapping("/test/{id}")
        public Person test(@PathVariable(required = false) String id) { 
            System.out.println("id的值为：" + id);
            Person person = new Person();
            person.setName("fsx");
            person.setAge(18);
            return person;
        }
    }

如果默认就这样，不管浏览器访问还是Postman访问，得到的**都是json串**。

但若你仅仅只需在`pom`加入如下两个包：

<dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.9.8</version>
    </dependency>
    
    <dependency>
        <groupId>com.fasterxml.jackson.dataformat</groupId>
        <artifactId>jackson-dataformat-xml</artifactId>
        <version>2.9.8</version>
    </dependency>

再用**浏览器/Postman**访问，得到结果就是xml了，形如这样：  
![在这里插入图片描述][20190825145404663.png]

> 有的文章说：浏览器是xml，postman是json。本人亲试：都是xml。

但若我们`postman`手动指定这个头：`Accept：application/json`，返回就和浏览器有差异了（若不手动指定，`Accept`默认值是`*/*`）：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70 1]  
并且我们可以看到`response`的头信息对比如下：  
手动指定了`Accept：application/json`：  
![在这里插入图片描述][20190825152341955.png]  
木有指定Accept（默认`*/*`）：  
![在这里插入图片描述][20190825152251547.png]

###### 原因简析 ######

`Chrome`浏览器请求默认发出的`Accept`是：`Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3`。  
由于我例子使用的是`@ResponseBody`，因此它不会返回一个view：交给消息转换器处理，因此这就和`MediaType`以及权重有关了。

消息最终都会交给`AbstractMessageConverterMethodProcessor.writeWithMessageConverters()`方法：

// @since 3.1
    AbstractMessageConverterMethodProcessor：
    	protected <T> void writeWithMessageConverters( ... ) { 
    		Object body;
    		Class<?> valueType;
    		Type targetType;
    		...
    		HttpServletRequest request = inputMessage.getServletRequest();
    		// 这里交给contentNegotiationManager.resolveMediaTypes() 找出客户端可以接受的MediaType们~~~
    		// 此处是已经排序好的（根据Q值等等）
    		List<MediaType> acceptableTypes = getAcceptableMediaTypes(request);
    		// 这是服务端它所能提供出的MediaType们
    		List<MediaType> producibleTypes = getProducibleMediaTypes(request, valueType, targetType);
    	
    		// 协商。 经过一定的排序、匹配 最终匹配出一个合适的MediaType
    		...
    		// 把待使用的们再次排序，
    		MediaType.sortBySpecificityAndQuality(mediaTypesToUse);
    
    		// 最终找出一个最合适的、最终使用的：selectedMediaType 
    			for (MediaType mediaType : mediaTypesToUse) { 
    				if (mediaType.isConcrete()) { 
    					selectedMediaType = mediaType;
    					break;
    				} else if (mediaType.isPresentIn(ALL_APPLICATION_MEDIA_TYPES)) { 
    					selectedMediaType = MediaType.APPLICATION_OCTET_STREAM;
    					break;
    				}
    			}
    	}

`acceptableTypes`是客户端通过`Accept`告知的。  
`producibleTypes`代表着服务端所能提供的类型们。参考这个`getProducibleMediaTypes()`方法：

AbstractMessageConverterMethodProcessor：
    
    	protected List<MediaType> getProducibleMediaTypes( ... ) { 
    		// 它设值的地方唯一在于：@RequestMapping.producers属性
    		// 大多数情况下：我们一般都不会给此属性赋值吧~~~
    		Set<MediaType> mediaTypes = (Set<MediaType>) request.getAttribute(HandlerMapping.PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE);
    		if (!CollectionUtils.isEmpty(mediaTypes)) { 
    			return new ArrayList<>(mediaTypes);
    		}
    		// 大多数情况下：都会走进这个逻辑 --> 从消息转换器中匹配一个合适的出来
    		else if (!this.allSupportedMediaTypes.isEmpty()) { 
    			List<MediaType> result = new ArrayList<>();
    			// 从所有的消息转换器中 匹配出一个/多个List<MediaType> result出来
    			// 这就代表着：我服务端所能支持的所有的List<MediaType>们了
    			for (HttpMessageConverter<?> converter : this.messageConverters) { 
    				if (converter instanceof GenericHttpMessageConverter && targetType != null) { 
    					if (((GenericHttpMessageConverter<?>) converter).canWrite(targetType, valueClass, null)) { 
    						result.addAll(converter.getSupportedMediaTypes());
    					}
    				}
    				else if (converter.canWrite(valueClass, null)) { 
    					result.addAll(converter.getSupportedMediaTypes());
    				}
    			}
    			return result;
    		} else {  
    			return Collections.singletonList(MediaType.ALL);
    		}
    	}

可以看到服务端最终能够提供哪些`MediaType`，来源于消息转换器`HttpMessageConverter`对类型的支持。  
本例的现象：起初返回的是json串，仅仅只需要导入`jackson-dataformat-xml`后就返回`xml`了。原因是因为加入`MappingJackson2XmlHttpMessageConverter`都有这个判断：

private static final boolean jackson2XmlPresent = ClassUtils.isPresent("com.fasterxml.jackson.dataformat.xml.XmlMapper", classLoader);
    	
    		if (jackson2XmlPresent) { 
    			addPartConverter(new MappingJackson2XmlHttpMessageConverter());
    		}

所以默认情况下`Spring MVC`并不支持`application/xml`这种媒体格式，所以若不导包协商出来的结果是：`application/json`。

> 默认情况下优先级是xml高于json。当然一般都木有xml包，所以才轮到json的。

另外还需要注意一点：有的小伙伴说通过在请求头里指定`Content-Type：application/json`来达到效果。现在你应该知道，这样做显然是没用的（至于为何没用，希望读者做到了心知肚明），只能使用`Accept`这个头来指定~~~

第一种协商方式是`Spring MVC`完全基于`HTTP Accept`首部的方式了。该种方式`Spring MVC`默认支持且默认已开启。  
**优缺点：**

*  优点：理想的标准方式
 *  缺点：由于浏览器的差异，导致发送的Accept Header头可能会不一样，从而得到的结果不具备浏览器兼容性

#### 方式二：（变量）扩展名 ####

基于上面例子：若我访问`/test/1.xml`返回的是xml，若访问`/test/1.json`返回的是json；完美~

**这种方式使用起来非常的便捷，并且还不依赖于浏览器**。但我总结了如下几点使时的注意事项：

1.  扩展名必须是**变量**的扩展名。比如上例若访问`test.json / test.xml`就404~
2.  `@PathVariable`的参数类型只能使用通用类型（`String/Object`），因为接收过来的value值就是`1.json/1.xml`，所以若用`Integer`接收将报错类型转换错误~  
    1. 小技巧：我个人建议是这部分不接收（这部分不使用`@PathVariable`接收），拿出来**只为内容协商使用**
3.  **扩展名优先级比Accept要高**（并且和使用神马浏览器无关）

**优缺点：**

*  优点：灵活，不受浏览器约束
 *  缺点：丧失了同一URL的多种展现方式。在实际环境中使用还是较多的，因为这种方式更符合程序员的习惯

#### 方式三：请求参数 ####

这种协商方式`Spring MVC`支持，但默认是关闭的，需要显示的打开：

@Configuration
    @EnableWebMvc
    public class WebMvcConfig extends WebMvcConfigurerAdapter { 
        @Override
        public void configureContentNegotiation(ContentNegotiationConfigurer configurer) { 
        	// 支持请求参数协商
            configurer.favorParameter(true);
        }
    }

请求URL：`/test/1?format=xml`返回xml；`/test/1?format=json`返回json。同样的我总结如下几点注意事项：

1.  前两种方式默认是开启的，但此种方式需要**手动显示开启**
2.  此方式优先级`低于`扩展名（因此你测试时若想它生效，请去掉url的后缀）

**优缺点：**

*  优点：不受浏览器约束
 *  缺点：需要额外的传递format参数，URL变得冗余繁琐，缺少了REST的简洁风范。还有个缺点便是：还需手动显示开启。

##### 方式四：固定类型（produces） #####

它就是利用`@RequestMapping`注解属性`produces`（可能你平时也在用，但并不知道原因）：

@ResponseBody
    @GetMapping(value = { "/test/{id}", "/test"}, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public Person test() {  ... }

访问：`/test/1`返回的就是json；即使你已经导入了jackson的xml包，返回的依旧还是json。

它也有它很很很重要的一个注意事项：**`produces`指定的`MediaType`类型不能和后缀、请求参数、Accept冲突**。例如本利这里指定了`json`格式，如果你这么访问`/test/1.xml`，或者`format=xml`，或者`Accept`不是`application/json或者*/*` 将无法完成内容协商：http状态码为406，报错如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70 2]  
`produces`使用固然也比较简单，针对上面报错406的原因，我简单解释如下。

###### 原因： ######

1、先解析请求的媒体类型：`1.xml`解析出来的`MediaType`是`application/xml`  
2、拿着这个`MediaType`（当然还有URL、请求Method等所有）去匹配`HandlerMethod`的时候会发现`producers`匹配不上  
3、匹配不上就交给`RequestMappingInfoHandlerMapping.handleNoMatch()`处理：

RequestMappingInfoHandlerMapping：
    
    	@Override
    	protected HandlerMethod handleNoMatch(...) { 
    		if (helper.hasConsumesMismatch()) { 
    			...
    			throw new HttpMediaTypeNotSupportedException(contentType, new ArrayList<>(mediaTypes));
    		}
    		// 抛出异常：HttpMediaTypeNotAcceptableException
    		if (helper.hasProducesMismatch()) { 
    			Set<MediaType> mediaTypes = helper.getProducibleMediaTypes();
    			throw new HttpMediaTypeNotAcceptableException(new ArrayList<>(mediaTypes));
    		}
    	}

4、抛出异常后最终交给`DispatcherServlet.processHandlerException()`去处理这个异常，转换到`Http`状态码

> 会调用所有的`handlerExceptionResolvers`来处理这个异常，本处会被`DefaultHandlerExceptionResolver`最终处理。最终处理代码如下（406状态码）：

protected ModelAndView handleHttpMediaTypeNotAcceptable(HttpMediaTypeNotAcceptableException ex,
    			HttpServletRequest request, HttpServletResponse response, @Nullable Object handler) throws IOException { 
    
    		response.sendError(HttpServletResponse.SC_NOT_ACCEPTABLE);
    		return new ModelAndView();
    	}

> `Spring MVC`默认注册的异常处理器是如下3个：  
> ![在这里插入图片描述][20190826200412502.png]

###### 原理 ######

有了关于`Accept`的原理描述，理解它就非常简单了。因为指定了`produces`属性，所以`getProducibleMediaTypes()`方法在拿服务端支持的媒体类型时：

protected List<MediaType> getProducibleMediaTypes( ... ){ 
    	Set<MediaType> mediaTypes = (Set<MediaType>) request.getAttribute(HandlerMapping.PRODUCIBLE_MEDIA_TYPES_ATTRIBUTE);
    	if (!CollectionUtils.isEmpty(mediaTypes)) { 
    		return new ArrayList<>(mediaTypes);
    	}
    	...
    }

因为设置了`producers`，所以代码第一句就能拿到值了（后面的协商机制完全同上）。

> 备注：若produces属性你要指定的非常多，建议可以使用`!xxx`语法，它是支持这种语法（排除语法）的~

**优缺点：**

*  优点：使用简单，天然支持
 *  缺点：让`HandlerMethod`处理器缺失灵活性

##### Spring Boot默认异常消息处理 #####

再回到开头的`Spring Boot`为何对异常消息，浏览器和postman的展示不一样。这就是`Spring Boot`默认的对异常处理方式：它使用的就是基于 固定类型(produces)实现的内容协商。

`Spirng Boot`出现异常信息时候，会**默认**访问`/error`,它的处理类是：`BasicErrorController`

@Controller
    @RequestMapping("${server.error.path:${error.path:/error}}")
    public class BasicErrorController extends AbstractErrorController { 
    	...
    	// 处理类浏览器
    	@RequestMapping(produces = "text/html")
    	public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) { 
    		... 
    		return (modelAndView != null ? modelAndView : new ModelAndView("error", model));
    	}
    
    	// 处理restful/json方式
    	@RequestMapping
    	@ResponseBody
    	public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) { 
    		Map<String, Object> body = getErrorAttributes(request, isIncludeStackTrace(request, MediaType.ALL));
    		HttpStatus status = getStatus(request);
    		return new ResponseEntity<Map<String, Object>>(body, status);
    	}
    	...
    }

有了上面的解释，对这块代码的理解应该就没有盲点了~

#### 总结 ####

内容协商在`RESTful`流行的今天还是非常重要的一块内容，它对于提升用户体验，提升效率和降低维护成本都有不可忽视的作用，注意它三的优先级为：**后缀 > 请求参数 > HTTP首部Accept**

一般情况下，我们为了通用都会使用基于Http的内容协商（Accept），但在实际应用中其实很少用它，因为不同的浏览器可能导致不同的行为（比如`Chrome`和`Firefox`就很不一样），**所以为了保证“稳定性”一般都选择使用方案二或方案三（比如Spring的官方doc）**。

#### 相关阅读 ####

[ContentNegotiation内容协商机制(一)—Spring MVC内置支持的4种内容协商方式【享学Spring MVC】][ContentNegotiation_Spring MVC_4_Spring MVC]  
[ContentNegotiation内容协商机制(二)—Spring MVC内容协商实现原理及自定义配置【享学Spring MVC】][ContentNegotiation_Spring MVC_Spring MVC]  
[ContentNegotiation内容协商机制(三)—在视图View上的应用：ContentNegotiatingViewResolver深度解析【享学Spring MVC】][ContentNegotiation_View_ContentNegotiatingViewResolver_Spring MVC]

--------------------

# 关注A哥 #

<table> 
 <thead> 
  <tr> 
   <th>Author</th> 
   <th><a href="https://www.yourbatman.cn/about" rel="nofollow">A哥(YourBatman)</a></th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>个人站点</td> 
   <td><a href="https://www.yourbatman.cn" rel="nofollow">www.yourbatman.cn</a></td> 
  </tr> 
  <tr> 
   <td>E-mail</td> 
   <td>yourbatman@qq.com</td> 
  </tr> 
  <tr> 
   <td><strong>微 信</strong></td> 
   <td><a href="https://www.yourbatman.cn/images/wechat.png" rel="nofollow">fsx641385712</a></td> 
  </tr> 
  <tr> 
   <td><strong><code>活跃平台</code></strong></td> 
   <td><a href="https://www.yourbatman.cn" rel="nofollow"><img src="https://img-blog.csdnimg.cn/2020071015182276.png" alt=""></a> <a href="https://fangshixiang.blog.csdn.net/" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710151913394.png" alt=""></a><a href="https://yourbatman.cnblogs.com" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710151929355.png" alt=""></a><a href="https://juejin.im/user/5b44d178f265da0fa1220efe/posts" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710151938937.png" alt=""></a><a href="https://www.zhihu.com/people/fangshixiang/posts" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710151950629.png" alt=""></a><a href="https://www.jianshu.com/u/8740f1fdd684" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710152000530.png" alt=""></a><a href="https://segmentfault.com/u/yourbatman/articles" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710152008726.png" alt=""></a><a href="https://github.com/yourbatman" rel="nofollow"><img src="https://img-blog.csdnimg.cn/20200710152015895.png" alt=""></a></td> 
  </tr> 
  <tr> 
   <td><strong>公众号</strong></td> 
   <td><a href="https://www.yourbatman.cn/images/wechat_channel.jpg" rel="nofollow">BAT的乌托邦（ID：BAT-utopia）</a></td> 
  </tr> 
  <tr> 
   <td>知识星球</td> 
   <td><a href="https://t.zsxq.com/nQBi66I" rel="nofollow">BAT的乌托邦</a></td> 
  </tr> 
  <tr> 
   <td>每日文章推荐</td> 
   <td><a href="https://github.com/yourbatman/reading/issues" rel="nofollow">每日文章推荐</a></td> 
  </tr> 
 </tbody> 
</table>

![BAT的乌托邦][BAT]

[20190824122527790.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/a38cb7f13b564ffdb34989ca0c84c318.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/a27ec1f56f904ff09f3ea3403eb376cd.png
[Http_Content-Type]: https://segmentfault.com/a/1190000013056786
[20190825145404663.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/3a9c0e02de864fc4a2a3eb1abe5ae39b.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/361b7300e19c49bd916b410e755d1c93.png
[20190825152341955.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/ec3981ff635f4abd8bcfa795484ab30a.png
[20190825152251547.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/953da0d22f0b4a41bec6439182eba341.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L2Y2NDEzODU3MTI_size_16_color_FFFFFF_t_70 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/a6d42f809c28413885cd9671b7d5981c.png
[20190826200412502.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/0266acfbea674bf4bf68a2355c4c6d6a.png
[ContentNegotiation_Spring MVC_4_Spring MVC]: https://blog.csdn.net/f641385712/article/details/100020664
[ContentNegotiation_Spring MVC_Spring MVC]: https://blog.csdn.net/f641385712/article/details/100060445
[ContentNegotiation_View_ContentNegotiatingViewResolver_Spring MVC]: https://blog.csdn.net/f641385712/article/details/100079806
[BAT]: https://image.dandelioncloud.cn/pgy_files/images/2024/04/11/64a073a194ff423e820063e2757ddbcf.gif