SpringMVC 教程 - Handler Method

原文连接：https://www.codemore.top/cates/Backend/post/2018-04-21/spring-mvc-handler-methods

由注解@RequestMapping注解修饰的处理请求的函数的签名很是的灵活，可使用controller函数支持的一系列参数和返回值。

函数参数

下列表格列出了controller方法能够接受的参数,稍后会对其进行详细的解释。 对于 JDK 8的java.util.Optional 能够在包含required属性的注解中使用，例如:@RequestParam,@RequestHeader等，至关于required=false

函数参数	解释
WebRequest,NativeWebRequest	无需直接使用Servlet API来访问请求参数，请求属性和session的属性。
javax.servlet.ServletRequest,javax.servlet.ServletResponse	能够是指定的请求和响应类型例如ServletRequest，HttpServletRequest，也能够是Spring的MultipartRequest,MultipartHttpServletRequest
HttpSession	参数永不为null，访问session非线程安全，若是多个请求访问一个session，须要设置RequestMappingHandlerAdapter的synchronizeOnSession为true。
PushBuilder	Servlet 4.0 支持HTTP/2 push的API，若是客户端不支持则为null
Principal	当前受权用户。
HttpMethod	请求的HTTP方法
Locale	当前请求的区域，由LocaleResolver解析
TimeZone,ZoneId	由LocaleContextResolver解析的当前请求的时区
InputStream,Reader	访问由Servlet API暴露的请求体
OutputStream,Writer	访问由Servlet API 暴露的响应体
@PathVairable	访问URI变量
@MatrixVariable	访问URI中的name-value值。例如 pets/42;q=11 @MatrixVariable int q
@Requestparam	访问请求中参数
@RequestHeader	访问请求头
@CookieValue	访问cookie值
@RequestBody	访问请求体，将请求体转换为相应类型
HttpEntity<B>	访问请求头和请求体
Map,Model,ModelMap	访问会在渲染模板时使用的变量。
RedirectAttributes	重定向时使用的属性
@ModelAttribute	访问model中的属性，同时进行数据绑定和校验
Errors, BindingResult	访问在数据绑定和校验是出现的错误。

类级别的 @SessionAttributes,SessionStatus | 在不一样的请求中存储session UriComponentsBuilder | 相对于当前请求的host，port，scheme等 @SessionAttribute | 访问session中的属性 @RequestAttribute| 访问请求的属性。 其余类型 | 若是参数非上述类型，那么将当成@RequestParam来处理

返回值

下列表格列出了支持的返回类型

返回值类型	解释
@ResponseBody	返回值由HttpMessageConverters转换，直接写到响应体
HttpEntity<B>, ResponseEntity<B>	返回值包括，http header和body
HttpHeaders	只返回HTTP header
String	由ViewResolver解析出具体的模板渲染。
View	返回具体的视图
Map,Model	model包含的属性，视图由RequestToViewNameTranslator解析
@ModelAttribute	返回添加到Model的属性，视图由RequestToViewNameTranslator解析.
ModelAndView	返回具体视图和添加的model
void	返回void，则Spring MVC会认为Controller内部已经处理好响应内容了。
DeferredResult<V>	异步返回结果，能够由任意线程处理
Callback<V>	异步返回，现成由Spring MVC管理
ListenableFuture<V>,CompletionStage<V>,CompletableFuture<V>	同DefferedResult
ResponseBodyEmitter,SseEmitter	使用HttpMessageConverter异步将对象以流的方式发到响应。
StreamingResponseBody	异步将响应发送的输出流
Reactor, RxJava, 等Reactive类型	同DeferredResult
其余类型	若是不返回以上类型，默认看成视图名称处理。

类型转换

一些须要参数的注解，例如@RequestParam,@RequestHeader,@PathVariabl,@MatrixVariable和@CookieValue，若是他么的参数并不是String，那么久须要进行类型转换。 类型转换自动由Spring MVC中注册的转换器来进行转换，默认状况下支持，int，long，Date等简单类型。对于不支持的类型能够经过WebDataBinder或者由FormattingConversionService注册的Formatter来进行转换。

