Spring MVC的常用注解（持续更新中）

---

前言

     Spring从2.5版本开始引入注解，用户可以在Spring MVC中使用@Controller @RequestMapping、@RequestParam、@ModelAttribute 等类似的注解。到目前为止，Spring的版本虽然发生了很大的变化，但注解的特性却一直延续下来，并不断扩展，让开发者的工作变得轻松简单。

Spring MVC中用于参数绑定的注解有很多，都在org.springframework.web.bind.annotation包中，根据它们处理的request的不同内容可以分为六类。

1. 处理请求参数和内容部分的注解:@RequestMapping、@RequestParam、@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping、@RequestBody、@ResponseBody、@RequestPart、@RestController
2. 处理请求URL部分的注解:@PathVariable、@MatrixVariable、@CrossOrigin
3. 处理请求头部分的注解:@RequestHeader、@CookieValue
4. 处理属性类型的注解:@RequestAttribute、@SessionAttribute、@SessionAttributes、@ModelAttribute
5. 处理异常类型的注解:@ExceptionHandler、@ControllerAdvice、@RestController、@ResponseStatus
6. 处理表单数据的注解:@InitBinder

---

@Controller 注解

1、前期准备

        Controller控制器是通过服务接口定义的提供访问应用程序的一种行为，它解释用户的输入，将其转换成一个模型然后将试图呈献给用户。Spring MVC 使用 @Controller 定义控制器，它还允许自动检测定义在类路径下的组件并自动注册。如想自动检测生效，需在XML头文件下引入 spring-context:

<?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: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-4.3.xsd">

<!-- 扫描找到控制层 -->
<context:component-scan base-package="com.packagename"></context:component-scan>

2、@Controller注解的使用
        HelloController 是一个基于@Controller注解的控制器，@RequestMapping注解用来映射一个请求，括号中的“/hello”表示请求由hello方法进行处理。hello方法接收了一个org.springframework.web.servlet.ModelAndView类型的参数，在mv中加入了一个名为"msg"的字符串对象，可以在返回的视图中通过request对象获取。最后，方法返回一个mv作为视图名称。

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

@Controller
public class HelloController {
	@RequestMapping("/hello")
	public ModelAndView hello() {
		ModelAndView mv = new ModelAndView("hello");
		mv.addObject("msg","success");
		return mv;
	}
}

在http://localhost:8080/项目名/hello中即可成功访问

---

@RequestMapping 注解

        我们可以 @RequestMapping 注解将类似 “/hello”这样的URL映射到整个类或特定的处理方法上。一般来说，类级别的注解映射特定的请求路径到表单控制器上，而方法级别的注解只是映射为一个特定的HTTP方法请求（“GET”，“POST”等）或HTTP请求参数。

package com.zrz.test;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

@Controller
public class HelloController {
	@RequestMapping(value="/login")
	public String login() {
		return "login";
	}
	@RequestMapping(value="/register")
	public String register() {
		return "register";
	}
}

在网页中访问两个地址

http://localhost:8080/项目名/login
http://localhost:8080/项目名/register

RequestMapping的六个属性：
1、value 属性
value是@RequestMapping注释的默认属性，因此如果只有唯一的属性，则可以忽略属性名

@RequestMapping(value="/login")
	public String login() {
		return "login";
	}
	
//与上方代码同样效果
@RequestMapping("/login")
	public String login() {
		return "login";
	}

2、method 属性
该属性用来指示该方法处理哪些HTTP请求方式

//只支持POST请求
@RequestMapping(value="/login",method=RequestMethod.Post)

//同时支持多个HTTP请求方式
@RequestMapping(value="/login",method={RequestMethod.Post,RequestMethod.GET})

/**在Spring4.3中引入了{@GetMapping、@PostMapping、@PutMapping、@DeleteMapping、@PatchMapping}，
其中@PatchMapping是对put方式的一种补充，put可以是更新，但是是对整体的更新，patch是对局部的更新**/

@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
@PatchMapping

//如果没有指定method属性值，则请求处理方法可以处理任意的HTTP请求方式

3、consumes 属性
该属性指定处理请求的提交内容类型(Content-Type)

//仅处理request Content-Type 为"application/json"类型的请求
@RequestMapping(value="/login",method=RequestMethod.Post,consumes="application/json")

4、produces 属性
该属性指定返回的内容类型，返回的内容类型必须是request请求头（Accept）中所包含的类型

//方法仅处理request请求中Accept头中包含了"application/json"的请求，
//同时指明了返回的内容类型为application/json
@RequestMapping(value="/login",method=RequestMethod.Post,produces="application/json")

5、params 属性
该属性指定request中必须包含某些参数值时，才让该方法处理

