Web MVC

1. Spring Web MVC

Spring Web MVC是构建在Servlet API上的原始Web框架，从一开始就包含在Spring Framework中。 正式名称 “Spring Web MVC,” 来自其源模块(spring-webmvc)的名称，但它通常被称为“Spring MVC”。

与Spring Web MVC并行，Spring Framework 5.0引入了一个反应堆栈Web框架，其名称“Spring WebFlux,”也基于其源模块(spring-webflux)。 本节介绍Spring Web MVC。 下一节将介绍Spring WebFlux。.

有关基本信息以及与Servlet容器和Java EE版本范围的兼容性，请参阅Spring Framework Wiki。

1.1. DispatcherServlet

与Spring WebFlux相同

Spring MVC和许多其他Web框架一样，围绕前端控制器模式设计，其中核心 Servlet``DispatcherServlet为请求处理提供共享算法，而实际工作由可配置委托组件执行。 该模型非常灵活，支持多种工作流程。

DispatcherServlet与任何 Servlet一样，需要使用Java配置或 web.xml根据Servlet规范进行声明和映射。 反过来，DispatcherServlet使用Spring配置来发现请求映射，视图解析，异常处理 等等所需的委托组件。

下面的Java配置示例注册并初始化DispatcherServlet，它由Servlet容器自动检测（请参阅Servlet Config）：

public class MyWebApplicationInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext servletCxt) {

        // Load Spring web application configuration
        AnnotationConfigWebApplicationContext ac = new AnnotationConfigWebApplicationContext();
        ac.register(AppConfig.class);
        ac.refresh();

        // Create and register the DispatcherServlet
        DispatcherServlet servlet = new DispatcherServlet(ac);
        ServletRegistration.Dynamic registration = servletCxt.addServlet("app", servlet);
        registration.setLoadOnStartup(1);
        registration.addMapping("/app/*");
    }
}

除了直接使用ServletContext API之外，您还可以扩展AbstractAnnotationConfigDispatcherServletInitializer 并覆盖特定方法（请参阅Context Hierarchy下的示例）。

以下web.xml配置示例注册并初始化DispatcherServlet:

