SpringBoot 接口传参：RequestParam、RequestBody、PathVariable 怎么选

SpringBoot 接口传参：RequestParam、RequestBody、PathVariable 怎么选

目录

• 一、@RequestParam：从 URL 查询参数中取值
• 二、@PathVariable：从 URL 路径中取值
• 三、@RequestBody：从请求体中取值
• 三种注解对比
• 什么时候用哪个：按 HTTP 语义来选
• 使用时注意事项
• 小结

我们在学习后端开发的时候，都在相应教学内容上看到过这三个注解。教程里直接给使用方式，但却没有详细说什么时候该用哪个。等到真正写项目接口的时候，就会开始纠结：分页参数用@RequestParam，那查详情的 ID 放在路径里用@PathVariable还是也用@RequestParam？提交表单十几个字段，是全用@RequestParam一个个接，还是塞进一个对象用@RequestBody？

三种注解都能拿到前端传来的数据，但它们的数据来源、适用场景、HTTP 语义完全不同。搞混了代码能跑，但接口设计会很别扭。我们一个一个来看一下使用场景。

一、@RequestParam：从 URL 查询参数中取值

@RequestParam对应的是 URL 中?后面的查询参数（Query String）。

@GetMapping("/users")publicList<User>listUsers(@RequestParam(defaultValue="1")intpage,@RequestParam(defaultValue="10")intsize){returnuserService.listUsers(page,size);}

前端请求：GET /users?page=1&size=10

Spring 看到@RequestParam，就知道去 URL 的查询参数里找page和size这两个 key，取出来转成int，注入到方法参数里。defaultValue是个保底：如果前端没传这个参数，就用默认值，不会报错。

适用场景

筛选、排序、分页这种可选的查询条件。用@RequestParam最合适。参数是 URL 的一部分，浏览器地址栏能直接看到，方便调试和分享链接。

@GetMapping("/products")publicList<Product>search(@RequestParam(required=false)Stringkeyword,@RequestParam(required=false)Stringcategory,@RequestParam(defaultValue="price")StringsortBy){returnproductService.search(keyword,category,sortBy);}

请求：GET /products?keyword=手机&category=electronics&sortBy=price

注意required = false：这个参数是可选的，不传也不会报 400。如果你确定某个参数必须传（比如分页的页码），可以用required = true（默认值），前端不传就直接返回 400 错误。

多个值的情况

一个参数还能接收多个值，前端用同一个 key 传多次：

@GetMapping("/users/batch")publicList<User>getByIds(@RequestParamList<Long>ids){returnuserService.getByIds(ids);}

请求：GET /users/batch?ids=1,2,3或GET /users/batch?ids=1&ids=2&ids=3

Spring 会自动把多个值收集到List里。

二、@PathVariable：从 URL 路径中取值

@PathVariable对应的是 URL 路径中用{xxx}占位的部分。

@GetMapping("/users/{id}")publicUsergetUser(@PathVariableLongid){returnuserService.getUserById(id);}

前端请求：GET /users/42

{id}是一个路径变量，@PathVariable告诉 Spring：去 URL 路径里把{id}位置的值取出来，转成Long，赋给id参数。

适用场景

标识具体资源的场景。RESTful 风格的 API 设计中，用路径来表达"操作的是哪个资源"。

GET /users/42 → 查看用户 42 PUT /users/42 → 更新用户 42 DELETE /users/42 → 删除用户 42 GET /orders/1001/items → 查看订单 1001 的商品列表

路径中的42、1001就是资源标识，用@PathVariable接收。这种设计比GET /users?id=42更符合 REST 语义，URL 也更简洁直观。

多个路径变量

一个 URL 里可以有多个占位符：

@GetMapping("/departments/{deptId}/employees/{empId}")publicEmployeegetEmployee(@PathVariableLongdeptId,@PathVariableLongempId){returnemployeeService.get(deptId,empId);}

请求：GET /departments/5/employees/128

两个占位符对应两个@PathVariable，Spring 会按名称匹配。

三、@RequestBody：从请求体中取值

@RequestBody对应的是 HTTP 请求的 Body 部分。当前端发送 JSON 格式的数据时，Spring 会用HttpMessageConverter（默认是 Jackson）把 JSON 反序列化成 Java 对象。

@PostMapping("/users")publicUsercreateUser(@RequestBodyUserCreateRequestrequest){returnuserService.createUser(request);}

// 请求体对应的 DTOpublicclassUserCreateRequest{privateStringname;privateStringemail;privateIntegerage;// getter/setter}

前端请求：

POST /users Content-Type: application/json { "name": "张三", "email": "zhangsan@example.com", "age": 25 }

Spring 看到@RequestBody，就知道把整个请求体读出来，用 Jackson 解析成UserCreateRequest对象。字段名要和 JSON 的 key 对应，类型要能转换，否则直接报 400。

适用场景

