20200319 Spring Web MVC 1

1. Spring Web MVC

Spring Web MVC是基于Servlet API构建的原始Web框架，并且从一开始就已包含在Spring框架中。正式名称“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

与其他许多Web框架一样，Spring MVC围绕 前端控制器模式 进行设计，在该模式下，核心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下的示例）。

org.springframework.web.SpringServletContainerInitializer

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

    
        org.springframework.web.context.ContextLoaderListener
    

    
        contextConfigLocation
        /WEB-INF/app-context.xml
    

    
        app
        org.springframework.web.servlet.DispatcherServlet
        
            contextConfigLocation
            
        
        1
    

    
        app
        /app/*
    

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

1.1.1。上下文层次

DispatcherServlet 需要 WebApplicationContext（ApplicationContext的扩展）为其自身的配置。 WebApplicationContext具有指向ServletContext和与其关联的Servlet的链接。 它还绑定到ServletContext，以便应用程序可以在RequestContextUtils上使用静态方法来查找WebApplicationContext（如果需要获取它们）。

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

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

org.springframework.web.servlet.support.AbstractDispatcherServletInitializer#onStartup

以下示例配置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等效项：

    
        org.springframework.web.context.ContextLoaderListener
    

    
        contextConfigLocation
        /WEB-INF/root-context.xml
    

    
        app1
        org.springframework.web.servlet.DispatcherServlet
        
            contextConfigLocation
            /WEB-INF/app1-context.xml
        
        1
    

    
        app1
        /app1/*
    

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

1.1.2。特殊 Bean 类型

DispatcherServlet 委托给特殊的Bean处理请求并呈现适当的响应。 所谓“特殊bean”，是指实现框架协定的Spring管理Object实例。 这些通常带有内置约定，但是您可以自定义其属性并扩展或替换它们。

下表列出了DispatcherServlet会检测的特殊bean：

Bean 类型	说明
HandlerMapping	将请求与拦截器列表一起映射到处理程序，以进行预处理和后期处理。映射基于某些标准，具体标准因HandlerMapping 实现而异。两个主要HandlerMapping实现是RequestMappingHandlerMapping （支持带@RequestMapping注释的方法）和SimpleUrlHandlerMapping （将URI路径模式显式注册到处理程序）。
HandlerAdapter	帮助DispatcherServlet调用映射到请求的处理程序，而不管实际如何调用该处理程序。例如，调用带注释的控制器需要解析注释。HandlerAdapter 的主要目的是保护DispatcherServlet这些细节。
HandlerExceptionResolver	解决异常的策略，可能将它们映射到处理程序，HTML错误视图或其他目标。请参阅例外。
ViewResolver	解析从处理程序返回的实际基于字符串的基于逻辑的视图名称，以实际的视图呈现给响应。 请参阅 View Resolution 和 View Technologies。
LocaleResolver，LocaleContextResolver	解决一个客户正在使用的Locale并且可能是其时区的问题，以便能够提供国际化的视图。请参阅语言环境。
ThemeResolver	解决Web应用程序可以使用的主题，例如，提供个性化的布局。请参阅主题。
MultipartResolver	借助一些多部分解析库来解析 multi-part 请求的抽象（例如，浏览器表单文件上传）。请参见Multipart Resolver。
FlashMapManager	存储和检索“输入”和“输出” FlashMap，它们通常用于通过重定向将属性从一个请求传递到另一个请求。请参见Flash属性。

默认配置在 DispatcherServlet.properties 中

调用：

org.springframework.web.servlet.DispatcherServlet#doDispatch

1.1.3。Web MVC配置

应用程序可以声明处理请求所需的特殊Bean类型中列出的基础结构Bean。 DispatcherServlet检查每个特殊bean的WebApplicationContext。 如果没有匹配的bean类型，它将使用DispatcherServlet.properties中列出的默认类型。

C:/Users/80953/.ideaLibSources/spring-webmvc-5.2.3.RELEASE-sources.jar!/org/springframework/web/servlet/DispatcherServlet.java:283

在大多数情况下，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 容器。WebApplicationInitializer的抽象基类实现名为AbstractDispatcherServletInitializer，它通过覆盖指定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. 请求处理过程

DispatcherServlet 处理请求过程如下：

• 搜索WebApplicationContext并将其绑定为请求中的属性，控制器和流程中的其他元素可以使用该属性。 默认情况下，它绑定在DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE键下。
• 语言环境解析器绑定到请求，以使流程中的元素解析在处理请求（呈现视图，准备数据等）时要使用的语言环境。 如果不需要语言环境解析，则不需要语言环境解析器。
• 主题解析器绑定到请求，以使诸如视图之类的元素确定要使用的主题。如果不使用主题，则可以将其忽略。
• 如果指定多部分文件解析器，则将检查请求中是否有多部分。如果找到多部分，则将请求包装在MultipartHttpServletRequest中，以供流程中的其他元素进一步处理。有关多部分处理的更多信息，请参见Multipart Resolver。
• 搜索适当的处理程序。 如果找到处理程序，则执行与处理程序（预处理器，后处理器和控制器）关联的执行链，以准备模型或渲染。 另外，对于带注释的控制器，可以呈现响应（在HandlerAdapter中），而不是返回视图。
• 如果返回模型，则呈现视图。如果没有返回任何模型（可能是由于预处理器或后处理器拦截了该请求，可能出于安全原因），则不会呈现任何视图，因为该请求可能已经被满足。

org.springframework.web.servlet.DispatcherServlet#doService

WebApplicationContext中声明的HandlerExceptionResolver Bean用于解决在请求处理期间引发的异常。 这些异常解析器允许定制逻辑以解决异常。 有关更多详细信息，请参见 Exceptions。

Spring DispatcherServlet还支持Servlet API所指定的last-modification-date的返回。 确定特定请求的最后修改日期的过程很简单：DispatcherServlet查找适当的处理程序映射，并测试找到的处理程序是否实现了LastModified接口。 如果是这样，则将LastModified接口的long getLastModified(request)方法的值返回给客户端。

您可以通过将Servlet初始化参数（init-param元素）添加到web.xml文件中的Servlet声明中，来定制各个DispatcherServlet实例。 下表列出了受支持的参数：

表1. DispatcherServlet初始化参数

参数	说明
contextClass	实现ConfigurableWebApplicationContext的类，由该Servlet实例化并在本地配置。默认情况下，使用XmlWebApplicationContext。
contextConfigLocation	传递给上下文实例的字符串（由contextClass指定），以指示可以在哪里找到上下文。该字符串可能包含多个字符串（使用逗号作为分隔符）以支持多个上下文。对于具有两次定义的bean的多个上下文位置，以最新位置为准。
namespace	WebApplicationContext的命名空间。默认为[servlet-name]-servlet。
throwExceptionIfNoHandlerFound	在找不到请求的处理程序时是否抛出NoHandlerFoundException。然后可以使用HandlerExceptionResolver（例如，使用 @ExceptionHandler控制器方法）捕获该异常并将其作为其他任何异常进行处理。默认情况下，它设置为false，在这种情况下，DispatcherServlet将响应状态设置为404（NOT_FOUND），而不会引发异常。请注意，如果还配置了默认servlet处理，则始终将未解决的请求转发到默认servlet，并且永远不会引发404。

org.springframework.web.servlet.HttpServletBean#init

1.1.6。拦截

所有HandlerMapping实现都支持处理程序拦截器，当您要将特定功能应用于某些请求（例如，检查主体）时，这些拦截器将非常有用。拦截器必须使用三种方法从org.springframework.web.servlet程序包中实现HandlerInterceptor，这 三种方法应提供足够的灵活性以执行各种预处理和后处理：

• preHandle(..)：在执行实际的处理程序之前
• postHandle(..)：执行处理程序后
• afterCompletion(..)：完成完整的请求后

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

有关如何配置拦截器的示例，请参见MVC配置部分中的拦截器。 您还可以通过使用各个HandlerMapping实现上的设置器直接注册它们。

请注意，对于@ResponseBody和ResponseEntity方法，postHandle的用处不大，在HandlerAdapter内和postHandle之前，将其写入并提交响应。 这意味着对响应进行任何更改为时已晚，例如添加额外的标头。 对于这种情况，您可以实现ResponseBodyAdvice并将其声明为Controller Advice Bean或直接在RequestMappingHandlerAdapter上对其进行配置。

1.1.7。异常

如果在请求映射期间发生异常或从请求处理程序（例如@Controller）抛出异常，则将DispatcherServlet委托委托给HandlerExceptionResolver Bean 链以解决异常并提供替代处理，通常是错误响应。

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

HandlerExceptionResolver	描述
SimpleMappingExceptionResolver	异常类名称和错误视图名称之间的映射。对于在浏览器应用程序中呈现错误页面很有用。
DefaultHandlerExceptionResolver	解决Spring MVC引发的异常，并将其映射到HTTP状态代码。另请参见替代ResponseEntityExceptionHandler和REST API异常。
ResponseStatusExceptionResolver	使用@ResponseStatus注释解决异常，并根据注释中的值将其映射到HTTP状态代码。
ExceptionHandlerExceptionResolver	通过调用@Controller或@ControllerAdvice类中的@ExceptionHandler方法来解决异常。 请参见@ExceptionHandler方法。

解析器链

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

org.springframework.web.servlet.DispatcherServlet#initHandlerExceptionResolvers

如果没有自定义 HandlerExceptionResolver bean，则异常解析器链中是在 DispatcherServlet.properties 中定义的：

org.springframework.web.servlet.HandlerExceptionResolver=org.springframework.web.servlet.mvc.method.annotation.ExceptionHandlerExceptionResolver,\
   org.springframework.web.servlet.mvc.annotation.ResponseStatusExceptionResolver,\
   org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver

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

• 指向错误视图的ModelAndView。

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

• 如果该异常仍未解决，则为null，以供后续解析器尝试；如果该异常仍在末尾，则允许将其冒泡到Servlet容器。

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

容器错误页面

如果所有HandlerExceptionResolver仍然无法解决异常，该异常可以传播，或者如果响应状态设置为错误状态（即4xx，5xx），则Servlet容器可以在HTML中呈现默认错误页面。要自定义容器的默认错误页面，可以在web.xml中声明错误页面映射。以下示例显示了如何执行此操作：

    /error

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

@RestController
public class ErrorController {

    @RequestMapping(path = "/error")
    public Map handle(HttpServletRequest request) {
        Map map = new HashMap();
        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。视图解析

Spring MVC定义了ViewResolver和View接口，可让您在浏览器中呈现模型，而无需将您与特定的视图技术联系在一起。ViewResolver 提供视图名称和实际视图之间的映射。View在移交给特定的视图技术之前，先解决数据准备问题。

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

表3. ViewResolver实现

ViewResolver	描述
AbstractCachingViewResolver	AbstractCachingViewResolver的子类缓存它们解析的视图实例。 缓存可以提高某些视图技术的性能。 您可以通过将cache属性设置为false来关闭缓存。 此外，如果必须在运行时刷新某个视图（例如，当修改FreeMarker模板时），则可以使用removeFromCache(String viewName，Locale loc)方法。
XmlViewResolver	ViewResolver的实现接受一个用XML编写的配置文件，该配置文件的DTD与Spring的XML bean工厂相同。默认配置文件是 /WEB-INF/views.xml。
ResourceBundleViewResolver	ViewResolver的实现，该实现使用ResourceBundle中的bean定义（由包基本名称指定）。对于应该解析的每个视图，它将属性的值[viewname].(class)用作视图类，并将属性的值[viewname].url用作视图URL。您可以在View Technologies一章中找到示例 。
UrlBasedViewResolver	ViewResolver接口的简单实现会影响将逻辑视图名称直接解析为URL而没有显式映射定义。如果您的逻辑名称以直接的方式与视图资源的名称匹配，而无需任意映射，则这是适当的。
InternalResourceViewResolver	UrlBasedViewResolver的方便子类，支持InternalResourceView（实际上，Servlet和JSP）和子类，如JstlView和TilesView。您可以使用setViewClass(..)来为此解析器生成的所有视图指定视图类。有关UrlBasedViewResolver 详细信息，请参见javadoc。
FreeMarkerViewResolver	UrlBasedViewResolver的方便的子类支持FreeMarkerView和他们的自定义子类。
ContentNegotiatingViewResolver	基于请求文件名或Accept头解析视图的ViewResolver接口的实现。请参阅内容协商。

初始化：

org.springframework.web.servlet.DispatcherServlet#initViewResolvers

DispatcherServlet.properties 中定义的：

org.springframework.web.servlet.ViewResolver=org.springframework.web.servlet.view.InternalResourceViewResolver

调用：

org.springframework.web.servlet.DispatcherServlet#resolveViewName

处理方式（Handling）

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

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

配置视图解析就像将ViewResolver bean添加到Spring配置中一样简单。 MVC Config为View解析器和添加无逻辑的View Controller提供了专用的配置API，这对于无控制器逻辑的HTML模板呈现非常有用。

重定向

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

org.springframework.web.servlet.view.UrlBasedViewResolver#createView

最终效果与控制器返回RedirectView的效果相同，但是现在控制器本身可以根据逻辑视图名称进行操作。 逻辑视图名称（如redirect:/myapp/some/resource）相对于当前Servlet上下文进行重定向，而名称如redirect：https://myhost.com/some/arbitrary/path则重定向至绝对URL。

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

转发

您还可以对视图名称使用特殊的forward:前缀，这些视图名称最终由UrlBasedViewResolver和子类解析。这将创建一个 InternalResourceView，并执行一个RequestDispatcher.forward()。因此，此前缀在InternalResourceViewResolver和InternalResourceView中（对于JSP）没有用，但是如果您使用另一种视图技术，但仍然希望强制转发由Servlet/JSP引擎处理的资源，则该前缀很有用。请注意，您也可以链接多个视图解析器。

内容协商

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

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

有关配置详细信息，请参见MVC Config下的查看解析器。

1.1.9. Locale

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

收到请求时，DispatcherServlet将查找一个语言环境解析器，如果找到一个，它将尝试使用它来设置语言环境。通过使用RequestContext.getLocale() 方法，您始终可以检索由语言环境解析器解析的语言环境。

除了自动的语言环境解析之外，您还可以在处理程序映射上附加一个拦截器（有关处理程序映射拦截器的更多信息，请参见拦截），以在特定情况下（例如，基于请求中的参数）更改语言环境。

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

• Time Zone
• Header Resolver
• Cookie Resolver
• Session Resolver
• Locale Interceptor

org.springframework.web.servlet.LocaleResolver=org.springframework.web.servlet.i18n.AcceptHeaderLocaleResolver

时区

除了获取客户的语言环境外，了解其时区通常也很有用。 LocaleContextResolver接口提供了LocaleResolver的扩展，该扩展使解析程序可以提供更丰富的LocaleContext，其中可能包含时区信息。

如果可用，则可以使用RequestContext.getTimeZone()方法获取用户的TimeZone。 通过Spring的ConversionService注册的任何日期/时间转换器和格式器对象都会自动使用时区信息。

标头解析器

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

Cookie解析器

该语言环境解析器检查客户端上可能存在的Cookie，以查看是否指定Locale或TimeZone。如果是这样，它将使用指定的详细信息。通过使用此语言环境解析器的属性，可以指定Cookie的名称以及最长期限。以下示例定义了一个CookieLocaleResolver：

下表描述了CookieLocaleResolver的属性：

表4. CookieLocaleResolver属性

属性	默认	描述
cookieName	类名+ LOCALE	Cookie的名称
cookieMaxAge	Servlet容器默认	Cookie在客户端上保留的最长时间。如果指定-1，则cookie将不会保留。它仅在客户端关闭浏览器之前可用。
cookiePath	/	将Cookie的可见性限制在您网站的特定部分。当cookiePath被指定，cookie是仅对于该路径和它下面的路径可见。

会话解析器

SessionLocaleResolver允许您从可能与用户的请求相关的会话中检索Locale和TimeZone。不同于CookieLocaleResolver，此策略将本地选择的语言环境设置存储在Servlet容器的HttpSession中。结果，这些设置对于每个会话都是临时的，因此在每个会话终止时会丢失。

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

区域拦截器

您可以通过将LocaleChangeInterceptor添加到HandlerMapping定义之一来启用语言环境更改。 它在请求中检测到一个参数，并相应地更改语言环境，在调度程序的应用程序上下文中在LocaleResolver上调用setLocale方法。 下一个示例显示，对所有包含名为siteLanguage的参数的*.view资源的调用现在都会更改语言环境。 因此，例如，对URL的请求https://www.sf.net/home.view?siteLanguage=nl会将站点语言更改为荷兰语。 以下示例显示如何拦截语言环境：

    





    
        
            
        
    
    
        /**/*.view=someController
    

