Spring 4 官方文档学习（十一）Web MVC 框架

<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
    <property name="messageConverters">
        <util:list id="beanList">
            <ref bean="stringHttpMessageConverter"/>
            <ref bean="marshallingHttpMessageConverter"/>
        </util:list>
    </property
</bean><bean id="stringHttpMessageConverter"
        class="org.springframework.http.converter.StringHttpMessageConverter"/><bean id="marshallingHttpMessageConverter"
        class="org.springframework.http.converter.xml.MarshallingHttpMessageConverter">
    <property name="marshaller" ref="castorMarshaller"/>
    <property name="unmarshaller" ref="castorMarshaller"/>
</bean><bean id="castorMarshaller" class="org.springframework.oxm.castor.CastorMarshaller"/>

@RequestBody 注解的方法参数还可以使用@Valid注解，Spring会使用配置好的Validator实例来校验该参数。当使用MVC命名空间或MVC Java config时，一个JSR-303 validator会被自定的配置 — 假如classpath中有一个JSR-303实现。

就像使用@ModelAttribute注解的参数已有，Errors参数可以用来检查errors。如果没有声明这样一个参数，会抛出一个MethodArgumentNotValidException。该异常由DefaultHandlerExceptionResolver来处理，会返回400 error。

使用@ResponseBody注解来映射response body

@ResponseBody注解类似于@RequestBody。该注解放在方法上指示返回类型会被写入HTTP response body （没有被放入Model，或被解释成view name）。 例如：

@GetMapping("/something")
@ResponseBody
public String helloWorld() {
    return "Hello World";
}

上面的例子，会将字符串写入HTTP response stream。

如同@RequestBody，Spring会将返回的对象转换成一个response body — 使用一个HttpMessageConverter。

使用@RestController注解创建一个REST Controller

使用@RestController代替@ResponseBody与@Controller。它虽然是由后两者组合而成，但在将来会被赋予更多语义。

@RestController也可以配合@ControllerAdvice或@RestControllerAdvice beans。详见 the the section called “Advising controllers with @ControllerAdvice and @RestControllerAdvice” section。

使用HttpEntity

HttpEntity 类似于 @RequestBody和@ResponseBody。除了能获取request和response body之外，HttpEntity（以及其response子类：ResponseEntity）还允许获取request和response  headers，如下：

@RequestMapping("/something")
public ResponseEntity<String> handle(HttpEntity<byte[]> requestEntity) throws UnsupportedEncodingException {
    String requestHeader = requestEntity.getHeaders().getFirst("MyRequestHeader");
    byte[] requestBody = requestEntity.getBody();    // do something with request header and body    HttpHeaders responseHeaders = new HttpHeaders();
    responseHeaders.set("MyResponseHeader", "MyValue");
    return new ResponseEntity<String>("Hello World", responseHeaders, HttpStatus.CREATED);
}

The above example gets the value of the MyRequestHeader request header, and reads the body as a byte array. It adds the MyResponseHeader to the response, writes Hello World to the response stream, and sets the response status code to 201 (Created).

As with @RequestBody and @ResponseBody, Spring uses HttpMessageConverter to convert from and to the request and response streams. For more information on these converters, see the previous section and Message Converters.

在方法上使用@ModelAttribute

该注解可以用在方法或方法参数上。本部分讲解用在方法上的作用，下一部分会讲解用在方法参数上的作用。

在方法上使用该注解，意味着该方法的一个目的是增加一个或多个model attribute。该方法支持的参数类型与@RequestMapping methods一样，但不能直接映射到请求。相反，同一个Controller中的@ModelAttribute methods会在@RequestMapping methods之前被调用！！！例子：

// 添加一个 attribute
// 该方法的返回值会被添加到model account中
// 你可以定义该model的名字，例如 @ModelAttribute("myAccount")@ModelAttribute
public Account addAccount(@RequestParam String number) {
    return accountManager.findAccount(number);
}// 添加多个 attributes@ModelAttribute
public void populateModel(@RequestParam String number, Model model) {
    model.addAttribute(accountManager.findAccount(number));
    // add more ...
}

@ModelAttribute methods被用于将常用的attributes填入model。

注意两种形式的@ModelAttribute methods。第一个，是隐式的将返回值添加为attribute。第二个，接收一个Model，然后在其中增加任意数量的model attributes。

一个Controller可以拥有任意数量的@ModelAttribute methods。所有这些方法都会在同一个Controller中的@RequestMapping methods之前被调用！

@ModelAttribute methods 也可以被定义在@ControllerAdvice class内，这样的methods会被用于所有Controllers。–就是在所有Controller的所有@RequestMapping methods之前被调用！