//方法仅处理其中名为"myParam"、值为"myValue"的请求
@RequestMapping(value="/login",method=RequestMethod.Post,params="myParam=myValue")

6、 headers 属性
该属性指定request中必须包含某些指定的header值时，才能让该方法处理请求

//方法仅处理header中包含了指定"Referer"请求头和对应值为"http://www.zrz.org/"的请求
@RequestMapping(value="/login",method=RequestMethod.Post,headers="Referer=http://www.zrz.org/")

---

@RequestParam 注解

这个注解是用于方法中为某个形参进行请求参数入参

@RequestMapping(value="/login")
	public ModelAndView login(
		@RequestParam("loginname") String loginname,
		@RequestParam("password") String password){
		retrun...;
	}

//假设url请求如下:
http://localhost:8080/context/login?loginname=jack&password=123456
//则以上代码会将loginname的值"jack"赋给loginname变量，password参数的值"123456"赋给password变量

上述写法若请求中不包含loginname参数，则将产生异常！
建议使用以下写法：
   @RequestParam(value = "loginname",required = false)
或者:
   @RequestParam(value = "loginname",required = true,defaultValue="admin")
//value=“请求中的参数名”，指定后就会将请求中的该参数入参匹配到，被该注解注释的形参中。
//required=true/false: 是指该参数是否必须存在于请求体中。 
//true：传入参数必须携带该参数，否则无法匹配成功。一般设置为false。
//defaultValue=“默认值”：即若参数传入为null，则为其设置默认值。
//其中required参数不是必需的，默认值为true

---

@PathVariable 注解

        该注解可以非常方便地获得请求URL中的动态参数。
@PathVariable注解可指定以下三个属性:

         @RequestMapping(value="/pathVariableTest/{userId}")
         // 使用@PathVariable("userId")  获取路径中的变量 userId 的值
     public void pathVariableTest(@PathVariable Integer userId) 
     
 假设请求的URL为"http://localhost:8080/VariableTest/pathVariable/1",
 则自动将URL中模板变量{userId} 绑定到通过@PathVariable注解的同名参数上，
 即userId变量将被赋值为1。

//name,指定请求参数绑定的名称，如果省略则绑定同名参数
//value=“请求中的参数名”，指定后就会将请求中的该参数入参匹配到，被该注解注释的形参中。
//required 指示参数是否必须绑定

---

@MatrixVariable 注解

        该注解扩展了URL请求地址的功能。
使用@MatrixVariable 注解时多个变量可以使用";"分分隔，该注解允许开发者进行多条件组合查询。

//映射的请求是/VariableTest/matrixVariableTest/{userId};name=Jack;age=23
@GetMapping(value="/martixVariableTest/{userId}")
public void matrixVariableTest(
@PathVariable Integer userId,
@MatrixVariable(value="name",pathVar="userId") String name,
@MatrixVariable(value="age",pathVar="userId") Integer age)

假设请求的URL为"http://localhost:8080/VariableTest/pathVariable/1;name=jack;age=23",
则自动将URL中模板变量{userId} 绑定到通过@PathVariable注解的同名参数上，
即userId变量将被赋值为1。
通过@MatrixVariable注解绑定name和age变量 

注意：
@MatrixVariable 注解功能在SpringMVC中默认是不启用的，启用它需要设置enable-matrix-variables=“true”。

<mvc:annocation-driven enable-matrix-variables="true"/>

---

@RequestHeader 注解

        该注解用于将请求的头信息数据映射到功能处理方法的参数上。

@RequestMapping(value="/requestHeaderTest")
      public void requestHeaderTest(
      @RequestHeader("User-Agent") String userAgent,
      @RequestHeader(value="Accept") String[] accepts)

以上配置自动将请求头"User-Agent"的值赋到userAgent变量上，并将请求头"Accept"的值赋到accepts变量上

---

@CookieValue 注解

        该注解用于将请求的Cookie数据映射到功能处理的参数上。

@RequestMapping(value="/cookieValueTest")
      public void cookieValueTest(
      @cookieValue(value="JSESSIONID",defaultValue="") String sessionId)

以上配置自动将Cookie中JSESSIONID的值设置到sessionId参数上，defaultValue表示cookie中没有JSESSIONID时默认为空

---

@RequestAttribute 注解

       该注解用于访问请求处理方法、过滤器或拦截器创建的、预先存在于request作用域中的属性，将该属性转换到目标方法的参数。

@RequestMapping(value="/arrtibuteTest")
      public void arrtibuteTest(
     @RequestAttribute(value="username") String username)

以上代码会自动将request作用域中名为username的属性的值设置到username参数上。

---

@SessionAttributes 注解

       该注解允许我们有选择地指定Model中的哪些属性转存到HttpSession对象当中。

