请求参数、路径参数、查询参数、Spring MVC/FeignClient请求相关注解梳理

news2025/4/28 16:24:40

- - 1 请求分类
  - - 1.1 URL参数--查询参数
    - 1.2 URL参数--路径参数
  - 2 请求相关注解
  - - 2.1 @RequestParam--查询参数
    - 2.2 @PathVariable--路径参数
    - 2.3 @RequestBody
    - 2.4 @Param & @RequestLine
    - 2.5 SpringMVC请求参数注解用在FeignClient里

使用SpringMVC处理http请求或使用FeignClient进行请求时，会使用到许多请求相关注解，现梳理一下以免混乱。

1 请求分类

在进行HTTP请求时，会看到“请求参数”、“查询参数”、“路径参数”相关字眼，那么它们之间的关系是什么呢？——请求参数是更加宽泛的概念，它包括查询参数和路径参数，它是指在请求中传递给服务器的数据，可以是URL携带的参数，也可以是请求体，请求数据类型可以是路径参数（rest风格）、查询字符串、JSON数据等，适用于GET/POST/PUT/DELETE方法。

而查询参数和路径参数特指请求URL携带的参数。

1.1 URL参数–查询参数

查询参数一般特指使用GET请求、以URL传递的查询字符串参数，它附加在URL里，参数位于URL的 “?” 之后，由一个或多个以 & 符号分隔的键值对组成。如：

https://example.com/api/users?age=30&sort=name

这个URL传递两个参数age和sort，值分别是30和name。

1.2 URL参数–路径参数

路径参数常用在RESTful API风格中，它是URL路径的一部分，一个形式化的路径参数格式如下，路径参数通常在大括号表示的地方：

https://example.com/api/users/{userId}
https://example.com/api/categories/{categoryId}/products

‘{}’部分在请求时需要填入真实的值，比如：

https://example.com/api/users/1
https://example.com/api/categories/2024/products

2 请求相关注解

请求相关注解有不少，下面逐个介绍一下。

2.1 @RequestParam–查询参数

在后端使用@RequestParam来获取查询参数，对于如下请求路径：

/api/users?sex=1&age1=30&sort=name

响应方式为：

@GetMapping("/api/users")
public List<User> getUsers(@RequestParam（required = false） int sex,
							@RequestParam(name= "age1", required = false) Integer age,
                            @RequestParam("sort") String sort) {
    
}

以上三种@RequestParam的写法都可以，required 字段默认为true：

sex: 当没有给定任何注解属性时，会默认将URL请求参数名和响应参数名称进行映射，比如将请求参数sex映射到后端参数sex（参数名必须一致）。需要注意的是虽然参数为非必须，但用的是简单类型进行接收，如果前端未传sex字段则会报错，因为不能使用null赋值给简单类型。解决方式是可以使用defaultValue属性设置默认值或者使用包装类型Integer进行接收【defaultValue和required = false 搭配使用】。当没有显示设置required且前端未传值时，也会尝试赋空值。
age: 显示使用两个属性，name规定将查询参数“age1”映射至后端参数“age”。
sort：比较常用的写法。

2.2 @PathVariable–路径参数

在后端使用@PathVariable来获取路径参数，对于如下请求路径：

/api/users/1

响应方式为：

@GetMapping("/api/users/{userId}")
public User getUserById(@PathVariable String userId) {}

注意路径变量是URL的一部分，必须提供，因此@PathVariable没有required属性。

2.3 @RequestBody

用于将前端的请求体携带的JSON数据绑定到Java对象中。

@PostMapping("/api/users")
    public String createUser(@RequestBody User user) {}

2.4 @Param & @RequestLine

FeignClient提供的注解，在使用Feign客户端的时候，这两个注解常常搭配使用。

@Param用于将方法参数绑定到请求的URL路径参数、查询参数或请求体中，像反向的@RequestParam。

@RequestLine在FeignClient里面定义HTTP请求的方法和路径。

@FeignClient(name = "user-service", url = "http://localhost:8080")
public interface UserClient {
    // 使用 @RequestLine 定义HTTP请求方法和路径
    @RequestLine("GET /users/{id}")
    User getUserById(@Param("id") Long id);
}

在使用feignclient的时候，如果@RequestLine及@RequestMapping(method = RequestMethod.xxx)(或@PostMapping/@GetMapping)同时出现，会优先使用@RequestLine。因为@RequestLine属于Feign原生注解，而@RequestMapping属于Spring MVC注解，因此Feign在处理请求时会优先选择属于自己的注解规则。

2.5 SpringMVC请求参数注解用在FeignClient里

@RequestParam、@PathVariable、@RequestBody都属于SpringMVC框架提供的注解，通常用于从请求里解析参数到后端方法参数，而当这些注解用在FeignClient里时，可以实现方法参数到请求的逆向绑定。

@FeignClient(name = "user-service", url = "http://localhost:8080")
public interface UserClient {
    // 1. @RequestParam：绑定查询参数，将方法参数 name 绑定到查询参数 name 上
    @GetMapping("/users/search")
    User searchUser(@RequestParam("name") String name);
    
     // 2. @PathVariable：绑定路径变量，把方法参数 id 绑定到路径变量 {id} 上
    @GetMapping("/users/{id}")
    User getUserById(@PathVariable("id") Long id);

	// 3. 绑定请求体，把方法参数 user 绑定到请求体上
    @PostMapping("/users")
    User createUser(@RequestBody User user);

    
}