如果没有显式指定一个model attribute name，会发生什么？这种情况下，会基于其类型赋予一个默认的名字。例如，如果方法返回了Account类型，那默认的name就是account。

@ModelAttribute注解也可以用在@RequestMapping methods上。这种情况下，方法的返回值被解释成一个model attribute，而非view name。view name会基于name惯例而获取到，更像是返回了void。 see Section 22.13.3, “The View – RequestToViewNameTranslator”。

在方法参数上使用@ModelAttribute

当@ModelAttribute用于方法参数上时，代表该参数应该从该model中获取。如果model中没有，该参数会先被实例化，再被添加到model。一旦出现在model中，该参数的字段会被匹配名字的request parameters填充。这就是Spring MVC中的数据绑定（data binding），一个非常有用的机制，节省了你手动解析每个form字段的时间。

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

上面的例子，Pet实例从哪里来？有几个选项：

• 可能已经存在于@SessionAttributes的model中。

• 可能已经存在于同一个Controller的@ModelAttribute method的model中。
• 可能基于URI模板变量和类型转换器而获取（稍后详解）。
• 可能使用其默认构造器实例化。

@ModelAttribute method是从数据库中获取attribute的一种常用方式，可能可选的存储于requests之间–通过使用@SessionAttributes。某些情况下，使用URI模板变量和类型转换器更为方便。例子：

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

上面的例子，model attribute的name与URI模板变量的名字一致。如果你注册了一个Converter<String, Account>，那么上面的例子就可以不必使用一个@ModelAttribute method。

下一步就是数据绑定。WebDataBinder类会匹配request parameter names — 包含query string parameters 和 form fields — 到model attribute fields，根据名字。匹配的字段会被填充–当必要的类型转换被应用了之后。Data binding and validation are covered in Chapter 9, Validation, Data Binding, and Type Conversion. Customizing the data binding process for a controller level is covered in the section called “Customizing WebDataBinder initialization”.

数据绑定的一个结果是，可能存在errors，例如缺失必须的字段或者类型转换错误。为了检查该类错误，需要在@ModelAttribute argument之后紧跟着添加一个BindingResult argument。

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

使用BindingResult，你可以检查是否有errors，可以使用Spring的<errors> form tag来在同一个form中显示错误。

注意，某些情况下，不使用数据绑定而获取model中的一个attribute很有用。这些情况下，你可以在Controller中注入Model，或者在注解上使用binding flag，如下：

@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) {    // ...
}

In addition to data binding you can also invoke validation using your own custom validator passing the same BindingResult that was used to record data binding errors. That allows for data binding and validation errors to be accumulated in one place and subsequently reported back to the user:

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

— 就是根据BindingResult的结果进行自己的操作。

或者，可以使用JSR-303 @Valid注解来自动调用校验：

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

使用@SessionAttributes在requests之间的HTTP session中存储model attributes

type-level @SessionAttributes注解，声明了用于特定handler的session attributes。这会列出model attributes的names或types — 应该透明的存储于session或某conversational storage，在后续的requests中作为form-backing beans。

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

使用@SessionAttribute访问预存的全局session attributes

如果需要访问pre-existing global session attributes，就是在controller外部（例如在filter中）管理的 ，且可能或可能不会出现在method parameter上使用@SessionAttribute注解（–什么鬼）（If you need access to pre-existing session attributes that are managed globally, i.e. outside the controller (e.g. by a filter), and may or may not be present use the @SessionAttribute annotation on a method parameter）。

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

当需要增加或移除session attributes时，可以考虑在controller method上注入 org.springframework.web.context.request.WebRequest 或 javax.servlet.http.HttpSession。

为了在session中临时存储model attributes以作为controller workflow的一部分，可以考虑使用SessionAttributes as described in the section called “Using @SessionAttributes to store model attributes in the HTTP session between requests”.

使用@RequestAttribute来获取request attributes

类似于@SessionAttribute，@RequestAttribute也可以用于获取pre-existing request attributes — 由filter或interceptor创建的。

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

处理application/x-www-form-urlencoded data

前面的部分描述了使用@ModelAttribute来支持来自浏览器客户端的form submission requests。@ModelAttribute注解还被推荐用于处理来自非浏览器客户端的请求。然而，当处理HTTP PUT requests时，有一个显著的不同。浏览器会通过HTTP GET或HTTP POST提交表单数据。非浏览器客户端还可以通过HTTP PUT来提交。这就有一个问题，因为Servlet specification要求 ServletRequest.getParameter*()方法仅支持HTTP POST的字段获取，而非HTTP PUT。

