Spring 中的 @RequestParam 注解

1、概览

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

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

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

接下来,看看注解的属性:namevaluerequireddefaultValue

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、可选的请求参数

使用 @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

或者,也可以用 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、请求参数的默认值

还可以使用 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、映射所有参数

还可以使用 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、多值参数(列表/数组)

一个 @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、总结

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


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