1.1.10. Themes

您可以应用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"%>

    
        
    
    
        ...
    

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

解析主题

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

表5. ThemeResolver实现

类	描述
FixedThemeResolver	选择通过使用defaultThemeName属性设置的固定主题。
SessionThemeResolver	主题在用户的HTTP会话中维护。每个会话只需设置一次，但在会话之间不会保留。
CookieThemeResolver	所选主题存储在客户端的cookie中。

Spring还提供了一个ThemeChangeInterceptor允许使用简单的请求参数对每个请求进行主题更改的功能。

org.springframework.web.servlet.ThemeResolver=org.springframework.web.servlet.theme.FixedThemeResolver

1.1.11。Multipart 解析器

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

要启用 Multipart 处理，您需要在DispatcherServlet Spring配置中声明一个名为multipartResolver的MultipartResolver bean。 DispatcherServlet会检测到它并将其应用于传入的请求。 当收到内容类型为multipart/form-data的POST时，解析程序将解析内容并将当前的HttpServletRequest包装为MultipartHttpServletRequest，以提供对已解析部分的访问权，此外还可以将其公开为请求参数。

Apache Commons FileUpload

要使用Apache Commons FileUpload，可以配置名称为multipartResolver的CommonsMultipartResolver类型的Bean。 您还需要commons-fileupload作为对类路径的依赖。