<web-app>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/app-context.xml</param-value>
    </context-param>

    <servlet>
        <servlet-name>app</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value></param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>app</servlet-name>
        <url-pattern>/app/*</url-pattern>
    </servlet-mapping>

</web-app>

Spring Boot遵循不同的初始化顺序。 Spring Boot使用Spring配置来引导自身和嵌入式Servlet容器，而不是挂钩到Servlet容器的生命周期。 在Spring配置中检测Filter 和Servlet声明，并在Servlet容器中注册。 有关更多详细信息，请参阅[Spring Boot

documentation](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-embedded-container)文档。

1.1.1. 上下文层次结构

DispatcherServlet需要一个 WebApplicationContext（ApplicationContext的扩展）来配置自己。 WebApplicationContext有一个指向ServletContext的链接以及与之关联的 Servlet。 它还绑定到ServletContext，当需要访问它时，应用程序可以使用RequestContextUtils上的静态方法来查找WebApplicationContext。

对于许多应用程序，拥有一个简单的 WebApplicationContext已经足够了。它也有一个上下文层次结构，其中根WebApplicationContext在多个 DispatcherServlet（或其他 Servlet）实例之间共享， 每个实例都有自己的子WebApplicationContext配置。 有关上下文层次结构功能的更多信息，请参阅ApplicationContext的其他功能。

根WebApplicationContext通常包含bean基础结构，例如需要跨多个Servlet实例共享的数据存储库和业务服务。 这些bean被有效继承，可以在特定于 Servlet的子WebApplicationContext中重写（即重新声明），它通常包含给定Servlet本地的bean。 下图显示了这种关系：

以下示例配置WebApplicationContext层次结构:

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class<?>[] { RootConfig.class };
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[] { App1Config.class };
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/app1/*" };
    }
}

如果不需要应用程序上下文层次结构，则应用程序可以通过getRootConfigClasses() 返回所有配置，并从getServletConfigClasses()返回null。

以下示例显示了web.xml配置（和上面效果一样）:

<web-app>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/root-context.xml</param-value>
    </context-param>

    <servlet>
        <servlet-name>app1</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/app1-context.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>app1</servlet-name>
        <url-pattern>/app1/*</url-pattern>
    </servlet-mapping>

</web-app>

如果不需要应用程序上下文层次结构，则应用程序可以仅配置“root”上下文，并将 contextConfigLocation Servlet参数保留为空。

1.1.2. 特殊的Bean类型

Same as in Spring WebFlux

DispatcherServlet 委托特殊bean处理请求并渲染视图。 “特殊bean”是指实现WebFlux框架的Spring管理的Object实例。 这些通常带有内置联系，但您可以自定义其属性并扩展或替换它们。

下表列出了DispatcherHandler检测到的特殊bean:

1.1.3. Web MVC 配置

Same as in Spring WebFlux

对于每种类型的特殊bean， DispatcherServlet首先会检查WebApplicationContext。如果没有匹配的bean类型，则会退回检查DispatcherServlet.properties。

在大多数情况下，MVC Config是最佳起点。 它以Java或XML声明所需的bean，并提供更高级别的配置回调API来自定义它。

Spring Boot依赖于MVC Java配置来配置Spring MVC并提供许多额外的便捷选项。

1.1.4. Servlet 配置

在Servlet 3.0+环境中，您可以选择以编程方式配置Servlet容器作为替代方法，也可以与web.xml文件结合使用。 以下示例注册DispatcherServlet:

import org.springframework.web.WebApplicationInitializer;

public class MyWebApplicationInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext container) {
        XmlWebApplicationContext appContext = new XmlWebApplicationContext();
        appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");

        ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet(appContext));
        registration.setLoadOnStartup(1);
        registration.addMapping("/");
    }
}

WebApplicationInitializer是Spring MVC提供的一个接口，实现此接口的任何Servlet 3容器都可被检测到并自动初始化。 AbstractDispatcherServletInitializer抽象类实现了WebApplicationInitializer接口，通过重写方法来指定servlet映射和DispatcherServlet 配置的地址， 从而更方便的注册DispatcherServlet。

对于使用基于Java的Spring配置的应用程序，建议使用此方法，如以下示例所示:

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return null;
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[] { MyWebConfig.class };
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/" };
    }
}

如果使用基于XML的Spring配置，则应直接从AbstractDispatcherServletInitializer扩展，如以下示例所示:

public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {

    @Override
    protected WebApplicationContext createRootApplicationContext() {
        return null;
    }

    @Override
    protected WebApplicationContext createServletApplicationContext() {
        XmlWebApplicationContext cxt = new XmlWebApplicationContext();
        cxt.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");
        return cxt;
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/" };
    }
}

AbstractDispatcherServletInitializer还提供了一种便捷的方法来添加Filter实例并将它们自动映射到DispatcherServlet，如以下示例所示：

public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {

    // ...

    @Override
    protected Filter[] getServletFilters() {
        return new Filter[] {
            new HiddenHttpMethodFilter(), new CharacterEncodingFilter() };
    }
}

每个过滤器都根据其具体类型添加默认名称，并自动映射到DispatcherServlet。

AbstractDispatcherServletInitializer的protected方法isAsyncSupported提供了一个单独的地址来启用DispatcherServlet 上的异步支持以及映射到它的所有过滤器。 默认情况下，此标志设置为true。

最后，如果您需要进一步自定义DispatcherServlet本身，则可以覆盖createDispatcherServlet方法。

1.1.5. 处理流程

Same as in Spring WebFlux

DispatcherServlet按如下方式处理请求：

• 首先，搜索应用的上下文对象WebApplicationContext，并把它作为一个属性（attribute)绑定到该请求上。以便让控制器和其他组件能使用它。 属性的键名默认为DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE。

• 将locale resolver绑定到请求上，并允许其他组件解析处理请求时使用的语言环境（渲染视图，准备数据等）。 如果您不需要区域解析，则不需要locale resolver。

• 将theme resolver 绑定到请求，以允许视图等组件确定要使用的themes。 如果您不使用themes，则可以忽略它。

• 如果指定multipart 文件处理器，则会检查请求的文件是不是multiparts的， 如果是，请求将包装在MultipartHttpServletRequest中， 以便其他组件进一步处理。 有关Multipart Resolver的更多信息，请参见Multipart Resolver。

• 为该请求查找一个合适的处理器。 如果找到处理程序，则与该处理器关联的整条执行链（前处理器、后处理器、控制器等）都会被执行，以完成相应模型的准备或视图的渲染。 或者，对于带注解的控制器，可以显示响应（在 HandlerAdapter中）而不是返回视图。

• 如果处理器返回模型，则渲染视图。 如果没有返回模型（可能是由于前处理器或后处理器拦截请求，可能是出于安全原因），则不会渲染任何视图，因为该请求可能已经完成。

在 WebApplicationContext 中声明的HandlerExceptionResolver用于解决请求处理过程中引发的异常。这些异常解析程序允许使用自定义的逻辑来解决，有关详细信息，请参阅Exceptions 。

Spring的 DispatcherServlet也允许处理器返回Servlet API规范中定义的最后修改时间戳（last-modification-date）值。确定请求最后修改时间的方式是直截了当的： DispatcherServlet会先查找合适的处理映射来找到请求对应的处理器，然后检测它是否实现了 LastModified 接口。如果是的话，则调用接口的long getLastModified(request)方法，并将返回的值传回给客户端。

您可以自定义通过DispatcherServlet的配置。可以在web.xml文件中，声明元素Servlet的上添加Servlet的初始化参数（init-param元素）。 下表列出了支持的参数：

1.1.6. Interception

Spring的处理器映射机制包含了处理器拦截器，，可以实现 HandlerMapping，所有 HandlerMapping实现都支持处理拦截器，这些拦截器在需要为特定类型的请求应用一些功能时可能很有用非常有用， 例如，检查用户身份等，org.springframework.web.servlet包中的 HandlerInterceptor实现了三种方法，提供足够的灵活性来执行各种预处理和后处理：

• preHandle(..): 在执行实际处理程序之前

• postHandle(..): 在执行实际处理程序之后

• afterCompletion(..): 完成请求后

preHandle(..) 方法返回一个布尔值。 您可以使用此方法来中断或继续执行链的处理。 当此方法返回 true时，处理程序执行链继续。 当它返回false时，DispatcherServlet假定拦截器本身已处理请求（例如，呈现适当的视图）并且不继续执行执行链中的其他拦截器和实际处理程序。

有关如何配置Interceptors 的示例，请参阅MVC配置一节中的拦截器。 您还可以使用各个 HandlerMapping实现上的setter方法直接注册它们。

请注意，在HandlerAdapter和postHandle之前，响应被写入并提交。 postHandle对于@ResponseBody和ResponseEntity方法不太有用， 这意味着对响应进行任何更改都为时已晚，例如添加额外的header。 对于此类方案，您可以实现 ResponseBodyAdvice并将其声明为Controller Advicebean或直接在RequestMappingHandlerAdapter上进行配置。

1.1.7. 异常

Same as in Spring WebFlux

如果在请求映射期间发生异常或从请求处理程序（例如 @Controller）抛出异常， 则DispatcherServlet委托给 HandlerExceptionResolver bean来处理并解决异常，这通常是错误响应。

下表列出了可用的 HandlerExceptionResolver 实现：:

Table 2. HandlerExceptionResolver 实现 ：

解析链

您可以通过在Spring配置中声明多个 HandlerExceptionResolver bean并根据需要设置其顺序属性来形成异常解析链。 order属性越高，异常解析器定位的越晚。

HandlerExceptionResolver的约定指定它可以返回:

• 一个指向错误视图的 ModelAndView。

• 如果在解析程序中处理异常，则为空的ModelAndView。

• 如果异常仍未解析，则为 null，以供后续解析器尝试，如果异常保留在最后，则允许冒泡到Servlet容器。.

MVC Config自动声明内置的解析器，用于默认的Spring MVC异常，@ResponseStatus 带注解的异常，以及对@ExceptionHandler方法的支持。 您可以自定义该列表或替换它。

容器错误页面

如果任何HandlerExceptionResolver仍未解析异常，并且因此将其传播给servlet容器或者如果响应状态设置为错误状态（即4xx，5xx） ，则Servlet容器可以呈现HTML中的默认错误页面。 要自定义容器的默认错误页面，可以在 web.xml.中声明错误页面映射。 以下示例显示了如何执行此操作：

<error-page>
    <location>/error</location>
</error-page>

根据前面的示例，当异常冒泡或响应具有错误状态时，Servlet容器会在容器内对配置的URL进行ERROR调度（例如，/error）。 然后由DispatcherServlet处理，可能将其映射到 @Controller，可以实现该控件以返回带有模型的错误视图名称或呈现JSON响应，如以下示例所示：

@RestController
public class ErrorController {

    @RequestMapping(path = "/error")
    public Map<String, Object> handle(HttpServletRequest request) {
        Map<String, Object> map = new HashMap<String, Object>();
        map.put("status", request.getAttribute("javax.servlet.error.status_code"));
        map.put("reason", request.getAttribute("javax.servlet.error.message"));
        return map;
    }
}

Servlet API没有提供在Java中创建错误页面映射的方法。 但是，您可以同时使用WebApplicationInitializer和最小的 web.xml。

1.1.8. 视图解析

Same as in Spring WebFlux

Spring MVC定义了 ViewResolver和 View接口，使您可以在浏览器中呈现模型，而无需将您与特定的视图技术联系起来。 ViewResolver提供视图名称和实际视图之间的映射。 View接口负责准备请求，并将请求的渲染交给某种具体的视图技术实现。

下表提供了有关ViewResolver层次结构的更多详细信息：:

Table 3. ViewResolver 实现

处理

Same as in Spring WebFlux

您可以在视图解析器链中声明多个视图解析器，并在必要时通过设置 order属性来指定排序。 请记住，order属性越高，视图解析器在链中的位置越晚。 .

ViewResolver 可以返回null以指示无法找到该视图。 但是，对于JSP和InternalResourceViewResolver, 确定JSP是否存在的唯一方法是通过RequestDispatcher执行调度。 因此，您必须始终将InternalResourceViewResolver配置为视图解析器的整体顺序中的最后一个。

配置视图解析就像将ViewResolver bean添加到Spring配置一样简单。MVC Config为View Resolvers提供专用配置API，并添加无逻辑视图控制器（View Controllers ），这些控制器对于没有控制器逻辑的HTML模板渲染非常有用。

重定向

Same as in Spring WebFlux

您可以在视图中使用redirect:前缀来执行重定向。UrlBasedViewResolver（及其子类）将此识别为需要重定向的指令。 视图名称的其余部分是重定向URL。

控制器本身可以根据逻辑视图名称进行操作。 逻辑视图名称（例如redirect:/myapp/some/resource）相对于当前Servlet上下文重定向，而名称如redirect:http://myhost.com/some/arbitrary/path重定向到绝对URL。

请注意，如果使用@ResponseStatus注解控制器方法，则注解值优先于 RedirectView设置的响应状态。

转发

你也可以在视图名称中使用forward:前缀，来作为 UrlBasedViewResolver和其子类最终解析的视图名称。 这将创建一个 InternalResourceView，它执行RequestDispatcher.forward()。 因此，此前缀对于 InternalResourceViewResolver和InternalResourceView（对于JSP）没有用，但如果您使用其他视图技术时仍希望强制Servlet/JSP引擎处理资源的转发，则它可能会有所帮助。 请注意，您也可以链接多个视图解析器。

Content Negotiation

Same as in Spring WebFlux

ContentNegotiatingViewResolver本身不解析视图，而是委托给其他视图解析器，并选择类似于客户端请求的表示的视图。 可以从Accept头或查询参数（例如， "/path?format=pdf"）确定表示。

ContentNegotiatingViewResolver通过将请求的媒体类型与其每个ViewResolvers关联的View支持的媒体类型（也称为Content-Type）进行比较，选择适当的 View来处理请求。列表中具有兼容Content-Type的第一个View将表示返回给客户端。 如果 ViewResolver链无法提供兼容视图，则会查询通过DefaultViews 属性指定的视图列表。 后一个选项适用于单个视图，它可以呈现当前资源的适当表示，而不管逻辑视图名称如何。 Accept头可以包含通配符（例如text/*），在这种情况下，Content-Type为text/xml的View是兼容匹配。

有关配置详细信息，请参阅 MVC Config 下的View Resolvers 。

1.1.9. Locale

正如Spring Web MVC框架所做的那样，Spring架构的大多数部分都支持国际化。 DispatcherServlet允许您使用客户端的语言环境自动解析消息。 这是通过LocaleResolver对象完成的。

当请求进入时，DispatcherServlet 会查找当前语言环境解析器，如果找到，则会尝试使用它来设置语言环境。 您可以通过使用RequestContext.getLocale()方法，来获取由区域解析器解析到的结果。

除了自动解析语言环境之外，您还可以在处理程序时添加拦截器（有关拦截器的更多信息，请参阅Interception ），以便于在特定情况下更改语言环境。例如（通过请求中的参数来改变语言环境）

区域解析器和拦截器在 org.springframework.web.servlet.i18n包中定义，并以正常方式在应用程序上下文中进行配置。 Spring中包含以下选择的语言环境解析器。

• Time Zone

• Header Resolver

• Cookie Resolver

• Session Resolver

• Locale Interceptor

Time Zone

除了获取客户端的区域设置外，了解其时区通常也很有用。 LocaleContextResolver 接口提供了LocaleResolver的扩展，它允许解析器提供更丰富的 LocaleContext，其中可能包含时区信息。

当此解析器可用时，可以使用RequestContext.getTimeZone()方法获取用户的TimeZone。 时区信息由Spring的ConversionService注册的任何Date/Time Converter和Formatter 对象自动使用。

Header Resolver

此区域解析器检查客户端（例如，Web浏览器）发送的请求头中的accept-language。 通常，此字段包含客户端操作系统的区域设置。 请注意，此解析器不支持时区信息。

Cookie Resolver

此区域解析器检查客户端上可能存在的 Cookie，以查看是否指定了Locale或TimeZone。 如果是，则使用指定的详细信息。 通过使用此区域解析器的属性，您可以指定cookie的名称以及失效时间。 以下示例定义CookieLocaleResolver：

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">

    <property name="cookieName" value="clientlanguage"/>

    <!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
    <property name="cookieMaxAge" value="100000"/>

</bean>

下表描述了 CookieLocaleResolver的属性：

Table 4. CookieLocaleResolver properties:

Session Resolver

您可以使用 SessionLocaleResolver从与用户请求关联的Session中获取Locale 和TimeZone。 与CookieLocaleResolver相比，此策略将本地选择的区域设置存储在Servlet容器的 HttpSession中。 因此，这些设置对于每个会话都是临时的，这些设置在会话结束时会丢失。

请注意，与外部会话管理机制没有直接关系，例如Spring Session项目。 此SessionLocaleResolver 根据当前的HttpServletRequest评估和修改相应的HttpSession属性。

Locale Interceptor

您可以通过将LocaleChangeInterceptor添加到其中一个 HandlerMapping定义来启用语言环境的更改。 它会检测请求中的参数并相应地更改语言环境，在程序的应用程序上下文中调用 LocaleResolver 上的setLocale方法。 下一个示例显示，当调用包含名为 siteLanguage的参数的所有*.view资源时更改了区域设置。 例如，对URL的请求 [http://www.sf.net/home.view?siteLanguage=nl](https://www.sf.net/home.view?siteLanguage=nl)将网站语言更改为荷兰语。 以下示例显示如何拦截区域设置:

<bean id="localeChangeInterceptor"
        class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
    <property name="paramName" value="siteLanguage"/>
</bean>

<bean id="localeResolver"
        class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>

<bean id="urlMapping"
        class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    <property name="interceptors">
        <list>
            <ref bean="localeChangeInterceptor"/>
        </list>
    </property>
    <property name="mappings">
        <value>/**/*.view=someController</value>
    </property>
</bean>

1.1.10. 主题

您可以使用Spring Web MVC框架自带的主题来设置应用程序的整体外观，从而增强用户体验。 主题是静态资源的集合，通常是样式表和图像，它们会影响应用程序的视觉样式。

定义一个主题

要在Web应用程序中使用主题，必须设置 org.springframework.ui.context.ThemeSource接口的实现。 WebApplicationContext接口扩展了 ThemeSource， 但将其职责委托给专用实现。 默认情况下，委托是 org.springframework.ui.context.support.ResourceBundleThemeSource的实现。它从类路径的根目录加载属性文件。 要使用自定义 ThemeSource实现或配置 ResourceBundleThemeSource的名称前缀，可以在应用程序上下文中使用保留名称themeSource注册bean。 Web应用程序上下文自动检测具有该名称的bean并使用它。