为了支持HTTP PUT和PATCH 请求，spring-web模块提供了过滤器：HttpPutFormContentFilter。

<filter>
    <filter-name>httpPutFormFilter</filter-name>
    <filter-class>org.springframework.web.filter.HttpPutFormContentFilter</filter-class>
</filter><filter-mapping>
    <filter-name>httpPutFormFilter</filter-name>
    <servlet-name>dispatcherServlet</servlet-name>
</filter-mapping><servlet>
    <servlet-name>dispatcherServlet</servlet-name>
    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
</servlet>

上面的filter，会拦截content type为 application/x-www-form-urlencoded 的 HTTP PUT和PATCH请求，从其请求体中读取表单数据，封装ServletRequest以让ServletRequest.getParameter*() 能够使用表单数据。

由于HttpPutFormContentFilter会consume请求体，所以，不应为那些依赖针对 application/x-www-form-urlencoded 的转换器的PUT或PATCH URLs配置该filter。这包括@RequestBody MultiValueMap<String, String> 和 HttpEntity<MultiValueMap<String, String>>。

使用@CookieValue注解来映射cookie values

该注解允许一个方法参数绑定一个HTTP cookie的值。

假定从http request接收了如下cookie：

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

下面的代码演示了如何获取JSESSIONID cookie：

@RequestMapping("/displayHeaderInfo.do")
public void displayHeaderInfo(@CookieValue("JSESSIONID") String cookie) {
    //...
}

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

该注解，也被在Servlet和Portlet环境下的annotated handler methods支持。

使用@RequestHeader注解来映射request header attributes

这是一个样例request header：

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 headers的值：

@RequestMapping("/displayHeaderInfo.do")
public void displayHeaderInfo(@RequestHeader("Accept-Encoding") String encoding,
        @RequestHeader("Keep-Alive") long keepAlive) {
    //...
}

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

当@RequestHeader注解用于一个Map<String, String>、 MultiValueMap<String, String>，或HttpHeaders argument时，该map会被填入所有的header values。

内建的支持允许转换一个逗号间隔的字符串，将其转成一个字符串或其他类型的数组/集合。例如，@RequestHeader(“Accept”)注解的方法参数，可能是String类型，也可能是String[]或List<String>类型。

该注解，也被在Servlet和Portlet环境下的annotated handler methods支持。

method parameters 和 type conversion

http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-ann-typeconversion

从request中提取出来的基于字符串的值，包括request parameters、path variables、request headers、还有cookie values，可能需要被转成它们要绑定的method parameter或field的类型。如果目标类型不是String，Spring会自动转成合适的类型。支持所有简单类型，如int、long、Date等等。甚至，你可以使用一个WebDataBinder来定制转换过程，或者通过在FormattingConversionService中注册Formatters。

定制WebDataBinder 初始化

通过Spring的WebDataBinder使用PropertyEditors来定制request parameter 的绑定，你可以在你的controller中使用@InitBinder methods，或者在@ControllerAdvice class中使用@InitBinder methods，或者提供一个定制的WebBindingInitializer。 See the the section called “Advising controllers with @ControllerAdvice and @RestControllerAdvice” section for more details.

使用@InitBinder 定制数据绑定

在controller方法上使用@InitBinder，允许你在controller内部配置web数据绑定。@InitBinder代表方法初始化了WebDataBinder–会被用于填充被注解的handler方法的command 和 form object arguments。

这些init-binder methods，支持@RequestMapping所支持的所有参数，除了command/form objects和相应的校验结果对象。init-binder methods必须没有返回值。所以，大多被声明为void。 典型的arguments包括WebDataBinder 结合 WebRequest或 java.util.Locale，允许代码注册特定context的editors。

下面的案例演示了使用@InitBinder来配置针对所有java.util.Date form properties的一个CustomDateEditor。

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

或者，自Spring 4.2起，可以考虑使用addCustomFormatter来指定Formatter实现，取代PropertyEditor实例。

如果你在一个shared FormattingConversionService中有基于Formatter的设置，这会非常有用，只需要同样的做法来复用特定controller针对binding rules的调节。

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

配置一个定制的WebBindingInitializer

为了将数据绑定初始化外部化，你可以提供一个定制的WebBindingInitializer实现，然后通过提供一个定制的AnnotationMethodHandlerAdapter的bean configuration来启用它。

下面的例子示意了使用了org.springframework.samples.petclinic.web.ClinicBindingInitializer的配置，该配置配置了几个PetClinic controllers需要的PropertyEditors。