Servlet 3.0

需要通过Servlet容器配置启用Servlet 3.0 multipart 解析。 为此：

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

• 在web.xml中，将 部分添加到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. Logging

Spring MVC中的DEBUG级别的日志被设计为紧凑，最少且人性化的。 它侧重于一遍又一遍有用的高价值信息，而其他信息仅在调试特定问题时才有用。

TRACE级别的日志记录通常遵循与DEBUG相同的原理（例如，也不应是消防水带），但可用于调试任何问题。 此外，某些日志消息在TRACE和DEBUG上可能显示不同级别的详细信息。

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

敏感数据

调试和跟踪日志记录可能会记录敏感信息。 这就是默认情况下屏蔽请求参数和标头，并且必须通过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(ServletRegistration.Dynamic registration) {
        registration.setInitParameter("enableLoggingRequestDetails", "true");
    }

}

1.2. Filters

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来拦截内容类型为application/x-www-form-urlencoded的HTTP PUT，PATCH和DELETE请求，从请求主体中读取表单数据，并包装ServletRequest以使表单数据可通过ServletRequest.getParameter *()方法族获得。

1.2.2。转发的表头

当请求通过代理（例如负载平衡器）进行处理时，主机，端口和 scheme 可能会更改，这使得从客户端角度创建指向正确的主机，端口和 scheme 的链接带来了挑战。

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

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

对于转发的标头，出于安全方面的考虑，因为应用程序无法知道标头是由代理添加的，还是由恶意客户端添加的。这就是为什么应配置位于信任边界的代理以删除来自外部的不受信任的Forwarded标头的原因。您也可以用removeOnly=true配置ForwardedHeaderFilter，在这种情况下，它会删除但不使用标题。

1.2.3. Shallow ETag

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

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

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

1.2.4。CORS

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

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

1.3。带注释的控制器

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。声明

您可以使用Servlet的WebApplicationContext中的标准Spring bean定义来定义控制器bean。 @Controller构造型允许自动检测，与Spring对在类路径中检测@Component类并为其自动注册Bean定义的常规支持保持一致。 它还充当带注释类的构造型，表明其作为Web组件的作用。

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

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

    // ...
}

