1、概览 {#1概览}

本文将带你了解 Spring 中 @RequestParam 注解的用法。

简单地说，可以使用 @RequestParam 从请求中提取查询参数、表单参数甚至是多个参数。

2、示例端点 {#2示例端点}

假设我们有一个端点 /api/foos，它接受一个名为 id 的查询参数：

@GetMapping("/api/foos")
@ResponseBody
public String getFoos(@RequestParam String id) {
    return "ID: " + id;
}

在本例中，使用 @RequestParam 来提取 id 查询参数。

通过 GET 请求来调用 getFoos：

http://localhost:8080/spring-mvc-basics/api/foos?id=abc
----
ID: abc

接下来，看看注解的属性：name、value、required 和 defaultValue。

3、指定请求参数名称 {#3指定请求参数名称}

在上一个示例中，变量名和参数名都是相同的。

如果变量名称和参数名称不同，可以使用 name 属性配置 @RequestParam 名称：

@PostMapping("/api/foos")
@ResponseBody
public String addFoo(@RequestParam(name = "id") String fooId, @RequestParam String name) { 
    return "ID: " + fooId + " Name: " + name;
}

也可以使用 @RequestParam(value = "id") 或直接使用 @RequestParam("id")。

4、可选的请求参数 {#4可选的请求参数}

使用 @RequestParam 注解的方法参数默认为必填参数。

这意味着，如果请求中没有该参数，就会返回 400 错误：

GET /api/foos HTTP/1.1
-----
400 Bad Request
Required String parameter 'id' is not present

可以使用 required 属性将 @RequestParam 配置为可选参数：

@GetMapping("/api/foos")
@ResponseBody
public String getFoos(@RequestParam(required = false) String id) { 
    return "ID: " + id;
}

在这种情况下，下面两个调用都是正常的：

http://localhost:8080/spring-mvc-basics/api/foos?id=abc
----
ID: abc

http://localhost:8080/spring-mvc-basics/api/foos
----
ID: null

如果没有指定参数，方法参数将绑定为 null。

4.1、使用 Java 8 Optional {#41使用-java-8-optional}

或者，也可以用 Optional 对象来封装参数：

@GetMapping("/api/foos")
@ResponseBody
public String getFoos(@RequestParam Optional<String> id){
    return "ID: " + id.orElseGet(() -> "not provided");
}

在这种情况下，不需要指定 required 属性。

如果没有提供请求参数，则使用默认值：

http://localhost:8080/spring-mvc-basics/api/foos 
---- 
ID: not provided

5、请求参数的默认值 {#5请求参数的默认值}

还可以使用 defaultValue 属性为 @RequestParam 设置默认值：

@GetMapping("/api/foos")
@ResponseBody
public String getFoos(@RequestParam(defaultValue = "test") String id) {
    return "ID: " + id;
}

与 required=false 类似，用户不再需要提供参数：

http://localhost:8080/spring-mvc-basics/api/foos
----
ID: test

不过，也可以主动提供：

http://localhost:8080/spring-mvc-basics/api/foos?id=abc
----
ID: abc

注意，当设置 defaultValue 属性时，required 会被被设置为 false。

6、映射所有参数 {#6映射所有参数}

还可以使用 Map 来封装多个参数，而无需定义它们的名称（name）或数量：

@PostMapping("/api/foos")
@ResponseBody
public String updateFoos(@RequestParam Map<String,String> allParams) {
    return "Parameters are " + allParams.entrySet();
}

上述示例会把所有请求参数返回给客户端：

curl -X POST -F 'name=abc' -F 'id=123' http://localhost:8080/spring-mvc-basics/api/foos
-----
Parameters are {[name=abc], [id=123]}

7、多值参数（列表/数组） {#7多值参数列表数组}

一个 @RequestParam 可以有多个值：

@GetMapping("/api/foos")
@ResponseBody
public String getFoos(@RequestParam List<String> id) {
    return "IDs are " + id;
}

Spring MVC 会映射以逗号分割的参数：

http://localhost:8080/spring-mvc-basics/api/foos?id=1,2,3
----
IDs are [1,2,3]

或参数列表：

http://localhost:8080/spring-mvc-basics/api/foos?id=1&id=2
----
IDs are [1,2]

关于 Spring Boot 如何接受数组、集合类型的参数你可以参阅 这篇文章。

8、总结 {#8总结}

本文介绍了在 Spring 应用中如何使用 @RequestParam 注解来接收客户端参数。还介绍了如何处理参数的名称、使用默认参数、定义可选参数、接收多个参数等等。

Ref：https://www.baeldung.com/spring-request-param