201902W9 Review, 一篇关于Spring RequestMapping的译文。

Spring RequestMapping

原文
by Eugen Paraschiv

1. 概述

在这篇文章中，我们将关注于这个Spring MVC中常用的注释 - @RequestMapping。

简单地说，这个注释用于将网络请求映射到Spring Controller的方法。

2. @RequestMapping基础

让我们从一个简单的例子开始 - 按照一些基本的标准将一个HTTP请求映射到一个方法。

2.1. @RequestMapping - 按路径

1
2
3
4
5
@RequestMapping(value = "/ex/foos", method = RequestMethod.GET)
@ResponseBody
public String getFoosBySimplePath() {
    return "Get some Foos";
}

要使用简单的curl命令测试此映射，请运行：

1
curl -i http://localhost:8080/spring-rest/ex/foos

2.2. @RequestMapping - HTTP方法

HTTP方法参数没有默认值 - 因此，如果我们不指定值，它将映射到任何HTTP请求。

这是一个简单的示例，类似于前一个示例 - 但这次映射到一个HTTP POST请求：

1
2
3
4
5
@RequestMapping(value = "/ex/foos", method = POST)
@ResponseBody
public String postFoos() {
    return "Post some Foos";
}

要通过curl命令测试POST ：
1
curl -i -X POST http://localhost:8080/spring-rest/ex/foos

3. RequestMapping 和 HTTP Headers

3.1. 带有headers Attribute的@RequestMapping

给请求指定一个header，可以进一步限制映射范围。

1
2
3
4
5
@RequestMapping(value = "/ex/foos", headers = "key=val", method = GET)
@ResponseBody
public String getFoosWithHeader() {
    return "Get some Foos with Header";
}

为了测试运行，我们将使用curl的header参数
1
curl -i -H "key:val" http://localhost:8080/spring-rest/ex/foos

更进一步，通过 @RequestMapping的 header属性实现多个header
1
2
3
4
5
6
7
@RequestMapping(
  value = "/ex/foos", 
  headers = { "key1=val1", "key2=val2" }, method = GET)
@ResponseBody
public String getFoosWithHeaders() {
    return "Get some Foos with Header";
}

可以通过命令测试这个方法
1
curl -i -H "key1:val1" -H "key2:val2" http://localhost:8080/spring-rest/ex/foos

注意，对于curl语法，用冒号分离header的键和值，与HTTP中的规范相同，而在Spring中是用等号。

3.2. @RequestMapping 消费和生产

映射由Controller产生的媒体类型的方法特别值得注意 - 我们可以通过上面介绍的 @RequestMapping 的headers属性，基于Accept header映射请求。

1
2
3
4
5
6
7
8
@RequestMapping(
  value = "/ex/foos", 
  method = GET, 
  headers = "Accept=application/json")
@ResponseBody
public String getFoosAsJsonFromBrowser() {
    return "Get some Foos with Header Old";
}

匹配这种定义Accept header的方法是灵活的 - 是用包含而不是等于，所以一个下面这样的请求也能正确地匹配。
1
curl -H "Accept:application/json,text/html" http://localhost:8080/spring-rest/ex/foos

从Spring 3.1开始， @RequestMapping注释具有produces和consumes属性，特别是为了这种：
1
2
3
4
5
6
7
8
9
@RequestMapping(
  value = "/ex/foos", 
  method = RequestMethod.GET, 
  produces = "application/json"
)
@ResponseBody
public String getFoosAsJsonFromREST() {
    return "Get some Foos with Header New";
}

此外，带有headers属性的旧类型的映射将自动转换成Spring 3.1开始的新produces机制，所以结果是相同的。

同样的方式，通过curl进行consume：

1
curl -H "Accept:application/json" http://localhost:8080/spring-rest/ex/foos

另外，produces也支持多值：
1
2
3
4
5
@RequestMapping(
  value = "/ex/foos", 
  method = GET,
  produces = { "application/json", "application/xml" }
)

记住这些 - 指定accept header的旧的方法和新的方法 - 基本上是相同的映射，所以Spring不允许它们一起使用 - 一起用将会导致：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Caused by: java.lang.IllegalStateException: Ambiguous mapping found. 
Cannot map 'fooController' bean method 
java.lang.String 
org.baeldung.spring.web.controller
  .FooController.getFoosAsJsonFromREST()
to 
{ [/ex/foos],
  methods=[GET],params=[],headers=[],
  consumes=[],produces=[application/json],custom=[]
}: 
There is already 'fooController' bean method
java.lang.String 
org.baeldung.spring.web.controller
  .FooController.getFoosAsJsonFromBrowser() 
mapped.

关于新的produces和consumes机制的最后一点 - 与其他注释表现不同的是 - 当指定类型级别时，方法级别的注释不会补充而会覆盖类型级别的信息。

这句没理解，原文

when specified at the type level, the method level annotations do not complement but override the type level information.

当然，如果你想深入了解用Spring构建REST API - 请看the new REST with Spring course。