下面的示例显示与前面的示例等效的XML配置：

@RestController是一个组合的注解，其本身使用@Controller和@ResponseBody进行了元注释，以指示其每个方法都继承类型级别@ResponseBody注解的控制器，因此，将其直接写入响应主体（与视图解析相对应）并使用 HTML模板。

AOP代理

在某些情况下，您可能需要在运行时用AOP代理装饰控制器。 一个示例是，如果您选择直接在控制器上具有@Transactional注解。 在这种情况下，特别是对于控制器，我们建议使用基于类的代理。 这通常是控制器的默认选择。 但是，如果控制器必须实现不是Spring Context回调的接口（例如InitializingBean，*Aware等），则可能需要显式配置基于类的代理。 例如，使用可以更改为，使用@EnableTransactionManagement可以更改为@EnableTransactionManagement(proxyTargetClass = true)。

1.3.2。请求映射

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

@RequestMapping还有HTTP方法特定的快捷方式：

• @GetMapping
• @PostMapping
• @PutMapping
• @DeleteMapping
• @PatchMapping

快捷方式是提供的“自定义注释”，因为可以说，大多数控制器方法应该映射到特定的HTTP方法，而不是使用@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模式

您可以使用以下全局模式和通配符来映射请求：

• ? 匹配一个字符
• * 匹配路径段中的零个或多个字符
• ** 匹配零个或多个路径段

您还可以声明URI变量并使用@PathVariable来访问其值，如以下示例所示：

@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，等）默认支持，你可以注册任何其它数据类型的支持。请参阅类型转换和DataBinder。

您可以显式命名URI变量（例如@PathVariable("customId")），但是如果名称相同并且您的代码是通过调试信息或-parameters Java 8上的编译器标志进行编译的，则可以省去该细节。

语法{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使用spring-core中的PathMatcher协定和AntPathMatcher实现来进行URI路径匹配。

模式比较

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

如果模式的URI变量（计数为1），单通配符（计数为1）和双通配符（计数为2）的数量较少，则模式的含义不太明确。 给定相等的分数，则选择更长的模式。 给定相同的分数和长度，将选择URI变量比通配符更多的模式。

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

有关完整的详细信息，请参见AntPatternComparator 中AntPathMatcher，也请记住，你可以自定义PathMatcher的实现。请参阅配置部分中的路径匹配。

后缀匹配

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

当浏览器用来发送难以一致解释的Accept标头时，以这种方式使用文件扩展名是必要的。 目前，这已不再是必须的，使用Accept标头应该是首选。

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

若要完全禁用文件扩展名，必须设置以下两项：

• useSuffixPatternMatching(false)，请参阅PathMatchConfigurer
• favorPathExtension(false)，请参阅ContentNegotiationConfigurer

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

后缀匹配和RFD

反射文件下载（RFD）攻击与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头。请参阅内容类型。

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

Consumable Media Types

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

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

使用consumes属性按内容类型缩小映射。

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

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

MediaType提供常用媒体类型（例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE）的常量 。

Producible Media Types

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

@GetMapping(path = "/pets/{petId}", produces = "application/json") 
@ResponseBody
public Pet getPet(@PathVariable String petId) {
    // ...
}

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

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

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

MediaType提供常用媒体类型（例如APPLICATION_JSON_VALUE和APPLICATION_XML_VALUE）的常量 。

Parameters, headers

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

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

测试myParam是否相等myValue。

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

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

您可以匹配Content-Type并Accept与标头条件匹配，但最好使用 消耗和生产 。

HTTP HEAD, OPTIONS

@GetMapping（和@RequestMapping(method=HttpMethod.GET)）透明支持HTTP HEAD以进行请求映射。控制器方法不需要更改。应用于javax.servlet.http.HttpServlet的响应包装器确保将Content-Length 标头设置为写入的字节数（实际上未写入响应）。

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

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

对于@RequestMapping不使用HTTP方法声明的情况，Allow标头设置为 GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS。控制器方法应该总是声明支持HTTP方法（例如，通过使用HTTP方法具体变体： @GetMapping，@PostMapping，及其他）。

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

自定义注释

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

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

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

明确注册

您可以以编程方式注册处理程序方法，这些方法可用于动态注册或高级案例，例如同一处理程序在不同URL下的不同实例。下面的示例注册一个处理程序方法：

@Configuration
public class MyConfig {

	// 注入目标处理程序和控制器的处理程序映射。
    @Autowired
    public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler)  throws NoSuchMethodException {
		// 准备请求映射元数据。
        RequestMappingInfo info = RequestMappingInfo .paths("/user/{id}").methods(RequestMethod.GET).build(); 
		
		// 获取处理程序方法。
        Method method = UserHandler.class.getMethod("getUser", Long.class); 

		// 添加注册。
        mapping.registerMapping(info, handler, method); 
    }
}

1.3.3。处理程序方法（Handler Methods）

@RequestMapping 处理程序方法具有灵活的签名，可以从支持的控制器方法参数和返回值的范围中进行选择。

方法参数

下表描述了受支持的控制器方法参数。 任何参数均不支持响应式类型。

支持JDK 8的java.util.Optional作为方法参数，并与具有必需属性（例如，@RequestParam，@RequestHeader等）的注释结合在一起，等效于required = false。

