Mastering @RequestMapping in Spring Boot: Real‑World Examples & Tips

1. Introduction

@RequestMapping is an annotation in Spring MVC that maps HTTP requests to handler classes or methods. It can be applied at class or method level, allowing developers to define routing rules flexibly.

2. Practical Examples

2.1 Define Path

@RequestMapping(value = "/api/path")
public String path() {
  return "define path";
}

Test with:

curl http://localhost:8080/api/path

The value attribute can accept an array to map multiple paths:

@RequestMapping(value = {"/api/path1", "/api/path2"}, method = RequestMethod.GET)
public String path() { ... }

2.2 Set Request Method

@RequestMapping(value = "/api/method", method = RequestMethod.POST)
public String method() {
  return "request method";
}

Test with:

curl -i -X POST http://localhost:8080/api/method

Supported methods include GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE.

2.3 Set Request Header

@RequestMapping(value = "/api/header", headers = "x-pack=xxxooo")
public String header() {
  return "define Header";
}

Test with:

curl -i -H "x-pack:xxxooo" http://localhost:8080/api/header

Multiple headers can be specified:

@RequestMapping(value = "/api/header",
  headers = {"x-pack=xxxooo", "x-key=aabbcc"})
public String header() { ... }

curl -i -H "x-pack:xxxooo" -H "x-key:aabbcc" http://localhost:8080/api/header

2.4 Specify produces

@GetMapping(value = "/api/produces", produces = "application/json")
public String produces() {
  return "define produces";
}

This restricts the request to Accept header of application/json, equivalent to setting the header directly.

2.5 Specify consumes

@GetMapping(value = "/api/consumes", consumes = {"text/plain"})
public String consumes() {
  return "define consumes";
}

Test with:

curl -H "Content-Type:text/plain" http://localhost:8080/api/consumes

2.6 Use Path Variables

@RequestMapping(value = "/api/var/{id}")
public String pathVar(@PathVariable("id") long id) {
  return String.format("id = %d", id);
}

2.7 Set Request Parameters

@RequestMapping(value = "/api/params", params = "id")
public String params(Long id) {
  return "params id =" + id;
}

Multiple parameters can be required:

@RequestMapping(value = "/api/params", params = {"id","name"})
public String params(Long id) { ... }

2.8 Fallback Mapping

@RequestMapping(value = "*")
public String fallback() {
  return "Fallback for GET Requests";
}

Handles requests when no specific URI matches.

2.9 Ambiguous Mapping Errors

When two controller methods have identical HTTP method, URL, parameters, headers, and media types, Spring throws an ambiguous mapping error.

@PackMapping(value = "/api/params", params = "id")
public String params(Long id) { ... }

@PackMapping(value = "/api/params", params = "id")
public String params1(Long id) { ... }

The following screenshot illustrates such an error:

2.10 Private Handler Methods

@RequestMapping(value = "/api/params", params = "id")
private String params(Long id) {
  return "params id =" + id;
}

Controller methods can be private, but this may affect AOP‑based enhancements such as logging.