Matrix 变量

RFC 3986规定了在路径中添加name-value对。在Spring MVC中，将其定义为matrix变量。 Matrix变量能够出如今任意的路径中，每一个变量由分号隔开，多个值由逗号隔开，例如：/cars;color=red,green;year=2012。多个值一样可也但是经过分离名字来指定，例如：color=red;color=green。 若是想要在路径中添加Matrix变量，那么就必须保证相应的controller方法包含接收matrix变量，而且请求映射不收到Matrix变量的影响。例如：

// GET /pets/42;q=11;r=22 @GetMapping("/pets/{petId}") public void findPet(@PathVariable String petId, @MatrixVariable int q) { // petId == 42 // q == 11 }

由于全部的路径都有可能包办Matrix变量，能够经过指定路径的形式分辨某个Matrix变量属于哪一个路径例如：

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

Matrix变量能够是可选的，指定默认值.例如：

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

可使用MultiValueMap获取全部的Matrix变量，例如：

// 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] }

默认状况下Spring MVC是不启用Matrix变量的，若是是用Java配置，能够经过配置UrlPathHelper的removeSemicolonContent=false启用，若是是使用XML配置，可使用<mvc:annotation-driven enable-matrix=variable="true"/>启用。

@RequestParam

@RequestParam能够将Servlet请求参数绑定到controller函数中的变量.例如：

@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 默认状况下是true，若是不但愿必须指定某个参数能够设置required=false或者若是使用Java 8 可使用java.util.Optional。 若是函数的参数非String类型，那么将会进行自动类型转换。 若是@RequsetParam修饰的是Map<String,String>或者MultiValueMap<String,String>那么就会获取全部的请求参数。

@RequestHeader

@RequestHeader将header的值绑定到controller的方法参数中。 例如一下做为请求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-Aliveheader

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

一样，若是参数非String类型，也会自动进行类型转换，若是修饰的是Map<String,String>,MultiValueMap<String,String>或者HttpHeaders，也是获取全部的header值

@CookieValue

使用@CookieValue将cookie值绑定到controller的方法参数中 例如如下cookie：

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

下列代码便可获取：

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

一样的，若是参数类型非String，会自动进行类型转换。

@ModelAttribute

使用@ModelAttribute修饰的函数参数能够访问Model中的属性，或者其未初始化是初始化。方法参数名和请求参数名相同，model 属性一样也能够覆盖其请求参数，这样就不须要本身再从请求参数中解析了。例如：

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

Pet 示例的获取：

• 若是Model中存在，则从Model中解析
• 经过@SessionAttributes获取
• 从URI的路径变量中获取
• 经过默认的构造函数获取
• 经过和Servlet请求参数相匹配的带参数的构造函数获取。参数名由@ConstructorProperties获取或者字节码获取。

固然通常都是使用Model来填充其值的，另外一个选择使用URI的路径变量，其值经过注册的Converter<String,T>转换。下面这个例子就是@ModelAttribute修饰的值和路径匹配，经过Converter<String,Account>进行类型转换。

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

获取了属性值的实例后就能够开始进行数据绑定了。WebDataBinder类经过匹配Servlet 的请求参数名（查询参数和form字段）来将字段名对应到对象中。当类型转换完以后填充匹配的字段。DataBinder和Validation将在后面章节详细描述。 数据绑定是会产生错误的，默认状况下会抛出BindException异常，为了在controller的方法中捕获这个异常，能够在方法参数中加入BindingResult获取异常。例如：

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