控制器方法参数	描述
WebRequest， NativeWebRequest	通用访问请求参数以及请求和会话属性，而无需直接使用Servlet API。
javax.servlet.ServletRequest， javax.servlet.ServletResponse	选择任何特定的请求或响应类型-例如ServletRequest，HttpServletRequest或Spring的MultipartRequest，MultipartHttpServletRequest。
javax.servlet.http.HttpSession	强制会话的存在。 结果，这样的参数永远不会为空。 请注意，会话访问不是线程安全的。 如果允许多个请求并发访问会话，请考虑将RequestMappingHandlerAdapter实例的syncnizeOnSession标志设置为true。
javax.servlet.http.PushBuilder	用于程序化 HTTP/2 资源推送的Servlet 4.0推送构建器API。请注意，根据Servlet规范，如果客户端不支持HTTP/2功能，则注入的PushBuilder实例可以为null。
java.security.Principal	当前经过身份验证的用户-可能是特定的Principal实现类（如果已知）。
HttpMethod	请求的HTTP方法。
java.util.Locale	当前的请求语言环境，由最可用的特定LocaleResolver（实际上是配置的LocaleResolver或LocaleContextResolver）确定。
java.util.TimeZone + java.time.ZoneId	与当前请求关联的时区，由LocaleContextResolver决定。
java.io.InputStream， java.io.Reader	用于访问Servlet API公开的原始请求正文。
java.io.OutputStream， java.io.Writer	用于访问Servlet API公开的原始响应正文。
@PathVariable	用于访问URI模板变量。请参阅URI模式。
@MatrixVariable	用于访问URI路径段中的名称/值对。请参阅矩阵变量。
@RequestParam	用于访问Servlet请求参数，包括多部分文件。参数值将转换为声明的方法参数类型。参见@RequestParam以及Multipart。 请注意，对于简单参数值，使用@RequestParam是可选的。请参阅此表末尾的“其他任何参数”。
@RequestHeader	用于访问请求标头。标头值将转换为声明的方法参数类型。请参阅@RequestHeader。
@CookieValue	用于访问cookie。Cookies值将转换为声明的方法参数类型。请参阅@CookieValue。
@RequestBody	用于访问HTTP请求正文。正文内容通过使用HttpMessageConverter实现转换为声明的方法参数类型。请参阅@RequestBody。
HttpEntity	用于访问请求标头和正文。正文用HttpMessageConverter转换。参见HttpEntity。
@RequestPart	要访问multipart/form-data请求中的文件，使用HttpMessageConverter来转换文件的主体。参见多部分。
java.util.Map，org.springframework.ui.Model，org.springframework.ui.ModelMap	用于访问HTML控制器中使用的模型，并作为视图渲染的一部分公开给模板。
RedirectAttributes	指定在重定向的情况下使用的属性（即追加到查询字符串中），并指定要临时存储的属性，直到重定向后的请求为止。请参阅重定向属性和Flash属性。
@ModelAttribute	用于访问应用了数据绑定和验证的模型中的现有属性（如果不存在，则进行实例化）。 请参见@ModelAttribute以及Model和DataBinder。 请注意，@ModelAttribute的使用是可选的（例如，设置其属性）。 请参阅此表末尾的“其他任何参数”。
Errors， BindingResult	用于访问来自命令对象的验证和数据绑定（即@ModelAttribute参数）的错误或来自@RequestBody或@RequestPart参数的验证的错误。 您必须在经过验证的方法参数之后立即声明一个Errors或BindingResult参数。
SessionStatus + 类级别 @SessionAttributes	为了标记表单处理完成，将触发清除通过类级别@SessionAttributes注释声明的会话属性。 有关更多详细信息，请参见@SessionAttributes。
UriComponentsBuilder	用于准备相对于当前请求的主机，端口，方案，上下文路径以及servlet映射的文字部分的URL。请参阅URI链接。
@SessionAttribute	对于访问任何会话属性，与通过类级别@SessionAttributes声明存储在会话中的模型属性相反。 有关更多详细信息，请参见@SessionAttribute。
@RequestAttribute	用于访问请求属性。请参阅@RequestAttribute以获取更多详细信息。
任何其他论点	如果方法参数不与此表中的任何较前的值匹配，并且是简单类型（由BeanUtils＃isSimpleProperty确定 ，则将其解析为@RequestParam。否则，将其解析为@ModelAttribute。

为控制器上的参数赋值

org.springframework.web.method.support.InvocableHandlerMethod#invokeForRequest

默认支持的参数类型解析器：

org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#getDefaultArgumentResolvers

返回值

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

控制器方法返回值	描述
@ResponseBody	返回值通过HttpMessageConverter实现进行转换并写入响应。请参阅@ResponseBody。
HttpEntity， ResponseEntity	指定完整响应（包括HTTP标头和正文）的返回值将通过HttpMessageConverter实现进行转换，并写入响应中。参见ResponseEntity。
HttpHeaders	用于返回带标头没有主体内容的响应。
String	一个视图名称，将通过ViewResolver实现来解析，并与隐式模型一起使用-通过命令对象和@ModelAttribute方法确定。处理程序方法还可以通过声明Model参数来以编程方式丰富模型（请参见Explicit Registrations）。
View	用于与隐式模型一起渲染的View实例，该隐式模型是通过命令对象和@ModelAttribute方法确定的。 处理程序方法还可以通过声明Model参数来以编程方式丰富模型（请参阅Explicit Registrations）。
java.util.Map， org.springframework.ui.Model	要添加到隐式模型的属性，视图名称通过RequestToViewNameTranslator隐式确定。
@ModelAttribute	要添加到模型的属性，视图名称通过RequestToViewNameTranslator隐式确定。 请注意，@ModelAttribute是可选的。请参阅此表末尾的“其他任何返回值”。
ModelAndView 对象	要使用的视图和模型属性，以及响应状态（可选）。
void	如果返回类型为void（或返回值为null）的方法还具有ServletResponse，OutputStream参数或@ResponseStatus批注，则认为该方法已完全处理了响应。 如果控制器进行了肯定的ETag或lastModified时间戳检查，也是如此（请参阅控制器以获取详细信息）。 如果以上条件都不成立，则void返回类型还可以为REST控制器指示“无响应正文”，或者为HTML控制器指示默认视图名称选择。
DeferredResult	从任何线程异步生成任何上述返回值-例如，由于某些事件或回调的结果。请参见异步请求和DeferredResult。
Callable	在Spring MVC管理的线程中异步产生上述任何返回值。请参见异步请求和Callable。
ListenableFuture， java.util.concurrent.CompletionStage， java.util.concurrent.CompletableFuture	为方便起见，替代DeferredResult，（例如，当基础服务返回其中之一时）。
ResponseBodyEmitter， SseEmitter	异步发出对象流，以将其写入 HttpMessageConverter实现中。也支持作为ResponseEntity的主体。请参阅异步请求和HTTP流。
StreamingResponseBody	异步写入OutputStream响应。也支持作为ResponseEntity的主体 。请参阅异步请求和HTTP流。
反应类型-Reactor，RxJava或其他类型 ReactiveAdapterRegistry	DeferredResult的替代方法，其中包含收集到List的多值流（例如Flux，Observable）。 对于流场景（例如，text/event-stream, application/json+stream），使用SseEmitter和ResponseBodyEmitter代替，其中在Spring MVC管理的线程上执行ServletOutputStream阻塞I/O，并在完成时施加反压每个写入。 请参阅异步请求和响应类型。
任何其他返回值	如果返回值不是由BeanUtils#isSimpleProperty确定的简单类型，且它与该表中的任何较早值都不匹配且为String或void的任何返回值均被视为视图名称（通过RequestToViewNameTranslator选择默认视图名称） 。 简单类型的值仍然无法解析。

类型转换

如果参数声明为String以外的形式，则某些表示基于String的请求输入的带注释的控制器方法参数（例如@RequestParam，@RequestHeader，@PathVariable，@MatrixVariable和@CookieValue）可能需要类型转换。

在这种情况下，将根据配置的转换器自动应用类型转换。 默认情况下，支持简单类型（int，long，Date和其他）。 您可以通过WebDataBinder（请参见DataBinder）或通过在FormattingConversionService中注册Formatter来自定义类型转换。 参见Spring字段格式。

矩阵变量

RFC 3986讨论了路径段中的名称/值对。在Spring MVC中，我们根据Tim Berners-Lee 的“old post”将其称为“矩阵变量” ，但它们也可以称为URI路径参数。

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

