Spring MVC内置支持的4种内容协商方式【享学Spring MVC】

时间  2019-11-16
标签 spring mvc 内置 支持 内容 协商 方式 享学Spring MVC 栏目 Spring 繁體版
原文   原文链接

每篇一句

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

前言

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

@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实现了它而且扩展了它更为强大~）。java

定义

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

方式

http的内容协商方式大体有两种：web

  1. 服务端将可用列表（本身能提供的MIME类型们）发给客户端，客户端选择后再告诉服务端。这样服务端再按照客户端告诉的MIME返给它。（缺点：多一次网络交互，并且使用对使用者要求高，因此此方式通常不用）

  2. （经常使用）客户端发请求时就指明须要的MIME们（好比Http头部的：Accept），服务端根据客户端指定的要求返回合适的形式，而且在响应头中作出说明（如：Content-Type）json

    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）segmentfault

报头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服务器

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加入以下两个包：

<!-- 此处须要导入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.xml解析出来的MediaType是application/xml
二、拿着这个MediaType（固然还有URL、请求Method等全部）去匹配HandlerMethod的时候会发现producers匹配不上
三、匹配不上就交给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));
        }
    }

四、抛出异常后最终交给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），但在实际应用中其实不多用它，由于不一样的浏览器可能致使不一样的行为（好比Chrome和Firefox就很不同），因此为了保证“稳定性”通常都选择使用方案二或方案三（好比Spring的官方doc）。

相关阅读

【小家Spring】Spring MVC容器的web九大组件之---HandlerMapping源码详解(二)---RequestMappingHandlerMapping系列

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

知识交流

==The last：若是以为本文对你有帮助，不妨点个赞呗。固然分享到你的朋友圈让更多小伙伴看到也是被做者本人许可的~==

**若对技术内容感兴趣能够加入wx群交流：Java高工、架构师3群。
若群二维码失效，请加wx号：fsx641385712（或者扫描下方wx二维码）。而且备注："java入群" 字样，会手动邀请入群**==若对Spring、SpringBoot、MyBatis等源码分析感兴趣，可加我wx：fsx641385712，手动邀请你入群一块儿飞==

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程