4. RequestMapping使用路径变量

映射URI的一部分可以通过 @PathVariable注解绑定到变量。

4.1 单个 @PathVariable

一个简单的单路径变量例子：

1
2
3
4
5
6
@RequestMapping(value = "/ex/foos/{id}", method = GET)
@ResponseBody
public String getFoosBySimplePathWithPathVariable(
  @PathVariable("id") long id) {
    return "Get a specific Foo with id=" + id;
}

可以用curl测试：
1
curl http://localhost:8080/spring-rest/ex/foos/1

如果方法的参数名和路径名相同，可以只用 @PathVariable 而不附加值：
1
2
3
4
5
6
@RequestMapping(value = "/ex/foos/{id}", method = GET)
@ResponseBody
public String getFoosBySimplePathWithPathVariable(
  @PathVariable String id) {
    return "Get a specific Foo with id=" + id;
}

注意 @PathVariable 受利于自动类型转换，所以我们也可以修饰id为：
1
@PathVariable long id

4.2 多个 @PathVariable

更复杂的URI可能需要映射URI的多个部分到多个值：

1
2
3
4
5
6
7
@RequestMapping(value = "/ex/foos/{fooid}/bar/{barid}", method = GET)
@ResponseBody
public String getFoosBySimplePathWithPathVariables
  (@PathVariable long fooid, @PathVariable long barid) {
    return "Get a specific Bar with id=" + barid + 
      " from a Foo with id=" + fooid;
}

同样这可以用curl容易的测试：
1
curl http://localhost:8080/spring-rest/ex/foos/1/bar/2

4.3 带正则表达式的 @PathVariable

正则表达式也能用来映射 @PathVariable；举个例子，我们可以限制映射id只接受数字类型的值：

1
2
3
4
5
6
@RequestMapping(value = "/ex/bars/{numericId:[\\d]+}", method = GET)
@ResponseBody
public String getBarsBySimplePathWithPathVariable(
  @PathVariable long numericId) {
    return "Get a specific Bar with id=" + numericId;
}

这将意味着下面的URI可以适配：
1
http://localhost:8080/spring-rest/ex/bars/1

但这个不能：
1
http://localhost:8080/spring-rest/ex/bars/abc

5. RequestMapping使用Request Parameters

@RequestMapping允许方便的使用 @RequestParam注解映射URL参数。

我们现在映射一个这样的URI请求：

1
http://localhost:8080/spring-rest/ex/bars?id=100

1
2
3
4
5
6
@RequestMapping(value = "/ex/bars", method = GET)
@ResponseBody
public String getBarBySimplePathWithRequestParam(
  @RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;
}

我们接着在controller方法中使用 @RequestParam(“id”) 注解取出id参数的值。

要发送带id参数的请求，我们在curl中使用参数支持：

1
curl -i -d id=100 http://localhost:8080/spring-rest/ex/bars

在这个例子中，参数直接绑定而不先声明。

对于更进一步的场景， @RequestMapping有可选的参数定义 - 作为又一个限制请求映射的方法：

1
2
3
4
5
6
@RequestMapping(value = "/ex/bars", params = "id", method = GET)
@ResponseBody
public String getBarBySimplePathWithExplicitRequestParam(
  @RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;
}

甚至可以更灵活的映射 - 可以设置多个params值，并且不是所有都使用：
1
2
3
4
5
6
7
8
9
@RequestMapping(
  value = "/ex/bars", 
  params = { "id", "second" }, 
  method = GET)
@ResponseBody
public String getBarBySimplePathWithExplicitRequestParams(
  @RequestParam("id") long id) {
    return "Narrow Get a specific Bar with id=" + id;
}

当然，一个像这样的请求URI：
1
http://localhost:8080/spring-rest/ex/bars?id=100&second=something

将总会被映射到最好的适配 - 更进一步的适配，同时定义id和second参数。

6. RequestMapping Corner Cases

6.1. @RequestMapping – 多个路径映射到同一Controller方法

虽然一个单个 @RequestMapping路径值通常用于单个controller方法， 但这只是一种好的用法，而不是强制规则 - 有一些情况下，多个请求到同一方法的可能是必要的。在那种情况下， @RequestMapping的value属性接收多个映射，而不是一个映射：

1
2
3
4
5
6
7
@RequestMapping(
  value = { "/ex/advanced/bars", "/ex/advanced/foos" }, 
  method = GET)
@ResponseBody
public String getFoosOrBarsByPath() {
    return "Advanced - Get some Foos or Bars";
}

现在，这两个curl命令应该使用相同的方法：
1
2
curl -i http://localhost:8080/spring-rest/ex/advanced/foos
curl -i http://localhost:8080/spring-rest/ex/advanced/bars

6.2. @RequestMapping – 多个HTTP请求方法到同一个controller方法

用不同HTTP请求方式的多个请求可以被映射到同一个Controller方法：