如果期望URL包含矩阵变量，则控制器方法的请求映射必须使用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 matrixVars,
        @MatrixVariable(pathVar="petId") MultiValueMap petMatrixVars) {

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

请注意，您需要启用矩阵变量的使用。 在MVC Java配置中，您需要通过 路径匹配 设置具有removeSemicolonContent = false的UrlPathHelper。 在MVC XML名称空间中，可以设置。

代码示例：

@Configuration
@EnableWebMvc
public class MyWebMvcConfigurer implements WebMvcConfigurer {
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.setUrlPathHelper(urlPathHelper());
    }

    @Bean
    public UrlPathHelper urlPathHelper() {
        UrlPathHelper urlPathHelper = new UrlPathHelper();
        urlPathHelper.setRemoveSemicolonContent(false);
        return urlPathHelper;
    }
}

@RequestParam

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

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

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

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

    // ...

}

默认情况下，使用此注解的方法参数是必需的，但是您可以通过将@RequestParam注解的required标志设置为 false或通过使用java.util.Optional包装器声明参数来指定方法参数是可选的。

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

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

如果将@RequestParam注释声明为Map或 MultiValueMap，而未在注释中指定参数名称，则将使用每个给定参数名称的请求参数值填充映射。

请注意，@RequestParam的使用是可选的（例如，设置其属性）。 默认情况下，任何简单值类型的参数（由BeanUtils#isSimpleProperty确定）并且没有被任何其他参数解析器解析，就如同使用@RequestParam进行了注释一样。

@RequestHeader

您可以使用@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, 
        @RequestHeader("Keep-Alive") long keepAlive) { 
    //...
}

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

当@RequestHeader注解上的使用Map， MultiValueMap或HttpHeaders参数，则Map被填充有所有标头值。

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

@CookieValue

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

考虑带有以下cookie的请求：

JSESSIONID = 415A4AC178C59DACE0B2C9CA727CDD84

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

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

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

@ModelAttribute

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

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

上面的Pet实例解析如下：

• 来自模型（如果已使用Model添加）。
• 来自HTTP会话，通过使用@SessionAttributes。
• 来自URI路径变量，通过Converter传递（请参见下一个示例）。
• 来自默认构造函数的调用。
• 通过调用具有与Servlet请求参数匹配的参数的“主要构造函数”。 参数名称是通过JavaBeans @ConstructorProperties或字节码中运行时保留的参数名称确定的。

尽管通常使用模型来用属性填充模型，但另一种替代方法是依赖于Converter 与URI路径变量约定结合使用。 在以下示例中，模型属性名称account与URI路径变量account匹配，并且通过将String帐号传递给已注册的Converter 来加载Account：

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

获取模型属性实例后，将应用数据绑定。 WebDataBinder类将Servlet请求参数名称（查询参数和表单字段）与目标Object上的字段名称进行匹配。 必要时在应用类型转换后填充匹配字段。 有关数据绑定（和验证）的更多信息，请参见验证。 有关自定义数据绑定的更多信息，请参见DataBinder。

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

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

在某些情况下，您可能希望访问没有数据绑定的模型属性。对于这种情况，您可以将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 AccountForm form, BindingResult result,
        @ModelAttribute(binding=false) Account account) { 
    // ...
}

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

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

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

@SessionAttributes

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

以下示例使用@SessionAttributes注释：

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

在第一个请求上，将名称为pet的模型属性添加到模型时，该属性会自动升级到HTTP Servlet会话并保存在该会话中。它会一直保留在那里，直到另一个控制器方法使用SessionStatus方法参数来清除存储，如以下示例所示：

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

    // ...

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

代码示例：

@SessionAttributes("myIdx")
@RestController
public class MyController {

    @ModelAttribute("myIdx")
    public String myId() {
        return UUID.randomUUID().toString();
    }

    @GetMapping("myId2")
    public void myId2(HttpSession session, SessionStatus status) {
        System.out.println("1：" + session.getAttribute("myIdx"));
    }
}

@SessionAttribute

如果您需要访问全局管理（例如，在控制器外部（例如，通过过滤器））管理且可能存在或不存在的预先存在的会话属性，则可以在方法参数上使用@SessionAttribute注解，如下所示： 以下示例显示：

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

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

要将模型属性临时存储在会话中作为控制器工作流程的一部分，请考虑使用@SessionAttributes中所述 @SessionAttributes。

@RequestAttribute

与@SessionAttribute相似，您可以使用@RequestAttribute注解来访问先前创建的预先存在的请求属性（例如，通过Servlet Filter或HandlerInterceptor）：

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

重定向属性

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

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

RequestMappingHandlerAdapter提供了一个名为ignoreDefaultModelOnRedirect的标志，您可以使用该标志指示如果控制器方法重定向，则绝不要使用默认Model的内容。 相反，控制器方法应声明一个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属性。

代码示例

@Controller
public class MyController {

    @PostMapping("/files/{path}")
    public String upload(@PathVariable("path")String path) {
        // ...
        System.out.println("study.hwj.myspringmvc.MyController.upload");
        return "redirect:/files/my/{path}";
    }

    @RequestMapping("/files/my/{path}")
    public void mupload(@PathVariable("path") String path) {
        // ...
        System.out.println("study.hwj.myspringmvc.MyController.mupload");

        System.out.println(path);
        return ;
    }
}

Flash属性

Flash属性为一个请求提供了一种存储要在另一个请求中使用的属性的方式。重定向时最常需要此方法，例如Post-Redirect-Get模式。Flash属性在重定向之前（通常在会话中）被临时保存，以便在重定向之后可供请求使用，并立即被删除。

Spring MVC有两个主要的抽象来支持Flash属性。FlashMap用于保存Flash属性，而FlashMapManager用于存储，检索和管理 FlashMap实例。

Flash属性支持始终处于“打开”状态，无需显式启用。但是，如果不使用它，则永远不会导致HTTP会话创建。在每个请求上，都有一个“输入” FlashMap，该属性具有从前一个请求（如果有）传递过来的属性，而“输出”FlashMap则具有为后续请求保存的属性。FlashMap 可以通过Spring中的静态方法RequestContextUtils从Spring MVC中的任何位置访问这两个实例 。

带注释的控制器通常不需要直接使用FlashMap。而是， @RequestMapping方法可以接受RedirectAttributes类型的参数，并使用它为重定向方案添加Flash属性。通过添加的Flash属性将 RedirectAttributes自动传播到“输出” FlashMap。同样，重定向后，来自“输入”FlashMap的属性会自动添加到 服务于目标URL的控制器的Model。

将请求与Flash属性匹配

Flash属性的概念存在于许多其他Web框架中，并已证明有时会遇到并发问题。这是因为根据定义，Flash 属性将存储到下一个请求。但是，“下一个”请求可能不是预期的接收者，而是另一个异步请求（例如，轮询或资源请求），在这种情况下，过早删除了闪存属性。