使用 ResourceBundleThemeSource时，主题在简单属性文件中定义。 属性文件列出构成主题的资源，如以下示例所示：

styleSheet=/themes/cool/style.css background=/themes/cool/img/coolBg.jpg

属性的键是从视图代码引用主题元素的名称。 对于JSP，通常使用spring:theme 自定义标签执行此操作，该标记与spring:message标签非常相似。 以下JSP片段使用上一示例中定义的主题来自定义外观：

<%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%>
<html>
    <head>
        <link rel="stylesheet" href="<spring:theme code='styleSheet'/>" type="text/css"/>
    </head>
    <body style="background=<spring:theme code='background'/>">
        ...
    </body>
</html>

默认情况下，ResourceBundleThemeSource使用空的名称前缀。 因此，从类路径的根加载属性文件。 因此，您可以将cool.properties主题定义放在类路径根目录的目录中（例如，在 /WEB-INF/classes中）。 ResourceBundleThemeSource使用标准的Java资源包加载机制，从而使主题也具有国际化。 例如，我们可以有一个/WEB-INF/classes/cool_nl.properties，它引用一个带有荷兰文本的特殊背景图像。

解析主题

定义主题后，如上一节所述，您可以决定使用哪个主题。 DispatcherServlet查找名为themeResolver的bean，以找出要使用的ThemeResolver实现。 主题解析器的工作方式与LocaleResolver的工作方式大致相同。 它检测用于特定请求的主题，还可以更改请求的主题。 下表描述了Spring提供的主题解析器：

Table 5. ThemeResolver implementations :

Spring还提供了一个ThemeChangeInterceptor，它允许通过简单的请求参数对每个请求进行主题更改。

1.1.11. Multipart 解析器

Same as in Spring WebFlux

org.springframework.web.multipart 包中的 MultipartResolver是一种用于解析包括文件上传在内的多部分请求的策略。 他包含了一个Commons FileUpload 的实现，另一个基于Servlet 3.0多部分请求解析。

要启用多部分处理，Spring的配置文件中，在 DispatcherServlet 配置名称为multipartResolver的MultipartResolver bean。 DispatcherServlet会自动检测并将其应用于请求中。 当收到内容类型为multipart/form-data的POST请求时，解析器会解析内容并将当前的HttpServletRequest包装为 MultipartHttpServletRequest，以提供对已解析部分的访问，并将其作为请求参数公开。

Apache Commons FileUpload

要使用Apache Commons FileUpload，您可以配置名为 multipartResolver的CommonsMultipartResolverr类型的bean。 您还需要添加commons-fileupload依赖。

Servlet 3.0

需要通过Servlet容器配置启用Servlet 3.0多部分解析:

• 在Java中，在注册Servlet时设置 MultipartConfigElement。

• 在web.xml中，将“"<multipart-config>"”部分添加到servlet声明中。

以下示例显示如何在注册Servlet时设置 MultipartConfigElement:

public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    // ...

    @Override
    protected void customizeRegistration(ServletRegistration.Dynamic registration) {

        // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold
        registration.setMultipartConfig(new MultipartConfigElement("/tmp"));
    }

}

一旦您配置好Servlet 3.0，您就可以添加名为multipartResolver的StandardServletMultipartResolver类型的bean。

1.1.12. 日志

Same as in Spring WebFlux

Spring MVC中的DEBUG级别日志记录旨在实现紧凑，简约和人性化。 它侧重于那些一次又一次使用的高价值信息，其他的只有在调试特定问题时才有用。

TRACE级日志记录通常遵循与DEBUG相同的原则（例如，不应该是fire hose），但可以用于调试任何问题。 此外，一些日志消息可能在TRACE与DEBUG中显示不同的详细程度。

良好的日志记录来自使用日志的经验。 如果您发现任何不符合既定目标的事件，请告知我们。

敏感数据

Same as in Spring WebFlux

DEBUG和TRACE日志记录可能会记录敏感信息。 这就是默认情况下屏蔽请求参数和请求头的原因，并且必须通过 DispatcherServlet上的 enableLoggingRequestDetails属性显式启用它们的完整日志记录。

以下示例说明如何使用Java配置执行此操作：

public class MyInitializer
        extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return ... ;
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return ... ;
    }

    @Override
    protected String[] getServletMappings() {
        return ... ;
    }

    @Override
    protected void customizeRegistration(Dynamic registration) {
        registration.setInitParameter("enableLoggingRequestDetails", "true");
    }

}

1.2. 过滤器

Same as in Spring WebFlux

spring-web模块提供了一些有用的过滤器:

• Form Data（表单数据）

• Forwarded Headers（转发请求头）

• Shallow ETag（）

• CORS

1.2.1. 表单数据

浏览器只能通过HTTP GET或HTTP POST提交表单数据，但非浏览器客户端也可以使用HTTP PUT，PATCH和DELETE提交表单数据。 Servlet API要求ServletRequest.getParameter*()方法仅支持HTTP POST的表单字段访问。.

spring-web模块提供 FormContentFilter过滤器来拦截HTTP PUT，PATCH和DELETE请求，请求类型为 application/x-www-form-urlencoded， FormContentFilter从请求中读取表单数据， 并包装 ServletRequest，然后可以通过 ServletRequest.getParameter*()系列方法提供表单数据。

1.2.2. Forwarded Headers（转发请求头）

Same as in Spring WebFlux

当通过代理主机或者端口或者其他方案请求时（例如，负载均衡），这是，从客户端角度看，创建正确的主机，端口或者其他方案成为一项挑战，

RFC 7239 RFC 7239定义了代理可以用来提供有关原始请求信息的转发HTTP头。 还有其他非标准头文件，包括X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Proto, X-Forwarded-Ssl, 和 X-Forwarded-Prefix。

ForwardedHeaderFilter是一个Servlet过滤器，它根据 Forwarded 头部信息修改请求的主机，端口和方案，然后删除请求头。

当转发请求头时需要注意的安全事项，因为应用程序无法知道请求头是代理按我们想的那样添加还是由客户端恶意添加，这就是为什么应该将信任边界的代理配置为删除来自外部的不受信任的转发请求头。 您还可以使用removeOnly=true配置ForwardedHeaderFilter，在这种情况下，它会删除但不使用标头。

1.2.3. Shallow ETag

ShallowEtagHeaderFilter过滤器通过缓存写入响应的内容并从中计算MD5哈希来创建 “shallow”ETag。 客户端下次发送时， 它会执行相同操作，但它也会将计算值与If-None-Match请求头进行比较，如果两者相等，则返回304（NOT_MODIFIED）。

此策略可以节省网络带宽，但不能节省CPU，因为必须为每个请求计算完整响应。 前面描述的控制器级别的其他策略可以避免计算。 请参阅 HTTP Caching。

此过滤器具有writeWeakETag参数，该参数将过滤器配置为写入弱ETag，类似于以下内容：W/"02a2d595e6ed9a0b24f027f2b63b134d6"（如RFC 7232 Section 2.3）。

1.2.4. CORS

Same as in Spring WebFlux

Spring MVC通过控制器上的注解为CORS配置提供细粒度的支持。 但是，当与Spring Security一起使用时，我们建议依赖于必须在Spring Security的过滤器链之前配置的内置CorsFilter。

有关更多详细信息，请参阅 CORS和CORS Filter 过滤器部分。

1.3. 注解控制器

Same as in Spring WebFlux

Spring MVC提供了基于注解的编程模型，其中@Controller 和 @RestController 组件使用注解来表示请求映射、请求输入、异常处理等。被注解的控制器拥有灵活的方法签名，并且无需扩展基类或实现特定的接口。以下示例显示了由注解定义的控制器：

@Controller
public class HelloController {

    @GetMapping("/hello")
    public String handle(Model model) {
        model.addAttribute("message", "Hello World!");
        return "index";
    }
}

在前面的示例中，该方法接受Model并将视图名称作为String返回，但是存在许多其他选项，本章稍后将对其进行说明。

有关spring.io的指南和教程，请使用本节中介绍的基于注解的编程模型。

1.3.1. 声明

Same as in Spring WebFlux

您可以在Servlet的WebApplicationContext中使用标准的Spring bean定义来定义控制器bean。@Controller模板允许自动检测， 与Spring支持检测类路径中的@Component类一样，并会自动注册bean定义。它还充当注解类的模板，表示它充当的是Web组件的角色。

要启用@Controller bean的自动检测，您可以将组件扫描添加到Java配置中，如以下示例所示:

@Configuration
@ComponentScan("org.example.web")
public class WebConfig {

    // ...
}

以下示例显示了与前面示例等效的XML配置:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:p="http://www.springframework.org/schema/p"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context
        http://www.springframework.org/schema/context/spring-context.xsd">

    <context:component-scan base-package="org.example.web"/>

    <!-- ... -->

</beans>

@RestController 是一个组合注解 ，它本身由@Controller 和 @ResponseBody元注解组成。 其每个方法都继承类型级别（type-level）的 @ResponseBody注解，因此，直接写入响应主体与视图渲染和使用HTML模板。

AOP 代理

在某些情况下，您需要在运行时使用AOP代理装饰控制器。 例如，如果您想在控制器上直接使用@Transactional注解。 在这种情况下，对于控制器而言，我们建议使用基于类的代理。 这通常也是控制器的默认选择。 但是，如果控制器没有实现Spring Context回调的接口 （例如InitializingBean, *Aware等）， 则可能需要显式配置基于类的代理。 例如，使用 <tx:annotation-driven/>，您可以更改为<tx:annotation-driven proxy-target-class="true"/>。

1.3.2. Request Mapping

Same as in Spring WebFlux

@RequestMapping注解用于将请求映射到控制器方法。它具有各种属性，可以通过URL、HTTP方法、请求参数、请求头参数（headers）和媒体类型进行匹配。 可以在类级别使用它来表示共享映射，或在方法级别上用于缩小到特定的端点映射范围。

还有@RequestMapping的HTTP方法特定的缩写变量:

• @GetMapping

• @PostMapping

• @PutMapping

• @DeleteMapping

• @PatchMapping

这些简洁的注解是自定义注解，因为，大多数的控制器方法应该映射到HTTP方法而不是使用@RequestMapping。默认情况下， @RequestMapping和所有HTTP方法匹配。在类上定义的仍然需要@RequestMapping 来表示共享映射。