1
2
3
4
5
6
7
8
@RequestMapping(
  value = "/ex/foos/multiple", 
  method = { RequestMethod.PUT, RequestMethod.POST }
)
@ResponseBody
public String putAndPostFoos() {
    return "Advanced - PUT and POST within single method";
}

用curl，这些请求都被打到同一个方法：
1
2
curl -i -X POST http://localhost:8080/spring-rest/ex/foos/multiple
curl -i -X PUT http://localhost:8080/spring-rest/ex/foos/multiple

6.3. @RequestMapping - 对所有请求的返回

对所有请求实现一个返回，可以使用一个特别的HTTP方法 - 例如，对GET方法：

1
2
3
4
5
@RequestMapping(value = "*", method = RequestMethod.GET)
@ResponseBody
public String getFallback() {
    return "Fallback for GET Requests";
}

或者对所有请求：
1
2
3
4
5
6
7
@RequestMapping(
  value = "*", 
  method = { RequestMethod.GET, RequestMethod.POST ... })
@ResponseBody
public String allFallback() {
    return "Fallback for All Requests";
}

6.4 模糊映射错误

模糊映射错误发生与：当Spring评估两个或多个请求映射对于不同的Controller方法是相同的。当两个请求映射有同样的HTTP方法、URL、参数、头部和媒体类型时，它们就是相同的。例如，这是一个模糊映射：

1
2
3
4
5
6
7
8
9
@GetMapping(value = "foos/duplicate")
public String duplicate() {
    return "Duplicate";
}
 
@GetMapping(value = "foos/duplicate")
public String duplicateEx() {
    return "Duplicate";
}

抛出的异常通常在这些行有异常信息：
1
2
3
4
5
6
Caused by: java.lang.IllegalStateException: Ambiguous mapping.
  Cannot map 'fooMappingExamplesController' method 
  public java.lang.String org.baeldung.web.controller.FooMappingExamplesController.duplicateEx()
  to {[/ex/foos/duplicate],methods=[GET]}:
  There is already 'fooMappingExamplesController' bean method
  public java.lang.String org.baeldung.web.controller.FooMappingExamplesController.duplicate() mapped.

仔细阅读错误信息，指出Spring不能映射方法org.baeldung.web.controller.FooMappingExamplesController.duplicateEx() ，因为它与一个已经映射的org.baeldung.web.controller.FooMappingExamplesController.duplicate() 有冲突。

下面这个代码段将不会产生模糊映射错误，因为两个方法返回不同的内容类型：

1
2
3
4
5
6
7
8
9
@GetMapping(value = "foos/duplicate", produces = MediaType.APPLICATION_XML_VALUE)
public String duplicate() {
    return "Duplicate";
}
 
@GetMapping(value = "foos/duplicate", produces = MediaType.APPLICATION_JSON_VALUE)
public String duplicateEx() {
    return "Duplicate";
}

7. 新的请求映射捷径

Spring Framework 4.3引入了一些新的HTTP映射注释，所有这些都基于 @RequestMapping ：

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

这些新的注解可以提高可读性，减少代码冗长。让我们看看这些新的注解在创建一个支持CRUD操作RESTFUL API的实例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@GetMapping("/{id}")
public ResponseEntity<?> getBazz(@PathVariable String id){
    return new ResponseEntity<>(new Bazz(id, "Bazz"+id), HttpStatus.OK);
}
 
@PostMapping
public ResponseEntity<?> newBazz(@RequestParam("name") String name){
    return new ResponseEntity<>(new Bazz("5", name), HttpStatus.OK);
}
 
@PutMapping("/{id}")
public ResponseEntity<?> updateBazz(
  @PathVariable String id,
  @RequestParam("name") String name) {
    return new ResponseEntity<>(new Bazz(id, name), HttpStatus.OK);
}
 
@DeleteMapping("/{id}")
public ResponseEntity<?> deleteBazz(@PathVariable String id){
    return new ResponseEntity<>(new Bazz(id), HttpStatus.OK);
}

深入了解这些可以在这里找到。

8. Spring配置

Spring MVC的配置足够简单 - 考虑到我们的FooController被定义在接下来的包里:

1
2
3
4
package org.baeldung.spring.web.controller;
 
@Controller
public class FooController { ... }

我们只用一个 @Configuration 去启用完整的MVC支持并为控制器配置类路径扫描：
1
2
3
4
5
6
@Configuration
@EnableWebMvc
@ComponentScan({ "org.baeldung.spring.web.controller" })
public class MvcConfig {
    //
}

9. 结论

这篇文章专注于Spring的 @RequestMapping 注解 - 讨论一个简单的用例, HTTP头的映射, @PathVariable 绑定URI部分, 使用URL参数工作, 和使用 @RequestParam 注解.

如果你想学习如何使用另一个Spring MVC的核心注解, 你可以在这浏览 @ModelAttribu 注解.

这篇文章的全部代码在Github可见. 这是一个Maven项目, 所以它可以很容易被导入和运行.


#Review #Spring #RequestMapping
2019 年 03 月 02 日