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

前言

不知你在使用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

使用Postman访问:

同根不同命有木有。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/plainapplication/json等。*/*表示可以是任何MIME资源) Accept-Language:告诉服务端需要的语言(在中国默认是中文嘛,但浏览器一般都可以选择N多种语言,但是是否支持要看服务器是否可以协商) Accept-Charset:告诉服务端需要的字符集 Accept-Encoding:告诉服务端需要的压缩方式(gzip,deflate,br) 响应头 Content-Type:告诉客户端响应的媒体类型(如application/jsontext/html等) Content-Language:告诉客户端响应的语言 Content-Charset:告诉客户端响应的字符集 Content-Encoding:告诉客户端响应的压缩方式(gzip)

报头AcceptContent-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


Spring MVC内容协商

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

  1. HTTPAccept
  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加入如下两个包:

<!-- 此处需要导入databind包即可, jackson-annotations、jackson-core都不需要显示自己的导入了-->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.8</version>
</dependency>
<!-- jackson默认只会支持的json。若要xml的支持,需要额外导入如下包 -->
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.9.8</version>
</dependency>

再用浏览器/Postman访问,得到结果就是xml了,形如这样:

有的文章说:浏览器是xml,postman是json。本人亲试:都是xml。

但若我们postman手动指定这个头:Accept:application/json,返回就和浏览器有差异了(若不手动指定,Accept默认值是*/*):

并且我们可以看到response的头信息对比如下: 手动指定了Accept:application/json

木有指定Accept(默认*/*):

原因简析

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,报错如下:

produces使用固然也比较简单,针对上面报错406的原因,我简单解释如下。

原因:

1、先解析请求的媒体类型:1.xml解析出来的MediaTypeapplication/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个:

原理

有了关于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),但在实际应用中其实很少用它,因为不同的浏览器可能导致不同的行为(比如ChromeFirefox就很不一样),所以为了保证“稳定性”一般都选择使用方案二或方案三(比如Spring的官方doc)

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏java老实人

java学习笔记(中级篇)—细说mybatis的使用方式

我这里就直接创建一个简单的java项目了,这要求先要下载好mybatis-3.x.0.jar,然后把包导进项目,因为要连接数据库,所以还需要数据库驱动包,我用的...

5400
来自专栏Android小知识

CLEARTEXT communication to *** not permitted by network security policy

30720
来自专栏Java大联盟

Java 中的注解到底是如何工作的?

自Java5.0版本引入注解之后,它就成为了Java平台中非常重要的一部分。开发过程中,我们也时常在应用代码中会看到诸如@Override,@Deprecate...

8140
来自专栏程序亦非猿

【连载】聊聊 APK(三) —— Android 资源编译的秘密

上两期我们讲了 APK 里面 Dex 的东西,明白了 Dex 只是 classes 的某种打包形式,我们暂时不拘泥于细节,关于代码的部分就告一段落。我们知道除了...

14020
来自专栏程序亦非猿

Android 架构组件 - 让天下没有难做的 App

本文转载自我的好基友老梁老司机,一文带你领略AAC的魅力。 Google 为了帮助 Android 开发者更快更好地开发 App,推出了一系列组件,这些组件被...

14220
来自专栏流川疯编写程序的艺术

基于soap 的python 的web services 服务

web services 已经不再流行,但是,由于它的在接口技术中有着非常重要的地位,同时现在最主要的Web 服务设计模型REST其实也属于web servic...

15510
来自专栏IT那个小笔记

Servlet简述

编写程序时, 不需要有main函数了。因为写完后,就把编写的程序编译成字节码,放到服务器上面。当前发送就一个请求的时候,服务器就会按照一定规则调用编写的代码

10140
来自专栏java技术大本营

tomcat学习|tomat中的server.xml的学习

小刀博客: https://www.lixiang.red 小刀公众号: 程序员学习大本营

6540
来自专栏每天学点Android知识

让View跟随状态动起来——StateListAnimator

StateListAnimator定义了一组动画,可以根据View drawable的状态进行不同的切换。所谓状态指的是statepressed、stateen...

15420
来自专栏老码农的一亩三分地

《细说PHP》第四版 样章 第二章 PHP的应用与发展 1

学习任何编程语言之前,先了解一下它的应用与发展是很有必要的。从Web开发的历史看来,PHP、Python和Ruby几乎是同时出现的,都是十分有特点、优秀的开源语...

9710

扫码关注云+社区

领取腾讯云代金券

年度创作总结 领取年终奖励