提交复杂表单数据、创建或更新资源。当参数多、结构复杂、或者包含嵌套对象时，@RequestBody是最佳选择。

// 嵌套对象的场景publicclassOrderCreateRequest{privateLonguserId;privateList<OrderItem>items;privateAddressshippingAddress;privateStringpaymentMethod;}publicclassOrderItem{privateLongproductId;privateIntegerquantity;}publicclassAddress{privateStringprovince;privateStringcity;privateStringdetail;}

这种嵌套结构，用@RequestParam一个个接几乎不可能，用@RequestBody一行搞定。

三种注解对比

一句话总结：@RequestParam管查询条件，@PathVariable管资源标识，@RequestBody管请求体。

什么时候用哪个：按 HTTP 语义来选

与其记住注解的语法，不如理解 HTTP 本身的语义。每个 HTTP 方法有它自己的含义，参数怎么传跟着语义走就行了。

GET 请求：筛选和查询

GET 用来获取资源。参数通常是可选的筛选条件，放在 URL 查询参数里：

@GetMapping("/articles")publicList<Article>search(@RequestParam(required=false)Stringkeyword,@RequestParam(defaultValue="1")intpage,@RequestParam(defaultValue="20")intsize){returnarticleService.search(keyword,page,size);}

如果要查某个具体资源，用路径标识：

@GetMapping("/articles/{id}")publicArticlegetDetail(@PathVariableLongid){returnarticleService.getById(id);}

GET 请求没有请求体，所以@RequestBody在 GET 中没有意义。虽然 HTTP 规范没有明确禁止 GET 带 Body，但大多数 HTTP 客户端和代理服务器会忽略 GET 的 Body，Spring 默认也不支持。如果你发现自己想在 GET 里用@RequestBody，大概率是接口设计有问题，应该改成 POST。

POST 请求：创建资源

POST 用来提交数据、创建资源。数据通常比较复杂，放在请求体里：

@PostMapping("/articles")publicArticlecreate(@RequestBody@ValidArticleCreateRequestrequest){returnarticleService.create(request);}

PUT 请求：更新资源

PUT 用来更新资源。被更新的资源用路径标识，更新的内容放请求体：

@PutMapping("/articles/{id}")publicArticleupdate(@PathVariableLongid,@RequestBodyArticleUpdateRequestrequest){returnarticleService.update(id,request);}

这里@PathVariable和@RequestBody同时出现——一个管"更新谁"，一个管"更新成什么"，职责非常清晰。

DELETE 请求：删除资源

DELETE 用来删除资源，被删除的对象用路径标识：

@DeleteMapping("/articles/{id}")publicvoiddelete(@PathVariableLongid){articleService.delete(id);}

把上面的规律总结成一张表：

使用时注意事项

@RequestBody 不能和 @RequestParam 混用在同一参数上

有些新手会写出这种代码：

// 错误写法@PostMapping("/users")publicUsercreate(@RequestBody@RequestParamUserDTOdto){...}

这两个注解的数据来源是矛盾的：@RequestBody从请求体取，@RequestParam从查询参数取。一个参数不可能同时从两个地方取值。Spring 会直接报错。

正确的做法是分清楚：哪些参数从查询参数来，哪些从请求体来：

@PostMapping("/users")publicUsercreate(@RequestParam(defaultValue="false")Booleannotify,// 查询参数@RequestBodyUserDTOdto){// 请求体returnuserService.create(dto,notify);}

@PathVariable 的变量名要和路径占位符一致

// 如果占位符叫 {userId}，参数名也得叫 userId@GetMapping("/users/{userId}")publicUsergetUser(@PathVariableLonguserId){...}

@RequestBody 的校验

@RequestBody接收的对象通常需要校验。配合@Valid注解和 JSR-303 校验注解一起用：

publicclassUserCreateRequest{@NotBlank(message="用户名不能为空")privateStringname;@Email(message="邮箱格式不正确")privateStringemail;@Min(value=0,message="年龄不能为负数")privateIntegerage;}@PostMapping("/users")publicUsercreate(@RequestBody@ValidUserCreateRequestrequest){returnuserService.create(request);}

不加@Valid，校验注解不会生效，前端传什么数据都能进来。

接收数组或列表

@RequestBody可以直接接收 JSON 数组：

@PostMapping("/users/batch")publicList<User>batchCreate(@RequestBodyList<UserCreateRequest>requests){returnuserService.batchCreate(requests);}

前端传一个 JSON 数组就行：

[{"name":"张三","email":"zhangsan@example.com"},{"name":"李四","email":"lisi@example.com"}]

小结

三种注解的本质区别在于数据来源不同：@RequestParam从 URL 查询参数取，@PathVariable从 URL 路径取，@RequestBody从请求体取。不用死记语法，只需要跟着 HTTP 语义走：GET 查询用@RequestParam，资源标识用@PathVariable，复杂数据提交用@RequestBody。