某些状况下只想要访问属性之而不须要数据绑定。这种状况下能够将设置@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) { // ... }

添加javax.util.validation.Valid或者Spring的@Validated注解，在数据绑定完成后会自动校验。例如：

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

@SessionAttributes

@SessionAttributes用于在不一样的请求间存储Servlet session的属性值。主要是列出须要在接下来的请求访问的session的值自动的保存到session中。例如：

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

第一次请求后这个带有pet名字的属性值将会自动的存到session中。直到另一个带有SessionStatus参数的方法将其清除。例如：

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

@SessionAttribute

若是想要访问一个以前存在的session的属性，可使用@SessionAttribute访问。例如：

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

请他状况下，须要添加或者删除session的时候，能够经过注入org.springframework.web.context.request.WebRequest或者javax.servlet.http.HttpSession实现Session的管理。

@RequestAttribute

和@SessionAttribute类似，@RequestAttribute能够访问请求以前（例如，Filter,HandlerInterceptor）建立的请求属性。例如：

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

重定向属性值

默认状况下，在重定向url中全部的属性值都经过URI的模版变量暴露。 例如：

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

Flash属性值

Flash属性值能够保存一个请求的数据使得另外一个请求可使用他的数据。最经常使用的场景就是重定向，例如：Post/Redirect/Get模式。在重定向以前临时将Flash属性保存（通常保存在session中）。这样在另外一个请求中就能够获取保存值，以后就会被当即删除。 Spring MVC 经过FlashMap和FlashMapManager支持Flash属性。FlashMap保存值，FlashMapManager用来保存，查询，管理FlashMap实例。 Flash属性默认开启，若是不使用则不会建立HTTP session。对于每一个请求来讲都有一个input的FlashMap，包含了上一个请求传递的属性和一个output的FlashMap包含须要传递的属性。这两个FlashMap均可以经过RequestContextUtils中的静态方法来获取。 通常来说controller不会直接使用FlashMap。其方法参数RedirectAttributes默认状况下使用flash map存储须要重定向的数据，保存到output的FlashMap中，重定向后，自动从input的FlashMap中获取数据添加到Model中。

Multipart

启用MultipartResolver后，若是POST请求包含了multipart/form-data，则其将会解析请求参数，获取Multipart。下面是上次文件的示例：

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

若是使用Servlet 3.0 则能够用javax.servlet.http.Part代替Spring的MultipartFile。 Multipart 的内容一样能够做为数据绑定的一部分，例如：

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

Multipart请求一样能够经过非浏览器提交，例如：下面是一个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来获取元信息，可是更好的作法是使用@RequestPart来获取其元信息。例如：

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

@RequestPart能够和javax.validation.Valid或者Spring的@Validated注解一同使用，经过标准的bean验证来校验数据的准确性。默认状况下校验错误抛出MethodArgumentNotValidException的异常，会直接返回404的错误。一样能够经过BindingResult来本身处理异常状况。

@RequestBody

使用了@RequestBody的参数经过HttpMessageConverter来将请求体反序列化成一个对象。下面是使用@RequestBody的示例：

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

@RequestBody一样能够和javax.validation.Valid或者Spring的@Validated注解一同使用。默认抛出的异常是MethodArgumentNotValidException处理方法同@RequestPart

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

HttpEntity

HttpEntity的使用和@RequestBody类似，不过他能够同时包含header和body。使用方法以下：

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

@ReponseBody

在方法中使用@ResponseBody修饰，则会自动的将返回值经过HttpMessageConverter的转换写入到响应体中。 使用方法以下：

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

@ResponseBody一样支持类级别，若是修饰controller类，那么全部的方法都会继承这个注解。这个和@RestController同样，@RestController就是@Controller和@RequestBody的组合。

ResponseEntity

ResponseEntity同@ResponseBody类似，只是其同时包含了响应的header和body。使用以下：

@PostMapping("/something") public ResponseEntity<String> handle() { // ... URI location = ... ; return ResponseEntity.created(location).build(); }

Jackson JSON

Spring MVC 内监了对Jackson序列化视图的支持。在使用ResponseEntity和@ResponseBody的时候可使用@JsonView来启动序列化的视图类。使用以下：

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

若是controller的方法返回的是一个字符串的视图，能够将其放到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

为了开启@ResponseBody和ResonseEntity的JSONP的支持，能够经过定义一个@ControllerAdvice的bean继承AbstractJsonpResponseBodyAdvice，其默认构造参数就是JSONP的查询参数，使用以下：

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