@RequestMapping("/testSessionAttributes")    
public String testSessionAttributes(Map<String, Object> map) {        
User user = new User(1, "刘邦", "qwe", "123", "辽宁");        
map.put("user", user);        
map.put("school", "重庆");        
return "success";    
}}

注意：
@SessionAttributes 注解只能声明在类上，而不能声明在方法上

---

@ModelAttribute 注解

       该注解用于将请求参数绑定到对象。
       @ModelAttribute 注解只支持一个属性value，类型为String，表示绑定的属性名称。
       被@ModelAttribute注释的方法表示这个方法的目的是增加一个或多个模型(model)属性。这个方法和被@RequestMapping注释的方法一样也支持@RequestParam参数，但是它不能直接被请求映射。实际上，控制器中的@ModelAttribute方法是在同一控制器中的@RequestMapping方法被调用之前调用的。
       被@ModelAttribute注释的方法用于填充model属性，例如，为下拉菜单填充内容，或检索一个command对象（如，Account），用它来表示一个HTML表单中的数据。
       一个控制器可以有任意数量的@ModelAttribute方法。所有这些方法都在@RequestMapping方法被调用之前调用。
       有两种类型的@ModelAttribute方法。一种是：只加入一个属性，用方法的返回类型隐含表示。另一种是：方法接受一个Model类型的参数，这个model可以加入任意多个model属性。
注意：
       在被@ModelAttribute 注释的方法会在Controller 每个方法执行前被执行，因此在一个Controller被映射到多个URL时，要谨慎使用！

@Controller
public class ModelAttribute1Controller {
    //使用@ModelAttribute注释的value属性，来指定model属性的名称，model属性的值就是方法的返回值
    @ModelAttribute("loginName")
    }

@ModelAttribute 注解的使用有多种，将在后面单独写一篇该注解的多种使用。

---

@RequestBody 注解

       @RequestBody主要用来接收前端传递给后端的json字符串中的数据的(请求体中的数据的)；而最常用的使用请求体传参的无疑是POST请求了，所以使用@RequestBody接收数据时，一般都用POST方式进行提交。在后端的同一个接收方法里，@RequestBody与@RequestParam()可以同时使用，@RequestBody最多只能有一个，而@RequestParam()可以有多个。
       该注解接受的参数是来自request body中也就是请求体。一般用于处理非Content-Type：application/x-www-form-urlencoded编码格式的数据。比如application/json、application/xml等。
注意：
       1、一个请求，只有一个RequestBody；一个请求，可以有多个RequestParam。
       2、当同时使用@RequestParam（）和@RequestBody时，@RequestParam（）指定的参数可以是普通元素、数组、集合、对象等等(即:当，@RequestBody 与@RequestParam()可以同时使用时，原SpringMVC接收参数的机制不变，只不过RequestBody 接收的是请求体里面的数据；RequestParam接收的是key-value里面的参数，所以它会被切面进行处理从而可以用普通元素、数组、集合、对象等接收)。
即：如果参数时放在请求体中，application/json传入后台的话，那么后台要用@RequestBody才能接收到；如果不是放在请求体中的话，那么后台接收前台传过来的参数时，要用@RequestParam来接收，或则形参前 什么也不写也能接收。
       3、如果参数前写了@RequestParam(xxx)，那么前端必须有对应的xxx名字才行(不管其是否有值，当然可以通过设置该注解的required属性来调节是否必须传)，如果没有xxx名的话，那么请求会出错，报400。
       4、如果参数前不写@RequestParam(xxx)的话，那么就前端可以有可以没有对应的xxx名字才行，如果有xxx名的话，那么就会自动匹配；没有的话，请求也能正确发送。

---

@ResponseBody 注解

       @ResponseBody的作用其实是将java对象转为json格式的数据。
       @responseBody注解的作用是将controller的方法返回的对象通过适当的转换器转换为指定的格式之后，写入到response对象的body区，通常用来返回JSON数据或者是XML数据。
注意：在使用此注解之后不会再走视图处理器，而是直接将数据写入到输入流中，他的效果等同于通过response对象输出指定格式的数据。
注意：
       @ResponseBody是作用在方法上的，@ResponseBody 表示该方法的返回结果直接写入 HTTP response body 中，一般在异步获取数据时使用【也就是AJAX】。
       在使用 @RequestMapping后，返回值通常解析为跳转路径，但是加上 @ResponseBody 后返回结果不会被解析为跳转路径，而是直接写入 HTTP response body 中。 比如异步获取 json 数据，加上 @ResponseBody 后，会直接返回 json 数据。@RequestBody 将 HTTP 请求正文插入方法中，使用适合的 HttpMessageConverter 将请求体写入某个对象。