Spring RequestMapping – 春天的RequestMapping

最后修改: 2013年 5月 16日


1. Overview


In this tutorial, we’ll focus on one of the main annotations in Spring MVC: @RequestMapping.

在本教程中,我们将重点讨论Spring MVC中的一个主要注释:@RequestMapping.

Simply put, the annotation is used to map web requests to Spring Controller methods.


2. @RequestMapping Basics

2.@RequestMapping 基础知识

Let’s start with a simple example: mapping an HTTP request to a method using some basic criteria.


2.1. @RequestMapping — by Path

2.1.@RequestMapping – by Path

@RequestMapping(value = "/ex/foos", method = RequestMethod.GET)
public String getFoosBySimplePath() {
    return "Get some Foos";

To test out this mapping with a simple curl command, run:


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

2.2. @RequestMapping — the HTTP Method

2.2.@RequestMapping – HTTP方法

The HTTP method parameter has no default. So, if we don’t specify a value, it’s going to map to any HTTP request.

HTTP method参数没有默认值。所以,如果我们不指定一个值,它就会映射到任何HTTP请求。

Here’s a simple example, similar to the previous one, but this time mapped to an HTTP POST request:

下面是一个简单的例子,与前面的例子类似,但这次是映射到一个HTTP POST请求。

@RequestMapping(value = "/ex/foos", method = POST)
public String postFoos() {
    return "Post some Foos";

To test the POST via a curl command:


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

3. RequestMapping and HTTP Headers

3.RequestMapping和HTTP Headers

3.1. @RequestMapping With the headers Attribute


The mapping can be narrowed even further by specifying a header for the request:


@RequestMapping(value = "/ex/foos", headers = "key=val", method = GET)
public String getFoosWithHeader() {
    return "Get some Foos with Header";

To test the operation, we’re going to use the curl header support:


curl -i -H "key:val" http://localhost:8080/spring-rest/ex/foos

and even multiple headers via the headers attribute of @RequestMapping:


  value = "/ex/foos", 
  headers = { "key1=val1", "key2=val2" }, method = GET)
public String getFoosWithHeaders() {
    return "Get some Foos with Header";

We can test this with the command:


curl -i -H "key1:val1" -H "key2:val2" http://localhost:8080/spring-rest/ex/foos

Note that for the curl syntax, a colon separates the header key and the header value, the same as in the HTTP spec, while in Spring, the equals sign is used.


3.2. @RequestMapping Consumes and Produces

3.2.@RequestMapping 消耗和产生

Mapping media types produced by a controller method is worth special attention.


We can map a request based on its Accept header via the @RequestMapping headers attribute introduced above:

我们可以通过上面介绍的@RequestMapping headers属性,根据一个请求的Accept头进行映射。

  value = "/ex/foos", 
  method = GET, 
  headers = "Accept=application/json")
public String getFoosAsJsonFromBrowser() {
    return "Get some Foos with Header Old";

The matching for this way of defining the Accept header is flexible — it uses contains instead of equals, so a request such as the following would still map correctly:


curl -H "Accept:application/json,text/html" 

Starting with Spring 3.1, the @RequestMapping annotation now has the produces and consumes attributes, specifically for this purpose:

从Spring 3.1开始,@RequestMapping注解现在有producesconsumes属性,专门用于此目的。

  value = "/ex/foos", 
  method = RequestMethod.GET, 
  produces = "application/json"
public String getFoosAsJsonFromREST() {
    return "Get some Foos with Header New";

Also, the old type of mapping with the headers attribute will automatically be converted to the new produces mechanism starting with Spring 3.1, so the results will be identical.

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

This is consumed via curl in the same way:


curl -H "Accept:application/json" 

Additionally, produces supports multiple values as well:


  value = "/ex/foos", 
  method = GET,
  produces = { "application/json", "application/xml" }

Keep in mind that these — the old and new ways of specifying the Accept header — are basically the same mapping, so Spring won’t allow them together.


Having both these methods active would result in:


Caused by: java.lang.IllegalStateException: Ambiguous mapping found. 
Cannot map 'fooController' bean method 
{ [/ex/foos],
There is already 'fooController' bean method

A final note on the new produces and consumes mechanisms, which behave differently from most other annotations: When specified at the type level, the method-level annotations do not complement but override the type-level information.


And of course, if you want to dig deeper into building a REST API with Spring, check out the new REST with Spring course.

当然,如果你想更深入地了解用Spring构建REST API,检查一下新的REST with Spring课程

4. RequestMapping With Path Variables


Parts of the mapping URI can be bound to variables via the @PathVariable annotation.


4.1. Single @PathVariable


A simple example with a single path variable:


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

This can be tested with curl:


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

If the name of the method parameter matches the name of the path variable exactly, then this can be simplified by using @PathVariable with no value:


@RequestMapping(value = "/ex/foos/{id}", method = GET)
public String getFoosBySimplePathWithPathVariable(
  @PathVariable String id) {
    return "Get a specific Foo with id=" + id;

Note that @PathVariable benefits from automatic type conversion, so we could have also declared the id as:


@PathVariable long id

4.2. Multiple @PathVariable


A more complex URI may need to map multiple parts of the URI to multiple values:


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

This is easily tested with a curl in the same way:


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

4.3. @PathVariable With Regex


Regular expressions can also be used when mapping the @PathVariable.


For example, we will restrict the mapping to only accept numerical values for the id:


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

This will mean that the following URIs will match:



But this will not:



5. RequestMapping With Request Parameters


@RequestMapping allows easy mapping of URL parameters with the @RequestParam annotation.


We are now mapping a request to a URI:


@RequestMapping(value = "/ex/bars", method = GET)
public String getBarBySimplePathWithRequestParam(
  @RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;

We are then extracting the value of the id parameter using the @RequestParam(“id”) annotation in the controller method signature.


To send a request with the id parameter, we’ll use the parameter support in curl:


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

In this example, the parameter was bound directly without having been declared first.


For more advanced scenarios, @RequestMapping can optionally define the parameters as yet another way of narrowing the request mapping:


@RequestMapping(value = "/ex/bars", params = "id", method = GET)
public String getBarBySimplePathWithExplicitRequestParam(
  @RequestParam("id") long id) {
    return "Get a specific Bar with id=" + id;

Even more flexible mappings are allowed. Multiple params values can be set, and not all of them have to be used:


  value = "/ex/bars", 
  params = { "id", "second" }, 
  method = GET)
public String getBarBySimplePathWithExplicitRequestParams(
  @RequestParam("id") long id) {
    return "Narrow Get a specific Bar with id=" + id;

And of course, a request to a URI such as:



will always be mapped to the best match — which is the narrower match, which defines both the id and the second parameter.


6. RequestMapping Corner Cases


6.1. @RequestMapping — Multiple Paths Mapped to the Same Controller Method

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

Although a single @RequestMapping path value is usually used for a single controller method (just good practice, not a hard and fast rule), there are some cases where mapping multiple requests to the same method may be necessary.


In that case, the value attribute of @RequestMapping does accept multiple mappings, not just a single one:


  value = { "/ex/advanced/bars", "/ex/advanced/foos" }, 
  method = GET)
public String getFoosOrBarsByPath() {
    return "Advanced - Get some Foos or Bars";

Now both of these curl commands should hit the same method:


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

6.2. @RequestMapping — Multiple HTTP Request Methods to the Same Controller Method

6.2.@RequestMapping – 多个HTTP请求方法到同一个控制器方法

Multiple requests using different HTTP verbs can be mapped to the same controller method:


  value = "/ex/foos/multiple", 
  method = { RequestMethod.PUT, RequestMethod.POST }
public String putAndPostFoos() {
    return "Advanced - PUT and POST within single method";

With curl, both of these will now hit the same method:


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 — a Fallback for All Requests

6.3.@RequestMapping – 所有请求的回退

To implement a simple fallback for all requests using a particular HTTP method, for example, for a GET:


@RequestMapping(value = "*", method = RequestMethod.GET)
public String getFallback() {
    return "Fallback for GET Requests";

or even for all requests:


  value = "*", 
  method = { RequestMethod.GET, RequestMethod.POST ... })
public String allFallback() {
    return "Fallback for All Requests";

6.4. Ambiguous Mapping Error


The ambiguous mapping error occurs when Spring evaluates two or more request mappings to be the same for different controller methods. A request mapping is the same when it has the same HTTP method, URL, parameters, headers, and media type.


For example, this is an ambiguous mapping:


@GetMapping(value = "foos/duplicate" )
public String duplicate() {
    return "Duplicate";

@GetMapping(value = "foos/duplicate" )
public String duplicateEx() {
    return "Duplicate";

The exception thrown usually does have error messages along these lines:


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.

A careful reading of the error message points to the fact that Spring is unable to map the method org.baeldung.web.controller.FooMappingExamplesController.duplicateEx(), as it has a conflicting mapping with an already mapped org.baeldung.web.controller.FooMappingExamplesController.duplicate().


The code snippet below will not result in ambiguous mapping error because both methods return different content types:


@GetMapping(value = "foos/duplicate", produces = MediaType.APPLICATION_XML_VALUE)
public String duplicateXml() {
    return "<message>Duplicate</message>";
@GetMapping(value = "foos/duplicate", produces = MediaType.APPLICATION_JSON_VALUE)
public String duplicateJson() {
    return "{\"message\":\"Duplicate\"}";

This differentiation allows our controller to return the correct data representation based on the Accepts header supplied in the request.


Another way to resolve this is to update the URL assigned to either of the two methods involved.


7. New Request Mapping Shortcuts


Spring Framework 4.3 introduced a few new HTTP mapping annotations, all based on @RequestMapping:

Spring Framework 4.3引入了一些新的HTTP映射注释,全部基于@RequestMapping

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

These new annotations can improve the readability and reduce the verbosity of the code.


Let’s look at these new annotations in action by creating a RESTful API that supports CRUD operations:

让我们通过创建一个支持CRUD操作的RESTful API,来看看这些新注解的作用:

public ResponseEntity<?> getBazz(@PathVariable String id){
    return new ResponseEntity<>(new Bazz(id, "Bazz"+id), HttpStatus.OK);

public ResponseEntity<?> newBazz(@RequestParam("name") String name){
    return new ResponseEntity<>(new Bazz("5", name), HttpStatus.OK);

public ResponseEntity<?> updateBazz(
  @PathVariable String id,
  @RequestParam("name") String name) {
    return new ResponseEntity<>(new Bazz(id, name), HttpStatus.OK);

public ResponseEntity<?> deleteBazz(@PathVariable String id){
    return new ResponseEntity<>(new Bazz(id), HttpStatus.OK);

A deep dive into these can be found here.


8. Spring Configuration


The Spring MVC Configuration is simple enough, considering that our FooController is defined in the following package:

考虑到我们的FooController被定义在下面的包中,Spring MVC配置足够简单。

package org.baeldung.spring.web.controller;

public class FooController { ... }

We simply need a @Configuration class to enable the full MVC support and configure classpath scanning for the controller:


@ComponentScan({ "org.baeldung.spring.web.controller" })
public class MvcConfig {

9. Conclusion


This article focused on the @RequestMapping annotation in Spring, discussing a simple use case, the mapping of HTTP headers, binding parts of the URI with @PathVariable, and working with URI parameters and the @RequestParam annotation.


If you’d like to learn how to use another core annotation in Spring MVC, you can explore the @ModelAttribute annotation here.

如果您想了解如何在Spring MVC中使用另一个核心注解,您可以在这里探索@ModelAttribute注解

The full code from the article is available over on GitHub.