为了减少此类问题的可能性，RedirectView会自动使用目标重定向URL的路径和查询参数“标记” FlashMap实例。 反过来，默认FlashMapManager在查找“输入” FlashMap时会将信息与传入请求匹配。

这不能完全消除并发问题的可能性，但是可以通过重定向URL中已经可用的信息大大减少并发问题。因此，我们建议您主要将Flash属性用于重定向方案。

Multipart

启用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 允许解析同一参数名的多个文件。

如果将@RequestParam注解声明为Map 或MultiValueMap ，但未在注解中指定参数名称，则将使用每个给定参数名称的多部分文件来填充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 ...

您可以使用@RequestParam作为字符串访问“元数据”部分，但您可能希望将其从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

您可以使用@RequestBody注解来使请求正文通过HttpMessageConverter读取并反序列化为Object。 以下示例使用@RequestBody参数：

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

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

您可以将@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

HttpEntity或多或少与使用@RequestBody相同，但是基于公开请求标头和正文的容器对象。 以下清单显示了一个示例：

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

@ResponseBody

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

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

@ResponseBody在类级别也受支持，在这种情况下，它由所有控制器方法继承。这就是@RestController的效果，无非就是带有@Controller和@ResponseBody标记的元注释。

您可以配合@ResponseBody使用反应类型。有关更多详细信息，请参见异步请求和响应类型。

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

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

ResponseEntity

ResponseEntity就像@ResponseBody但带有状态和标头。例如：

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

Spring MVC支持使用单值反应类型 来为主体生成异步ResponseEntity和/或单值和多值反应类型。

Jackson JSON

Spring提供了对Jackson JSON库的支持。

JSON视图

Spring MVC为Jackson的序列化视图提供了内置支持 ，该视图仅可呈现Object中所有字段的子集。要将其与 @ResponseBody或ResponseEntity控制器方法一起使用，可以使用Jackson的 @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允许一组视图类，但是每个控制器方法只能指定一个。如果需要激活多个视图，则可以使用复合接口。

对于依赖视图解析的控制器，可以将序列化视图类添加到模型中，如以下示例所示：

@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";
    }
}

参考：

@JsonView的使用

1.3.4. Model

您可以使用@ModelAttribute注释：

• 在@RequestMapping方法中的方法参数上，可从模型创建或访问对象，并将其通过WebDataBinder绑定到请求。
• 作为@Controller或@ControllerAdvice类中的方法级注释，可在任何@RequestMapping方法调用之前帮助初始化模型。
• 在@RequestMapping方法上标记其返回值的是模型属性。

本节讨论@ModelAttribute方法-前面列表中的第二项。 控制器可以具有任意数量的@ModelAttribute方法。 所有此类方法均在同一控制器中的@RequestMapping方法之前调用。 @ModelAttribute方法也可以通过@ControllerAdvice在控制器之间共享。 有关更多详细信息，请参见 Controller Advice 部分。

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

以下示例显示了一种@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);
}

如果未明确指定名称，则根据Object 类型选择默认名称，如javadoc中针对Conventions的解释。您始终可以使用重载addAttribute方法或通过nameon 的属性@ModelAttribute（用于返回值）来分配显式名称。

如果未明确指定名称，则根据Object 类型选择默认名称，如约定的javadoc中所述。 您始终可以使用重载的addAttribute方法或通过@ModelAttribute上的name属性（用于返回值）来分配显式名称。

您也可以将@ModelAttribute用作@RequestMapping方法上的方法级注释，在这种情况下，@RequestMapping方法的返回值将解释为模型属性。 通常不需要这样做，因为这是HTML控制器的默认行为，除非返回值是一个String，否则它将被解释为视图名称。 @ModelAttribute还可以自定义模型属性名称，如以下示例所示：

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

org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter#invokeHandlerMethod
先调用			modelFactory.initModel(webRequest, mavContainer, invocableMethod);
后调用			invocableMethod.invokeAndHandle(webRequest, mavContainer);


@ModelAttribute方法的调用栈：

pet:16, MyController (study.hwj.mymvc)
invoke0:-1, NativeMethodAccessorImpl (sun.reflect)
invoke:62, NativeMethodAccessorImpl (sun.reflect)
invoke:43, DelegatingMethodAccessorImpl (sun.reflect)
invoke:498, Method (java.lang.reflect)
doInvoke:190, InvocableHandlerMethod (org.springframework.web.method.support)
invokeForRequest:138, InvocableHandlerMethod (org.springframework.web.method.support)
invokeModelAttributeMethods:137, ModelFactory (org.springframework.web.method.annotation)
initModel:106, ModelFactory (org.springframework.web.method.annotation)
invokeHandlerMethod:865, RequestMappingHandlerAdapter (org.springframework.web.servlet.mvc.method.annotation)
handleInternal:793, RequestMappingHandlerAdapter (org.springframework.web.servlet.mvc.method.annotation)
handle:87, AbstractHandlerMethodAdapter (org.springframework.web.servlet.mvc.method)
doDispatch:1040, DispatcherServlet (org.springframework.web.servlet)
doService:943, DispatcherServlet (org.springframework.web.servlet)
processRequest:1006, FrameworkServlet (org.springframework.web.servlet)
doGet:898, FrameworkServlet (org.springframework.web.servlet)
service:634, HttpServlet (javax.servlet.http)
service:883, FrameworkServlet (org.springframework.web.servlet)
service:741, HttpServlet (javax.servlet.http)
internalDoFilter:231, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
doFilter:53, WsFilter (org.apache.tomcat.websocket.server)
internalDoFilter:193, ApplicationFilterChain (org.apache.catalina.core)
doFilter:166, ApplicationFilterChain (org.apache.catalina.core)
invoke:202, StandardWrapperValve (org.apache.catalina.core)
invoke:96, StandardContextValve (org.apache.catalina.core)
invoke:541, AuthenticatorBase (org.apache.catalina.authenticator)
invoke:139, StandardHostValve (org.apache.catalina.core)
invoke:92, ErrorReportValve (org.apache.catalina.valves)
invoke:688, AbstractAccessLogValve (org.apache.catalina.valves)
invoke:74, StandardEngineValve (org.apache.catalina.core)
service:343, CoyoteAdapter (org.apache.catalina.connector)
service:367, Http11Processor (org.apache.coyote.http11)
process:65, AbstractProcessorLight (org.apache.coyote)
process:868, AbstractProtocol$ConnectionHandler (org.apache.coyote)
doRun:1639, NioEndpoint$SocketProcessor (org.apache.tomcat.util.net)
run:49, SocketProcessorBase (org.apache.tomcat.util.net)
runWorker:1149, ThreadPoolExecutor (java.util.concurrent)
run:624, ThreadPoolExecutor$Worker (java.util.concurrent)
run:61, TaskThread$WrappingRunnable (org.apache.tomcat.util.threads)
run:748, Thread (java.lang)