以下示例具有类型和方法级别映射:

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    public Person getPerson(@PathVariable Long id) {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public void add(@RequestBody Person person) {
        // ...
    }
}

URI 模式匹配

Same as in Spring WebFlux

你可以使用glob模式和通配符来映射请求:

• ? 匹配一个字符

• * 匹配路径段一个或多个字符

• ** 匹配0个或多个路径段

您还可以使用 @PathVariable声明URI变量并访问它们的值，如以下示例所示:

@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
    // ...
}

您可以在类和方法级别声明URI变量，如以下示例所示：

@Controller
@RequestMapping("/owners/{ownerId}")
public class OwnerController {

    @GetMapping("/pets/{petId}")
    public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
        // ...
    }
}

URI变量会自动转换为适当的类型，或者引发 TypeMismatchException。 默认情况下支持简单类型（int, long, Date等），您也可以注册对任何其他数据类型的支持。 请参见Type Conversion and DataBinder。

你可以显示命名URI 变量(例如, @PathVariable("customId")),但是如果名称是相同的，并且代码是使用调试信息编译的，或者在Java 8中使用-parameters 编译器标记。 则可以保留该详细信息。

语法{varName:regex}声明一个具有正则表达式的URI变量，其语法为{varName:regex}。例如，给定URL"/spring-web-3.0.5 .jar"，以下方法提取名称，版本和文件扩展名:

@GetMapping("/{name:[a-z-]+}-{version:\\d\\.\\d\\.\\d}{ext:\\.[a-z]+}")
public void handle(@PathVariable String version, @PathVariable String ext) {
    // ...
}

URI路径模式还可以嵌入${…​}，在启动时通过PropertyPlaceHolderConfigurer解析本地、系统、环境和其他属性源时解析的占位符。例如，这种模式可以使用基于某些外部配置对基URL进行参数化

Spring MVC使用 PathMatcher联系和 AntPathMatcher实现位于spring-core URI路径匹配。

模式比较

Same as in Spring WebFlux

当多个模式与URL匹配时，必须对它们进行比较以找到最佳匹配。 这是通过使用 AntPathMatcher.getPatternComparator(String path)来完成的，它会查找更具体的模式。

如果URI变量的数量较少且单个通配符计为1且双通配符计为2，那么模式就不那么具体了。如果模式得到的分数相等，那么会选择较长的模式匹配。如果分数和长度都相同，则会选择拥有比通配符更多的URI变量的模式。

默认映射模式（/**）从评分中排除，并始终排在最后。 此外，前缀模式（例如/public/**）被认为比没有双通配符的其他模式更不具体。

有关详细信息，请参阅AntPathMatcher 中的 AntPatternComparator。 您可以自定义PathMatcher 的实现. 请参阅 配置中的Path Matching

后缀匹配

默认情况下,默认情况下，Spring MVC执行.* 后缀模式匹配，以便映射到 /person的控制器也隐式映射到 /person.*。这里使用文件扩展名来解释用于响应的请求内容类型（即，而不是 Accept请求头） - 例如，/person.pdf，/person.xml等。

当浏览器用于发送难以持续交互的Accept头时，必须以这种方式使用文件扩展名。目前，这不再是必需的，判断 Accept头应该是首选。

随着时间的推移，文件扩展名的使用已经证明有多种方式存在问题。 当使用URI变量，路径参数和URI编码进行覆盖时，它可能会导致歧义。 有关基于URL的授权和安全性的推理（有关更多详细信息，请参阅下一节）也变得更加困难。

要完全禁用文件扩展名，必须同时设置以下两项:

• useSuffixPatternMatching(false), see PathMatchConfigurer

• favorPathExtension(false), see ContentNegotiationConfigurer

基于URL的内容协商仍然有用（例如，在浏览器中键入URL时）。 为此，我们建议使用基于查询参数的策略来避免文件扩展名带来的大多数问题。 或者，如果必须使用文件扩展名，请考虑通过ContentNegotiationConfigurer的mediaTypes属性将它们限制为显式注册的扩展名列表。

后缀匹配和RFD

反射文件下载（Reflected file download）攻击与XSS类似，因为它依赖请求输入，例如查询参数、URI变量，并且在响应中被反射。但是，RFD攻击不是将JavaScript插入HTML，而是依赖浏览器切换来执行下载，进而在之后的双击时将响应作为可执行脚本处理。

在Spring MVC中，@ResponseBody和 ResponseEntity方法存在风险，因为它们可以呈现不同的内容类型，客户端可以通过URL路径扩展来请求。 禁用后缀模式匹配并使用路径扩展进行内容协商可降低风险，但不足以防止RFD攻击。

为了防止RFD攻击，在呈现响应主体之前，需要在Spring MVC添加 Content-Disposition:inline;filename=f.txt头用于提供固定和安全的下载文件。只有在URL路径包含的文件扩展名中既不包含白名单，也没有为内容协商显式注册以时，才需要这样做。 但是，在浏览器直接键入URL时，可能会产生副作用。

默认情况下，有许多常见的路径扩展白名单。具有自定义HttpMessageConverter实现的应用程序可以显式注册内容协商的文件扩展名，以避免为这些扩展添加Content-Disposition 头。 请参阅Content Types

有关RFD的其他建议，请参阅CVE-2015-5211。

消费者媒体类型

Same as in Spring WebFlux

您可以根据请求的Content-Type缩小请求映射范围，如以下示例所示:

@PostMapping(path = "/pets", consumes = "application/json") (1)
public void addPet(@RequestBody Pet pet) {
    // ...
}

1、使用 consumes属性来缩小内容类型的映射。

consumes属性还支持否定表达式 - 例如，!text/plain表示除 text/plain之外的任何内容类型。

您可以在类级别声明共享 consumes属性。 但是，与大多数其他请求映射属性不同，在类级别使用时，方法级别会 consumes 属性覆盖而不是扩展类级别声明。

MediaType为常用媒体类型提供常量，例如APPLICATION_JSON_VALUE and APPLICATION_XML_VALUE。

生产者媒体类型

Same as in Spring WebFlux

您可以根据Accept请求头和控制器方法生成的内容类型列表来缩小请求映射，如以下示例所示：

@GetMapping(path = "/pets/{petId}", produces = "application/json;charset=UTF-8") (1)
@ResponseBody
public Pet getPet(@PathVariable String petId) {
    // ...
}

1

使用produces属性来缩小内容类型的映射。

媒体类型可以指定字符集。 支持否定表达式 - 例如， !text/plain表示”text/plain”以外的任何内容类型。

对于JSON内容类型，即使 RFC7159明确声明“没有为此注册定义charset参数”，也应指定UTF-8字符集，因为某些浏览器要求它正确解释UTF-8特殊字符。

您可以在类级别声明共享的produces属性。 但是，与大多数其他请求映射属性不同，在类级别使用时，方法级别会生成属性覆盖，而不是扩展类级别声明。

MediaType为常用媒体类型提供常量，例如APPLICATION_JSON_UTF8_VALUE and APPLICATION_XML_VALUE。

参数, 请求头

Same as in Spring WebFlux

您可以根据请求参数条件缩小请求映射。 您可以测试是否存在请求参数（myParam），缺少一个（!myParam）或特定值（myParam=myValue）。 以下示例显示如何测试特定值：

@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") (1)
public void findPet(@PathVariable String petId) {
    // ...
}

1、测试myParam是否等于myValue。

您还可以将其与请求头条件一起使用，如以下示例所示：:

@GetMapping(path = "/pets", headers = "myHeader=myValue") (1)
public void findPet(@PathVariable String petId) {
    // ...
}

1、Testing whether myHeader equals myValue 。.

您可以将 Content-Type和 Accept 与headers条件匹配，但最好使用consumes和produces替代。

HTTP HEAD, OPTIONS

Same as in Spring WebFlux

@GetMapping (和 @RequestMapping(method=HttpMethod.GET))一样，为了请求映射的目的，透明地支持HTTP HEAD以进行请求映射。控制器方法无需更改。 在javax.servlet.http.HttpServlet中应用的响应包确保有Content-Length标头并且设置为写入的字节数，但实际上不会写入响应。

@GetMapping (and @RequestMapping(method=HttpMethod.GET))一样，为了请求映射的目的，被隐式映射到并支持HTTP HEAD，处理HTTP HEAD请求就像它是HTTP GET一样，但不是写入正文，而是计算字节数并设置 Content-Length头。

默认情况下，HTTP OPTIONS通过设置Allow响应头来为所有具有匹配URL模式的@RequestMapping方法中列出的HTTP方法列表来处理HTTP选项。

对于没有HTTP方法声明的@RequestMapping，Allow请求头可以设置为 GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。 控制器方法应始终声明支持的HTTP方法（例如，通过使用特定于HTTP方法的变体：@GetMapping, @PostMapping等）。

您可以将 @RequestMapping 方法显式映射到HTTP HEAD和HTTP OPTIONS，但在常见情况下这不是必需的。

自定义注解

Same as in Spring WebFlux

Spring MVC支持使用 组合注解进行请求映射。 这些注解本身是使用 @RequestMapping进行元注解的，并且用于重新声明具有更窄，更具体目的的 @RequestMapping属性的子集（或全部）。

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, 和 @PatchMapping 就是组合注解最好的示例， 提供它们是因为，可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是使用@RequestMapping，默认情况下，它与所有HTTP方法匹配。 如果您需要组合注解的示例，请查看如何声明这些注解。

Spring MVC还支持使用自定义请求匹配逻辑的自定义请求映射属性。这是一个更高级的选项，需要继承RequestMappingHandlerMapping 并覆盖getCustomMethodCondition 方法， 您可以在其中检查自定义属性并返回自己的RequestCondition。

显式注册

Same as in Spring WebFlux

您可以以编程方式注册处理程序方法，您可以将其用于动态注册或高级情况，例如不同URL下的同一处理程序的不同实例。 以下示例注册处理程序方法：

@Configuration
public class MyConfig {

    @Autowired
    public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) (1)
            throws NoSuchMethodException {

        RequestMappingInfo info = RequestMappingInfo
                .paths("/user/{id}").methods(RequestMethod.GET).build(); (2)

        Method method = UserHandler.class.getMethod("getUser", Long.class); (3)

        mapping.registerMapping(info, handler, method); (4)
    }

}

1、为控制器注入目标处理程序和处理程序映射

2、准备映射元数据的请求。

3、获取处理程序方法。

4、添加注册。

1.3.3. 程序处理方法

Same as in Spring WebFlux

@RequestMapping 处理程序方法具有灵活的签名,可以从一系列受支持的控制器方法参数和返回值中进行选择.

方法参数

Same as in Spring WebFlux

下表显示了受支持的控制器方法参数，任何参数都不支持响应式(Reactive)类型。

JDK 8’s java.util.Optional 作为方法参数来支持的，它与具有必需属性的注解(例如@RequestParam, @RequestHeader等相结合)。 并且等同于required=false。

返回值

Same as in Spring WebFlux

下表描述了支持的控制器方法返回值。 所有返回值都支持响应式类型。

类型转换

Same as in Spring WebFlux

如果参数声明为String以外的其他参数，则表示某些带注解的控制器方法参数（例如@RequestParam, @RequestHeader, @PathVariable, @MatrixVariable, 和 @CookieValue）可能需要进行类型转换。

对于此类情况，将根据配置的转换器自动应用类型转换。 默认情况下，支持简单类型（int, long, Date和其他）。 您可以通过WebDataBinder（请参阅DataBinder）或使用FormattingConversionService注册Formatters来自定义类型转换。 请参见 Spring Field Formatting。

矩阵变量

Same as in Spring WebFlux

RFC 3986讨论了路径段中的携带键值对。 在Spring MVC中，我们将那些基于Tim Berners-Lee的 “old post” 称为“矩阵变量”，但它们也可以称为URI路径参数。

矩阵变量可以在任意路径段落中出现，每对矩阵变量之间使用分号隔开，多个值可以用逗号隔开（例如，/cars;color=red,green;year=2012）， 也可以通过重复的变量名称指定多个值（例如，color=red;color=green;color=blue）。

如果URL有可能会包含矩阵变量，那么在请求路径的映射配置上就需要使用URI模板来体现。这样才能确保请求可以被正确地映射，而不管矩阵变量在URI中是否出现、出现的次序是怎样的等。以下示例使用矩阵变量：

// GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
public void findPet(@PathVariable String petId, @MatrixVariable int q) {

    // petId == 42
    // q == 11
}

由于任意路径段落中都可以含有矩阵变量，在某些场景下，开发者需要用更精确的信息来指定矩阵变量的位置。以下示例说明如何执行此操作：

// GET /owners/42;q=11/pets/21;q=22

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable(name="q", pathVar="ownerId") int q1,
        @MatrixVariable(name="q", pathVar="petId") int q2) {

    // q1 == 11
    // q2 == 22
}

矩阵变量可以定义为可选，并指定默认值，如以下示例所示：

// GET /pets/42

@GetMapping("/pets/{petId}")
public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) {

    // q == 1
}

要获取所有矩阵变量，可以使用MultiValueMap，如以下示例所示:

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable MultiValueMap<String, String> matrixVars,
        @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

请注意，您需要启用矩阵变量的使用。 在MVC Java配置中，您需要通过 路径匹配将removeSemicolonContent=false 设置为UrlPathHelper。 在MVC XML命名空间中，您可以设置<mvc:annotation-driven enable-matrix-variables="true"/>。

@RequestParam

Same as in Spring WebFlux

您可以使用@RequestParam注解将Servlet请求参数（即查询参数或表单数据）绑定到控制器中的方法参数。

以下示例显示了如何执行此操作：

@Controller
@RequestMapping("/pets")
public class EditPetForm {

    // ...

    @GetMapping
    public String setupForm(@RequestParam("petId") int petId, Model model) { (1)
        Pet pet = this.clinic.loadPet(petId);
        model.addAttribute("pet", pet);
        return "petForm";
    }

    // ...

}

1、使用 @RequestParam绑定petId。

若参数使用了该注解，则该参数默认是必须提供的.但您可以通过将@RequestParam注解的required属性设置为false或通过使用 java.util.Optional包装器声明参数来指定方法参数是可选的。

如果目标方法参数类型不是String，则会自动应用类型转换。 请参阅类型转换。

将参数类型声明为数组或列表允许为同一参数名称解析多个参数值。

当@RequestParam注解声明为Map<String, String> 或MultiValueMap<String, String>时， 如果注解中未指定参数名称，则会使用每个给定参数名称的请求参数值填充映射。

请注意，使用@RequestParam是可选的（例如，设置其属性）。 默认情况下， 任何属于简单值类型的参数（由BeanUtils#isSimpleProperty确定）并且未被任何其他参数解析器解析，都被视为使用@RequestParam进行注解。

@RequestHeader

Same as in Spring WebFlux

您可以使用@RequestHeader注解将请求标头绑定到控制器中的方法参数。

考虑以下请求，请求头为:

Host localhost:8080 Accept text/html,application/xhtml+xml,application/xml;q=0.9 Accept-Language fr,en-gb;q=0.7,en;q=0.3 Accept-Encoding gzip,deflate Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 Keep-Alive 300

以下示例获取Accept-Encoding和Keep-Alive 头的值：

@GetMapping("/demo")
public void handle(
        @RequestHeader("Accept-Encoding") String encoding, (1)
        @RequestHeader("Keep-Alive") long keepAlive) { (2)
    //...
}

1、获取 Accept-Encoding 头部信息.

2、获取 Keep-Alive 头部信息.

如果目标方法参数类型不是String，则会自动应用类型转换。 请参阅类型转换。

在Map<String, String>，MultiValueMap<String, String>或HttpHeaders参数上使用 @RequestHeader注解时，将使用所有请求头值填充映射。

内置支持可用于将逗号分隔的字符串转换为字符串或字符串集或类型转换系统已知的其他类型。 例如，使用 @RequestHeader("Accept") 注解的方法参数可以是String类型，也可以是String[]或List<String>。

@CookieValue

Same as in Spring WebFlux

您可以使用@CookieValue注解将HTTP cookie的值绑定到控制器中的方法参数。

考虑使用以下cookie的请求:

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

以下示例显示了如何获取cookie值：

@GetMapping("/demo")
public void handle(@CookieValue("JSESSIONID") String cookie) { (1)
    //...
}

1、获取JSESSIONID cookie的值

如果目标方法参数类型不是String，则自动应用类型转换。 请参阅类型转换。

@ModelAttribute

Same as in Spring WebFlux

您可以在方法参数上使用@ModelAttribute注解来从模型访问属性，或者如果不存在则将其实例化。 model属性还覆盖了名称与字段名称匹配的HTTP Servlet请求参数的值。 这称为数据绑定，它使您不必处理解析和转换单个查询参数和表单字段。 以下示例显示了如何执行此操作：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { } (1)

1、绑定一个Pet的实例。

上面的Pet实例解析如下：:

• 它可能来自已经添加的Model.

• 它可能因为@SessionAttributes注解的使用已经存在在model中.

• 它可能是由URI模板变量和转换中取得的（下面会详细讲解）.

• 它可能是调用了自身的默认构造器被实例化出来的.

• 他可能从调用具有与Servlet请求参数匹配的参数的“primary constructor”。 参数名称通过JavaBeans@ConstructorProperties或字节码中的运行时保留参数名称确定。

虽然通常使用Model来使用属性填充模型，但另一种替代方法是依赖于Converter<String, T>和URI路径变量。 在以下示例中，model属性名称account匹配URI路径变量 account，并通过将String字符串传递到已注册的Converter<String, Account>转换器来加载Account ：

@PutMapping("/accounts/{account}")
public String save(@ModelAttribute("account") Account account) {
    // ...
}

下一步就是数据的绑定，WebDataBinder类能将请求参数，包括字符串的查询参数和表单字段等，通过名称匹配到model的属性上。成功匹配的字段在需要的时候会进行一次类型转换（从String类型到目标字段的类型），然后被填充到model对应的属性中， 有关数据绑定（和验证）的更多信息，请参阅Validation。 有关自定义数据绑定的更多信息，请参阅DataBinder。

数据绑定可能导致错误。 默认情况下，会引发BindException 。 但是，要在控制器方法中检查此类错误，可以在@ModelAttribute旁边添加一个BindingResult参数，如以下示例所示：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { (1)
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}

1、在@ModelAttribute旁边添加 BindingResult。

在某些情况下，您可能希望在没有数据绑定的情况下访问model属性。对于这种情况，您可以将model注入控制器并直接访问它，或者设置@ModelAttribute(binding=false)，如下例所示：

@ModelAttribute
public AccountForm setUpForm() {
    return new AccountForm();
}

@ModelAttribute
public Account findAccount(@PathVariable String accountId) {
    return accountRepository.findOne(accountId);
}

@PostMapping("update")
public String update(@Valid AccountUpdateForm form, BindingResult result,
        @ModelAttribute(binding=false) Account account) { (1)
    // ...
}

1、设置 @ModelAttribute(binding=false).

通过添加javax.validation.Valid注解或Spring的@Validated注解（Bean validation和Spring validation），您可以在数据绑定后自动应用验证。 以下示例显示了如何执行此操作：

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}

1、验证 Pet 实例.

请注意，使用@ModelAttribute是可选的（例如，设置其属性）。 默认情况下，任何非简单值类型的参数（由BeanUtils#isSimpleProperty确定）并且未被任何其他参数解析器解析，都被视为使用@ModelAttribute进行注解。

@SessionAttributes

Same as in Spring WebFlux

@SessionAttributes用于在请求之间的HTTP Servlet会话中存储model属性。 它是一个类型级别的注解，用于声明特定控制器使用的会话属性。 这通常列出model属性的名称或model属性的类型，这些属性应该透明地存储在会话中以供后续访问请求使用。

以下示例使用@SessionAttributes注解:

@Controller
@SessionAttributes("pet") (1)
public class EditPetForm {
    // ...
}

1、Using the @SessionAttributes annotation.

在第一个请求中，当名称为pet的model属性添加到模型中时，他会自动保存到HTTP Servlet会话中，并保持不变，直到另一个控制器方法使用SessionStatus方法参数来清除存储，如下例所示：

@Controller
@SessionAttributes("pet") (1)
public class EditPetForm {

    // ...

    @PostMapping("/pets/{id}")
    public String handle(Pet pet, BindingResult errors, SessionStatus status) {
        if (errors.hasErrors) {
            // ...
        }
            status.setComplete(); (2)
            // ...
        }
    }
}

1、在Servlet会话中存储Pet值。

2、在Servlet会话中清除Pet值。

@SessionAttribute

Same as in Spring WebFlux

如果需要访问已存在的被全局session属性，例如在控制器之外（如通过过滤器）的（可有可无），请在方法参数上使用@SessionAttribute注解：

@RequestMapping("/")
public String handle(@SessionAttribute User user) { (1)
    // ...
}

1、Using a @SessionAttribute annotation.

对于需要添加或删除会话属性的用例，请考虑将org.springframework.web.context.request.WebRequest或javax.servlet.http.HttpSession注入控制器方法。

作为控制器工作流的一部分，在会话中临时存储模型属性的方法可以使用@SessionAttributes，详情请参阅@SessionAttributes。

@RequestAttribute

Same as in Spring WebFlux

与@SessionAttribute类似，@RequestAttribute注解可用于访问由过滤器（Filter）或拦截器（HandlerInterceptor）创建的已存在的请求属性:

@GetMapping("/")
public String handle(@RequestAttribute Client client) { (1)
    // ...
}

1、Using the @RequestAttribute annotation.

Redirect 属性

默认情况下，所有模型属性都被视为在重定向URL中公开为URI模板变量。 在其余属性中，原始类型或集合或基本类型数组的属性将自动附加为查询参数。

如果专门为重定向准备了模型实例，期望的结果则是将原始类型属性作为查询参数。 但是，在带注解的控制器中，为了渲染目的，模型可以包含其他属性（例如，下拉字段值）。 为了避免在URL中出现此类属性的可能性，@RequestMapping方法可以声明RedirectAttributes类型的参数， 并使用它来指定可供RedirectView使用的确切属性。 如果方法重定向，则使用RedirectAttributes的内容。 否则，使用模型的内容。

RequestMappingHandlerAdapter提供了一个名为ignoreDefaultModelOnRedirect的标志，您可以使用该标志指示如果控制器方法重定向，则永远不应使用默认模型的内容。 相反，控制器方法应声明RedirectAttributes类型的属性，如果不这样做，则不应将任何属性传递给RedirectView。 MVC命名空间和MVC Java配置都将此标志设置为false，以保持向后兼容性。 但是，对于新应用程序，我们建议将其设置为true。

请注意，扩展重定向URL时，当前请求中的URI模板变量会自动可用，您需要通过 Model或RedirectAttributes显式添加它们。 以下示例显示如何定义重定向：

@PostMapping("/files/{path}")
public String upload(...) {
    // ...
    return "redirect:files/{path}";
}

将数据传递到重定向目标的另一种方法是使用flash属性。 与其他重定向属性不同，Flash属性保存在HTTP会话中（因此，不会出现在URL中）。 有关更多信息，请参阅 Flash 属性。

Flash 属性

Flash属性（flash attributes）提供了一个请求为另一个请求存储有用属性的方法。这在重定向的时候最常使用，比如常见的POST/REDIRECT/GET模式。 Flash属性会在重定向前被暂时地保存起来（通常是保存在session中），重定向后会重新被下一个请求取用并立即从原保存地移除。

为支持flash属性，Spring MVC提供了两个抽象。 FlashMap被用来存储flash属性，而用FlashMapManager来存储、取回、管理FlashMap的实例。

对flash属性的支持默认是启用“on” 的，并不需要显式声明，不过没用到它时它绝不会主动地去创建HTTP会话（session）。对于每个请求，框架都会“input” 一个FlashMap，里面存储了从上个请求（如果有）保存下来的属性；同时，每个请求也会“output”FlashMap，里面保存了要给下个请求使用的属性。 两个FlashMap实例在Spring MVC应用中的任何地点都可以通过RequestContextUtils工具类的静态方法取得。

控制器通常不需要直接接触FlashMap。一般是通过@RequestMapping方法去接受RedirectAttributes类型的参数，然后直接地往其中添加flash属性。 通过RedirectAttributes对象添加进去的flash属性会自动被填充到请求的“output”FlashMap对象中去。类似地，重定向后“input”的FlashMap属性也会自动被添加到服务重定向URL的控制器参数Model中去

匹配请求所使用的flash属性

flash属性的概念在其他许多的Web框架中也存在，并且实践证明有时可能会导致并发上的问题。这是因为从定义上讲，flash属性保存的时间是到下个请求接收到之前。 问题在于，“next”请求不一定刚好就是需要重定向到的那个请求，它有可能是其他的异步请求（比如polling请求或者资源请求等）。这会导致flash属性在到达真正的目标请求前就被移除了。

为了减少这个问题发生的可能性，重定向视图RedirectView会自动为一个FlashMap实例记录其目标重定向URL的路径和查询参数。然后，默认的FlashMapManager会在为请求查找其该“input”的FlashMap时，匹配这些信息。

这并不能完全解决重定向的并发问题，但极大程度地减少了这种可能性，因为它可以从重定向URL已有的信息中来做匹配。因此，一般只有在重定向的场景下，才推荐使用flash属性。

Multipart

Same as in Spring WebFlux

启用MultipartResolver后，将解析具有multipart/form-data的POST请求的内容，并将其作为常规请求参数进行访问。 以下示例访问一个常规表单字段和一个上载文件：

@Controller
public class FileUploadController {

    @PostMapping("/form")
    public String handleFormUpload(@RequestParam("name") String name,
            @RequestParam("file") MultipartFile file) {

        if (!file.isEmpty()) {
            byte[] bytes = file.getBytes();
            // store the bytes somewhere
            return "redirect:uploadSuccess";
        }
        return "redirect:uploadFailure";
    }
}

将参数类型声明为List<MultipartFile>允许为同一参数名称解析多个文件。

当@RequestParam注解声明为Map<String, MultipartFile>或MultiValueMap<String, MultipartFile>时，如果注解中未指定参数名称，则会使用每个给定参数名称的多部分文件填充map。

使用Servlet 3.0多部分解析，您也可以将 javax.servlet.http.Part而不是Spring的MultipartFile声明为方法参数或集合值类型。

您还可以将多部分内容用作绑定到命令对象的数据的一部分。 例如，前面示例中的表单字段和文件可以是表单对象上的字段，如以下示例所示：

class MyForm {

    private String name;

    private MultipartFile file;

    // ...
}

@Controller
public class FileUploadController {

    @PostMapping("/form")
    public String handleFormUpload(MyForm form, BindingResult errors) {
        if (!form.getFile().isEmpty()) {
            byte[] bytes = form.getFile().getBytes();
            // store the bytes somewhere
            return "redirect:uploadSuccess";
        }
        return "redirect:uploadFailure";
    }
}

还可以在RESTful服务方案中从非浏览器客户端提交多部分请求。 以下示例显示了带有JSON的文件：

POST /someUrl
Content-Type: multipart/mixed

--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; name="meta-data"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
    "name": "value"
}
--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; name="file-data"; filename="file.properties"
Content-Type: text/xml
Content-Transfer-Encoding: 8bit
... File Data ...

对于名称为”meta-data” 的部分，可以通过控制器方法上的@RequestParamString metadata参数来获得。但对于那部分请求体中为JSON格式数据的请求， 可能更想通过接受一个对应的强类型对象，就像@RequestBody通过HttpMessageConverter将一般请求的请求体转换成一个对象一样。使用@RequestPart注解访问多部分：

@PostMapping("/")
public String handle(@RequestPart("meta-data") MetaData metadata,
        @RequestPart("file-data") MultipartFile file) {
    // ...
}

您可以将@RequestPart与javax.validation.Valid结合使用，或使用Spring的@Validated注解，这两种注解都会导致应用标准Bean验证。 默认情况下，验证错误会导致MethodArgumentNotValidException， 并将其转换为400（BAD_REQUEST）响应。 或者，您可以通过Errors 或BindingResult 参数在控制器内本地处理验证错误，如以下示例所示:

@PostMapping("/")
public String handle(@Valid @RequestPart("meta-data") MetaData metadata,
        BindingResult result) {
    // ...
}

@RequestBody

Same as in Spring WebFlux

您可以使用@RequestBody注解通过HttpMessageConverter将请求主体读取并反序列化为Object。 以下示例使用@RequestBody参数:

@PostMapping("/accounts")
public void handle(@RequestBody Account account) {
    // ...
}

您可以使用MVC Config 的Message Converters选项来配置或自定义消息转换。

您可以将@RequestBody与javax.validation.Valid或Spring的@Validated 注解结合使用，这两种注解都会导致应用标准Bean验证。 默认情况下，验证错误会导致 MethodArgumentNotValidException，并将其转换为400（BAD_REQUEST）响应。 或者，您可以通过Errors或BindingResult参数在控制器内本地处理验证错误，如以下示例所示：:

@PostMapping("/accounts")
public void handle(@Valid @RequestBody Account account, BindingResult result) {
    // ...
}

HttpEntity

Same as in Spring WebFlux

HttpEntity与使用@RequestBody或多或少有些类似，但它基于一个公开请求头和正文的容器对象。 以下清单显示了一个示例:

@PostMapping("/accounts")
public void handle(HttpEntity<Account> entity) {
    // ...
}

@ResponseBody

Same as in Spring WebFlux

您可以在方法上使用@ResponseBody注解，以通过HttpMessageConverter将返回序列化到响应主体。 以下清单显示了一个示例:

@GetMapping("/accounts/{id}")
@ResponseBody
public Account handle() {
    // ...
}

类级别也支持@ResponseBody ，在这种情况下，它由所有控制器方法继承。 例如@RestController的效果，它只不过是一个用@Controller和@ResponseBody标记的元注解。

您可以将@ResponseBody与reactive类型一起使用。 有关更多详细信息，请参阅异步请求和Reactive 类型。

您可以使用MVC Config的 Message Converters选项来配置或自定义消息转换。

您可以将@ResponseBody方法与JSON序列化视图结合使用。 有关详细信息，请参阅Jackson JSON。

ResponseEntity

Same as in Spring WebFlux

ResponseEntity与 @ResponseBody 类似，但具有状态和响应头。 例如:

@GetMapping("/something")
public ResponseEntity<String> handle() {
    String body = ... ;
    String etag = ... ;
    return ResponseEntity.ok().eTag(etag).build(body);
}

Spring MVC支持使用单值reactive type异步生成 ResponseEntity，and/or 主体的单值和多值reactive类型。

Jackson JSON

Spring为Jackson JSON库提供支持。

Jackson 序列化视图

Same as in Spring WebFlux

Spring MVC为Jackson的序列化视图提供内置支持，允许仅渲染Object中所有字段的子集。 为了与@ResponseBody控制器方法或者返回ResponseEntity的控制器方法一起使用，可以简单地将@JsonView注解放在参数上，指定需要使用的视图类或接口即可。如以下示例所示：

@RestController
public class UserController {

    @GetMapping("/user")
    @JsonView(User.WithoutPasswordView.class)
    public User getUser() {
        return new User("eric", "7!jd#h23");
    }
}

public class User {

    public interface WithoutPasswordView {};
    public interface WithPasswordView extends WithoutPasswordView {};

    private String username;
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    @JsonView(WithoutPasswordView.class)
    public String getUsername() {
        return this.username;
    }

    @JsonView(WithPasswordView.class)
    public String getPassword() {
        return this.password;
    }
}

@JsonView允许一组视图类，但每个控制器方法只能指定一个。 如果需要激活多个视图，可以使用复合接口。

对于依赖视图的控制器，只需将序列化视图类添加到model中即可。如以下示例所示：

@Controller
public class UserController extends AbstractController {

    @GetMapping("/user")
    public String getUser(Model model) {
        model.addAttribute("user", new User("eric", "7!jd#h23"));
        model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class);
        return "userView";
    }
}

1.3.4. Model

Same as in Spring WebFlux

您可以使用@ModelAttribute 注解：

• 在@RequestMapping方法中的方法参数方法参数，用于从model创建或访问Object并通过WebDataBinder将其绑定到请求。

• 作为 @Controller或@ControllerAdvice 类中的方法级注解，有助于在任何 @RequestMapping方法调用之前初始化模型。

• 在@RequestMapping方法上标记其返回值是一个模型属性。

本节讨论@ModelAttribute注解可被应用在方法或方法参数上 - 前面列表中的第二项。控制器可以包含任意数量的 @ModelAttribute方法。 在同一控制器中的@RequestMapping方法之前调用所有这些方法。 @ModelAttribute方法也可以通过@ControllerAdvice在控制器之间共享。 有关更多详细信息，请参阅控制器上的通知 部分。

@ModelAttribute方法具有灵活的方法签名。 除了与@ModelAttribute本身或请求体相关的任何内容外，它们支持许多与@RequestMapping方法相同的参数。

以下示例显示了@ModelAttribute 方法：

@ModelAttribute
public void populateModel(@RequestParam String number, Model model) {
    model.addAttribute(accountRepository.findAccount(number));
    // add more ...
}

以下示例仅添加一个属性:

@ModelAttribute
public Account addAccount(@RequestParam String number) {
    return accountRepository.findAccount(number);
}

如果未明确指定名称，框架将根据属性的类型给予一个默认名称，如Conventions的javadoc中所述。 你可以通过设置@ModelAttribute注解的值来改变默认值。当向Model中直接添加属性时，请使用合适的重载方法addAttribute。

@ModelAttribute 注解也可以被用在@RequestMapping方法上，这种情况下，@RequestMapping方法的返回值将会被解释为model的一个属性，而非一个视图名。 此时视图名将以视图命名约定来方式来决议，与返回值为void的方法所采用的处理方法类似。@ModelAttribute 还可以自定义模型属性名称，如以下示例所示：

@GetMapping("/accounts/{id}")
@ModelAttribute("myAccount")
public Account handle() {
    // ...
    return account;
}

1.3.5. 数据绑定

Same as in Spring WebFlux

@Controller或@ControllerAdvice类可以使用@InitBinder 方法初始化WebDataBinder的实例，而这些方法又可以：

• 将请求参数（即表单或查询数据）绑定到模型对象。

• 将基于字符串的请求值（例如请求参数，路径变量，请求头，cookie等）转换为目标类型的控制器方法参数。

• 在呈现HTML表单时将模型对象值格式化为String值。

@InitBinder方法可以注册特定于控制器的java.bean.PropertyEditor或Spring Converter和Formatter组件。 此外，您可以使用MVC config在全局共享的FormattingConversionService中注册Converter和Formatter类型。

@InitBinder 方法支持许多与@RequestMapping方法相同的参数，但@ModelAttribute（命令对象）参数除外。 通常，它们使用WebDataBinder参数（用于注册）和void返回值进行声明。 以下清单显示了一个示例:

@Controller
public class FormController {

    @InitBinder (1)
    public void initBinder(WebDataBinder binder) {
        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        dateFormat.setLenient(false);
        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false));
    }

    // ...
}

1、Defining an @InitBinder method.

或者，当使用基于Formatter的设置时，您可以通过共享的FormattingConversionService重复使用相同的方法并注册特定于控制器的 Formatter 实现，如以下示例所示:

@Controller
public class FormController {

    @InitBinder (1)
    protected void initBinder(WebDataBinder binder) {
        binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd"));
    }

    // ...
}

1、Defining an @InitBinder method on a custom formatter.

1.3.6. 异常

Same as in Spring WebFlux

@Controller 和 @ControllerAdvice可以使用@ExceptionHandler方法来处理来自控制器方法的异常，如下例所示：

@Controller
public class SimpleController {

    // ...

    @ExceptionHandler
    public ResponseEntity<String> handle(IOException ex) {
        // ...
    }
}

该异常可能与顶级异常（即抛出直接IOException）或顶级包装器中的异常（例如，包含在 IllegalStateException内的IOException）相匹配。

对于匹配的异常类型，最好将目标异常声明为方法参数，如前面的示例所示。当多个异常方法匹配时，根(root)异常匹配通常优先于原因(cause )异常匹配。 更具体地说，ExceptionDepthComparator 用于根据抛出的异常类型的深度对异常进行排序。

注解声明可以缩小要匹配的异常类型，如以下示例所示：

@ExceptionHandler({FileSystemException.class, RemoteException.class})
public ResponseEntity<String> handle(IOException ex) {
    // ...
}

您甚至可以使用特定异常类型列表中的非常通用的参数签名，如以下示例所示：:

@ExceptionHandler({FileSystemException.class, RemoteException.class})
public ResponseEntity<String> handle(Exception ex) {
    // ...
}

根(root)和原因(cause )异常匹配之间的区别可能是令人惊讶的。

在前面显示的IOException变体中，通常使用实际的FileSystemException或RemoteException实例作为参数调用该方法，因为它们都是从IOException扩展的。 但是，如果任何此类异常在包装器内传播，而该异常本身就是IOException，则传入的异常实例就是包装器异常。

在handle(Exception)变体中，行为更简单。 这总是在包装场景中使用包装器异常调用，在这种情况下可以通过 ex.getCause()找到实际匹配的异常。 传入的异常仅在实际的FileSystemException或RemoteException实例被抛出为顶级异常时才会发生。

我们通常建议您在参数签名中尽可能具体，减少root和cause异常类型之间不匹配的可能性。 考虑将多匹配方法分解为单独的@ExceptionHandler方法，每个方法通过其签名匹配单个特定异常类型。

在具有多个@ControllerAdvice组成中，我们建议在@ControllerAdvice上声明根异常映射，并使用相应的顺序进行优先级排序。 虽然根异常匹配优先于某个原因，但这是在给定控制器或 @ControllerAdvice类的方法中定义的。 这意味着优先级较高的 @ControllerAdvice bean上的原因匹配优先于较低优先级的 @ControllerAdvice bean上的任何匹配（例如，root）。

最后但同样重要的是， 可以通过@ExceptionHandler方法的实现，讲异常以原始的形式重新抛出，并提供给特定的异常实例。 这在您仅对根级别匹配或在特定上下文中无法静态确定的匹配中感兴趣的情况下非常有用。 重新抛出的异常通过后续的解析链传播，就好像给定的@ExceptionHandler方法首先不匹配一样。

Spring MVC中对@ExceptionHandler方法的支持是基于DispatcherServlet级别的HandlerExceptionResolver机制构建的。

方法参数

@ExceptionHandler 方法支持以下参数：

返回值

@ExceptionHandler方法支持以下返回值:

REST API 异常

Same as in Spring WebFlux

REST服务的一个常见要求是在响应正文中包含错误详细信息。 Spring Framework不会自动执行此操作，因为响应正文中的错误详细信息的表示是特定于应用程序的。 但是，@RestController可以使用带有ResponseEntity返回值的@ExceptionHandler方法来设置响应的状态和正文。 这些方法也可以在@ControllerAdvice类中声明，以全局应用它们。

在响应主体中实现具有错误详细信息的全局异常处理的应用程序应考虑扩展ResponseEntityExceptionHandler， 它提供对Spring MVC引发的异常的处理，并提供钩子来定制响应主体。要使用它，请创建ResponseEntityExceptionHandler的子类，使用@ControllerAdvice注解它，覆盖必要的方法，并将其声明为Spring bean。

1.3.7. 控制器通知

Same as in Spring WebFlux

通常，在@Controller类上声明@ExceptionHandler, @InitBinder, 和 @ModelAttribute注解。 如果您希望此类方法更全局地应用（跨控制器），则可以在标有@ControllerAdvice 或 @RestControllerAdvice的类中声明它们。

@ControllerAdvice``@Component标记，这意味着可以通过组件扫描将这些类注册为Spring bean。 @RestControllerAdvice也是一个用@ControllerAdvice和@ResponseBody标记的元注解，这实际上意味着 @ExceptionHandler 方法通过消息转换（与视图分辨率或模板渲染相对）呈现给响应主体。

在启动时， @RequestMapping和@ExceptionHandler方法的基础结构类检测 @ControllerAdvice 类型的Spring bean，然后在运行时应用它们的方法。 全局@ExceptionHandler方法（来自@ControllerAdvice）在本地方法之后（来自 @Controller）应用。 相比之下，全局@ModelAttribute和@InitBinder方法在本地方法之前应用。

默认情况下，@ControllerAdvice方法适用于每个请求（即所有控制器），但您可以通过使用注解上的属性将其缩小到控制器的子集，如以下示例所示：

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)
public class ExampleAdvice1 {}

// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
public class ExampleAdvice2 {}

// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})
public class ExampleAdvice3 {}

前面示例中的选择器在运行时进行评估，如果广泛使用，可能会对性能产生负面影响。 有关更多详细信息，请参阅@ControllerAdvice javadoc 。

1.4. URI 链接

Same as in Spring WebFlux

本节介绍Spring Framework中可用于处理URI的各种选项。

1.4.1. UriComponents

Spring MVC和Spring WebFlux

UriComponentsBuilder 有助于从URI模板变量构建URI。 如下例所示:

UriComponents uriComponents = UriComponentsBuilder
        .fromUriString("http://example.com/hotels/{hotel}")  (1)
        .queryParam("q", "{q}")  (2)
        .encode() (3)
        .build(); (4)

URI uri = uriComponents.expand("Westin", "123").toUri();  (5)

1、带有URI模板的静态工厂方法。

2、添加或替换URI组件。

3、请求编码URI模板和URI变量。

4、构建一个UriComponents.

5、暴露变量并获取URI.

前面的示例可以合并到一个链中，并使用buildAndExpand缩短，如下例所示:

URI uri = UriComponentsBuilder
        .fromUriString("http://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri();

您可以通过直接转到URI（这意味着编码）来进一步缩短它，如下例所示：

URI uri = UriComponentsBuilder
        .fromUriString("http://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

您使用完整的URI模板进一步缩短它，如下例所示：

URI uri = UriComponentsBuilder
        .fromUriString("http://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123");

1.4.2. UriBuilder

Spring MVC和Spring WebFlux

UriComponentsBuilder 实现了 UriBuilder。 您可以使用UriBuilderFactory创建一个 UriBuilder。 UriBuilderFactory和UriBuilder一起提供了一种可插入机制，可以根据共享配置（例如基本URL，编码首选项和其他详细信息）从URI模板构建URI。

您可以使用UriBuilderFactory配置RestTemplate和WebClient。为自定义URI做准备。DefaultUriBuilderFactory 是UriBuilderFactory 的默认实现，它在内部使用UriComponentsBuilder并公开共享配置选项。

以下示例显示如何配置RestTemplate:

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "http://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VARIABLES);

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

以下示例配置WebClient:

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "http://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VARIABLES);

WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

此外，您还可以直接使用 DefaultUriBuilderFactory 。 它类似于使用UriComponentsBuilder ，但它不是静态工厂方法，而是一个保存配置和首选项的实际实例，如下例所示：

String baseUrl = "http://example.com";
DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);

URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

1.4.3. URI 编码

Spring MVC 和 Spring WebFlux

UriComponentsBuilder在两个级别公开编码选项：

• UriComponentsBuilder#encode(): 首先对URI模板进行预编码，然后在扩展时严格编码URI变量。.

• UriComponents#encode(): 扩展URI变量后对URI组件进行编码。

这两个选项都使用转义的八位字节替换非ASCII和非法字符。 但是，第一个选项还会替换出现在URI变量中的保留含义的字符。

考虑”;“，这在路径中是合法的但具有保留意义。第一个选项取代”;“在URI变量中使用”%3B”但在URI模板中没有。 相比之下，第二个选项永远不会替换“;”，因为它是路径中的合法字符。

对于大多数情况，第一个选项可能会给出预期结果，因为它将URI变量视为完全编码的不透明数据，而选项2仅在URI变量故意包含保留字符时才有用。

以下示例使用第一个选项:

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
            .queryParam("q", "{q}")
            .encode()
            .buildAndExpand("New York", "foo+bar")
            .toUri();

    // Result is "/hotel%20list/New%20York?q=foo%2Bbar"

您可以通过直接转到URI（这意味着编码）来缩短前面的示例，如以下示例所示：

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
            .queryParam("q", "{q}")
            .build("New York", "foo+bar")

您可以使用完整的URI模板进一步缩短它，如以下示例所示：

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}?q={q}")
            .build("New York", "foo+bar")

WebClient和RestTemplate通过 UriBuilderFactory策略在内部展开和编码URI模板。 两者都可以配置自定义策略。 如下例所示：

String baseUrl = "http://example.com";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

// Customize the RestTemplate..
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

// Customize the WebClient..
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

DefaultUriBuilderFactory实现在内部使用UriComponentsBuilder来展开和编码URI模板。 作为工厂，它提供了一个单独的位置来配置编码方法，基于以下编码模式之一：

• TEMPLATE_AND_VALUES: 使用UriComponentsBuilder#encode()（对应于前面列表中的第一个选项）对URI模板进行预编码，并在展开时严格编码URI变量。

• VALUES_ONLY: 不对URI模板进行编码，而是在将URI变量展开到模板之前，通过UriUtils#encodeUriUriVariables对URI变量严格编码。

• URI_COMPONENTS: 使用UriComponents#encode()（对应于前面列表中的第二个选项），在URI变量展开后对URI组件值进行编码。

• NONE: 没有应用编码。

出于历史原因和向后兼容性，RestTemplate设置为 EncodingMode.URI_COMPONENTS。WebClient 依赖于DefaultUriBuilderFactory中的默认值， 该值已从5.0.x中的 EncodingMode.URI_COMPONENTS更改为5.1中的 EncodingMode.TEMPLATE_AND_VALUES。

1.4.4. 相对请求

您可以使用ServletUriComponentsBuilder创建相对于当前请求的URI，如以下示例所示：

HttpServletRequest request = ...

// Re-uses host, scheme, port, path and query string...

ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder.fromRequest(request)
        .replaceQueryParam("accountId", "{id}").build()
        .expand("123")
        .encode();

您可以创建相对于上下文路径的URI，如以下示例所示:

// Re-uses host, port and context path...

ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder.fromContextPath(request)
        .path("/accounts").build()

您可以创建相对于Servlet的URI（例如，/main/*），如以下示例所示:

// Re-uses host, port, context path, and Servlet prefix...

ServletUriComponentsBuilder ucb = ServletUriComponentsBuilder.fromServletMapping(request)
        .path("/accounts").build()

从5.1开始，ServletUriComponentsBuilder忽略来自Forwarded和X-Forwarded-*头部的信息，这些头部信息指定了客户端发起的地址。 考虑使用ForwardedHeaderFilter来提取和使用或丢弃此类请求头。

1.4.5. 控制器链接

Spring MVC也提供了构造指定控制器方法链接的机制。 例如，以下MVC控制器允许创建链接：

@Controller
@RequestMapping("/hotels/{hotel}")
public class BookingController {

    @GetMapping("/bookings/{booking}")
    public ModelAndView getBooking(@PathVariable Long booking) {
        // ...
    }
}

您可以通过引用方法名字的办法来准备一个链接，如以下示例所示：

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

在前面的示例中，为方法参数准备了填充值（在本例中，long值： 21），以用于填充路径变量并插入到URL中。此外，我们提供了值42，来填充任何剩余的URI变量，比如从类层级的请求映射中继承来的hotel变量。 如果方法还有更多的参数，你可以为那些不需要参与URL构造的变量赋予null值。 通常，只有@PathVariable和@RequestParam参数与构造URL相关。

还有其他方法可以使用MvcUriComponentsBuilder。 例如，例如可以通过类似mock掉测试对象的方法，用代理来避免直接通过名字引用一个控制，如以下示例所示（该示例假设静态导入MvcUriComponentsBuilder.on）：

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

Controller method signatures are limited in their design when they are supposed to be usable for link creation with fromMethodCall. Aside from needing a proper parameter signature, there is a technical limitation on the return type (namely, generating a runtime proxy for link builder invocations), so the return type must not be final. In particular, the common String return type for view names does not work here. You should use ModelAndView or even plain Object (with a String return value) instead.

上面的代码例子中使用了MvcUriComponentsBuilder类的静态方法，内部实现中，它依赖于ServletUriComponentsBuilder来从当前请求中抽取schema、主机名、端口号、context路径和Servlet路径， 并准备一个基本URL。大多数情况下它能良好工作，但有时还不行，比如，在准备链接时你可能在当前请求的上下文（context）之外（比如，执行一个准备链接links的批处理），或你可能需要为路径插入一个前缀（比如一个地区性前缀，它从请求中被移除，然后又重新被插入到链接中去）。

对于上面所提的场景，开发者可以使用重载过的静态方法fromXxx，它接收一个UriComponentsBuilder参数，然后从中获取基本URL以便使用，或你也可以使用一个基本URL创建一个MvcUriComponentsBuilder对象， 然后使用实例对象的withXxx方法。以下列表使用 withMethodCall:

UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en");
MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base);
builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

从5.1开始，MvcUriComponentsBuilder忽略来自Forwarded 和X-Forwarded-*头的信息，这些头指定了客户端发起的地址。 考虑使用ForwardedHeaderFilter来提取和使用或丢弃此类标头。

1.4.6. 视图链接

在Thymeleaf，FreeMarker或JSP等视图中，您可以通过引用每个请求映射的隐式或显式指定名称来构建指向带注解控制器的链接。

请考虑以下示例：

@RequestMapping("/people/{id}/addresses")
public class PersonAddressController {

    @RequestMapping("/{country}")
    public HttpEntity getAddress(@PathVariable String country) { ... }
}

给定前面的控制器，可以按照以下方式准备来自JSP的链接，如下所示：

<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>
...
<a href="${s:mvcUrl('PAC#getAddress').arg(0,'US').buildAndExpand('123')}">Get Address</a>

前面的示例依赖于Spring标签库中声明的mvcUrl函数（即 META-INF/spring.tld），但可以很容易地定义自定义函数或使用自定义标记文件。

这是如何工作的，在启动时，每个@RequestMapping 都通过HandlerMethodMappingNamingStrategy分配一个默认名称，其默认实现使用类的大写字母和方法名称（例如， ThingController中的getThing方法变为”TC#getThing”）。如果存在名称冲突，则可以使用@RequestMapping(name="..")分配显式名称或实现自己的HandlerMethodMappingNamingStrategy。

1.5. 异步请求

Compared to WebFlux

Spring MVC与Servlet 3.0异步请求处理有广泛的集成：

• 在控制器方法中返回DeferredResult和Callable，并为单个异步返回值提供基本支持。

• 控制器可以stream多个值，包括SSE 和raw data。

• 控制器可以使用reactive clients 并返回reactive types以进行响应处理。

1.5.1. DeferredResult

Compared to WebFlux

一旦在Servlet容器中启用 了异步请求处理功能，控制器方法就可以使用 DeferredResult包装任何支持的控制器方法返回值，如以下示例所示：

@GetMapping("/quotes")
@ResponseBody
public DeferredResult<String> quotes() {
    DeferredResult<String> deferredResult = new DeferredResult<String>();
    // Save the deferredResult somewhere..
    return deferredResult;
}

// From some other thread...
deferredResult.setResult(data);

控制器可以从不同的线程异步生成返回值 - 例如，响应外部事件（JMS消息），计划任务或其他事件。

1.5.2. Callable

Compared to WebFlux

控制器可以使用 java.util.concurrent.Callable包装任何支持的返回值，如以下示例所示：