<bean class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
    <property name="cacheSeconds" value="0"/>
    <property name="webBindingInitializer">
        <bean class="org.springframework.samples.petclinic.web.ClinicBindingInitializer"/>
    </property>
</bean>

@InitBinder methods也可以定义在@ControllerAdvice class内，会用于所有的controllers。效果同WebBindingInitializer。See the the section called “Advising controllers with @ControllerAdvice and @RestControllerAdvice” section for more details.

advising controllers with @ControllerAdvice and @RestControllerAdvice

@ControllerAdvice注解，是一个component annotation，允许实现类能够在classpath扫描中被自动探测到。当使用MVC namespace或MVC Java config时，自动启用。

@ControllerAdvice class，可以含有@ExceptionHandler、@InitBinder以及@ModelAttribute methods，这些methods，会被应用到所有controller中的@RequestMapping methods，而非仅仅其所声明的controller中。

@RestControllerAdvice，等同于@ExceptionHandler + @ResponseBody methods。

@ControllerAdvice和@RestControllerAdvice 都可以指定作用的controllers：

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)
public class AnnotationAdvice {}// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
public class BasePackageAdvice {}// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})
public class AssignableTypesAdvice {}

详见@ControllerAdvice文档。

Jackson Serialization View Support

It can sometimes be useful to filter contextually the object that will be serialized to the HTTP response body. 为了提供这种能力，Spring MVC提供了内建的支持，可以rendering with Jackson’s Serialization Views.

在一个@Response controller method上，或者在那些返回ResponseEntity的controller methods上，简单的添加@JsonView注解，并指定需要使用的view class或Interface即可。如下：

@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允许指定多个class，但在controller method上使用时只能指定一个class！可以考虑使用复合接口，如果你需要启用多个views。

对于那些依赖view resolution的controllers，简单的将序列化view class添加到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";
    }
}

Jackson JSONP 支持

为了启用JSONP对@ResponseBody和@ResponseEntity methods的支持，声明一个@ControllerAdvice bean  — 需要继承AbstractJsonpResponseBodyAdvice，并在其构造中指出JSONP的query parameter name(s)。如下：

@ControllerAdvice
public class JsonpAdvice extends AbstractJsonpResponseBodyAdvice {    public JsonpAdvice() {
        super("callback");
    }
}

对于依赖view resolution的controllers，JSONP自动被启用，默认的query parameter name是 jsonp 或 callback。 可以通过其jsonpParameterNames property来定制。

http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html#mvc-ann-async

@PostMapping
public Callable<String> processUpload(final MultipartFile file) {    return new Callable<String>() {
        public String call() throws Exception {
            // ...
            return "someView";
        }
    };}

@RequestMapping("/quotes")
@ResponseBody
public DeferredResult<String> quotes() {
    DeferredResult<String> deferredResult = new DeferredResult<String>();
    // Save the deferredResult somewhere..
    return deferredResult;
}// In some other thread...
deferredResult.setResult(data);

@RequestMapping("/events")
public ResponseBodyEmitter handle() {
    ResponseBodyEmitter emitter = new ResponseBodyEmitter();
    // Save the emitter somewhere..
    return emitter;
}// In some other thread
emitter.send("Hello once");// and again later on
emitter.send("Hello again");// and done at some point
emitter.complete();

@RequestMapping("/download")
public StreamingResponseBody handle() {
    return new StreamingResponseBody() {
        @Override
        public void writeTo(OutputStream outputStream) throws IOException {
            // write...
        }
    };
}

<beans>
    <bean id="handlerMapping"
            class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping">
        <property name="interceptors">
            <list>
                <ref bean="officeHoursInterceptor"/>
            </list>
        </property>
    </bean>
    <bean id="officeHoursInterceptor"
            class="samples.TimeBasedAccessInterceptor">
        <property name="openingTime" value="9"/>
        <property name="closingTime" value="18"/>
    </bean>
</beans>

package samples;
public class TimeBasedAccessInterceptor extends HandlerInterceptorAdapter {
    private int openingTime;
    private int closingTime;
    public void setOpeningTime(int openingTime) {
        this.openingTime = openingTime;
    }
    public void setClosingTime(int closingTime) {
        this.closingTime = closingTime;
    }
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response,
            Object handler) throws Exception {
        Calendar cal = Calendar.getInstance();
        int hour = cal.get(HOUR_OF_DAY);
        if (openingTime <= hour && hour < closingTime) {
            return true;
        }
        response.sendRedirect("http://host.com/outsideOfficeHours.html");
        return false;
    }
}