1.3.5。 DataBinder

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

• 将请求参数（即表单或查询数据）绑定到模型对象。
• 将基于字符串的请求值（例如请求参数，路径变量，标头，Cookie等）转换为控制器方法参数的目标类型。
• 呈现HTML表单时，将模型对象值格式化为String值。

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

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

@Controller
public class FormController {

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

    // ...
}

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

@Controller
public class FormController {

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

    // ...
}

1.3.6. Exceptions

@Controller和@ControllerAdvice类可以具有处理控制器方法异常的@ExceptionHandler方法，如以下示例所示：

@Controller
public class SimpleController {

    // ...

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

该异常可以与正在传播的顶级异常（即，直接抛出的IOException异常）匹配，也可以与顶级包装异常（例如，IOException包装在IllegalStateException内）的直接原因匹配 。

对于匹配的异常类型，最好将目标异常声明为方法参数，如前面的示例所示。当多个异常方法匹配时，根源异常匹配通常比原因异常匹配更可取。更具体地，ExceptionDepthComparator用于根据异常从引发的异常类型的深度对异常进行排序。

另外，注释声明可以缩小异常类型以使其匹配，如以下示例所示：

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

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

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

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

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

在handle(Exception)变体中，行为甚至更简单。 在包装方案中，总是使用包装程序异常来调用此方法，在这种情况下，实际匹配的异常可以通过ex.getCause()找到。 仅当将它们作为顶级异常抛出时，传入的异常才是实际的FileSystemException或RemoteException实例。

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

在多@ControllerAdvice安排中，我们建议在以相应顺序优先的@ControllerAdvice上声明您的主根异常映射。 尽管根异常匹配优先于原因，但它是在给定控制器或@ControllerAdvice类的方法之间定义的。 这意味着，优先级较高的@ControllerAdvice Bean上的原因匹配优先于优先级较低的@ControllerAdvice Bean上的任何匹配（例如，根）。

最后但并非最不重要的一点是，@ExceptionHandler方法实现可以选择以不处理给定异常实例的方式将其以原始形式重新抛出。在仅对根级别匹配或无法静态确定的特定上下文中的匹配感兴趣的情况下，这很有用。重新抛出的异常会在其余的解决方案链中传播，就像给定的@ExceptionHandler方法最初不会匹配一样。

Spring MVC中对@ExceptionHandler方法的支持建立在DispatcherServlet 级别 HandlerExceptionResolver 机制上。

方法参数

@ExceptionHandler 方法支持以下参数：

方法参数	描述
异常类型	用于访问引发的异常。
HandlerMethod	用于访问引发异常的控制器方法。
WebRequest， NativeWebRequest	对请求参数以及请求和会话属性的常规访问，而无需直接使用Servlet API。
javax.servlet.ServletRequest， javax.servlet.ServletResponse	选择任何特定的请求或响应类型（例如ServletRequest或 HttpServletRequest或Spring的MultipartRequest或MultipartHttpServletRequest）。
javax.servlet.http.HttpSession	强制会话的存在。结果，这个参数永远不会为null。 请注意，会话访问不是线程安全的。 如果允许多个请求同时访问会话，请考虑将RequestMappingHandlerAdapter实例的syncnizeOnSession标志设置为true。
java.security.Principal	当前经过身份验证的用户-可能是特定的Principal实现类（如果已知）。
HttpMethod	请求的HTTP方法。
java.util.Locale	当前的请求语言设置，由最具体的可用LocaleResolver确定，实际上是配置的LocaleResolver或LocaleContextResolver。
java.util.TimeZone， java.time.ZoneId	与当前请求关联的时区，由LocaleContextResolver决定。
java.io.OutputStream， java.io.Writer	用于访问原始响应主体（由Servlet API公开）。
java.util.Map，org.springframework.ui.Model，org.springframework.ui.ModelMap	用于访问模型以进行错误响应。永远是空的。
RedirectAttributes	指定在重定向的情况下要使用的属性（要附加到查询字符串中），并指定要临时存储的属性，直到重定向后的请求为止。请参阅重定向属性和Flash属性。
@SessionAttribute	对于访问任何会话属性，与通过类级别@SessionAttributes声明存储在会话中的模型属性不同。 有关更多详细信息，请参见@SessionAttribute。
@RequestAttribute	用于访问请求属性。请参阅@RequestAttribute以获取更多详细信息。

返回值

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

返回值	描述
@ResponseBody	返回值通过HttpMessageConverter实例转换并写入响应。请参阅@ResponseBody。
HttpEntity， ResponseEntity	返回值指定完整的响应（包括HTTP标头和正文）将通过HttpMessageConverter实例转换并写入响应。参见ResponseEntity。
String	一个视图名称，将通过实现来解析，并与隐式模型一起使用-通过命令对象和@ModelAttribute方法确定。该处理程序方法还可以通过声明一个Model 变量（如前所述）以编程方式丰富模型。
View	用于与隐式模型一起渲染的View实例，该隐式模型是通过命令对象和@ModelAttribute方法确定的。 该处理程序方法还可以通过声明模型变量（如前所述）以编程方式丰富模型。
java.util.Map， org.springframework.ui.Model	要添加到隐式模型的属性，其视图名称是通过RequestToViewNameTranslator隐式确定的。
@ModelAttribute	要添加到模型的属性，其视图名称通过RequestToViewNameTranslator隐式确定。请注意，@ModelAttribute是可选的。请参见表末尾的“其他任何返回值”。
ModelAndView 对象	要使用的视图和模型属性，以及响应状态（可选）。
void	如果返回类型为void（或者返回值为null）的方法还具有ServletResponse，OutputStream参数或@ResponseStatus批注，则认为该方法已完全处理了响应。 如果控制器进行了肯定的ETag或lastModified时间戳检查，也是如此（请参阅 Controllers 以获取详细信息）。 如果以上所有条件都不成立，则对于REST控制器，void 返回类型也可以指示“无响应正文”，对于HTML控制器，则默认选择视图名称。
任何其他返回值	如果返回值与上述任何一个都不匹配并且不是简单类型（由BeanUtils＃isSimpleProperty确定 ），则默认情况下会将其视为要添加到模型的模型属性。如果它是简单类型，则仍无法解决。

REST API 异常

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

在响应主体中实现具有错误详细信息的全局异常处理的应用应考虑继承 ResponseEntityExceptionHandler，它提供对Spring MVC引发的异常的处理，并提供用于自定义响应主体的钩子。要使用此功能，请创建ResponseEntityExceptionHandler的子类 ，用@ControllerAdvice进行注释，覆盖必要的方法，然后将其声明为Spring bean。

代码示例

@ControllerAdvice
public class MyResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity