SpringBoot接口参数接收指南：从URL到请求体，4种方式一次掌握

前言

前后端分离已经成了主流开发模式，前端怎么向后端传递参数？这几乎是每个 Spring Boot 开发者都绕不开的基础技能。下面这张图先帮你快速建立起整体印象：

今天这篇文章，就把 Spring 中最常见的四种参数接收方式掰开揉碎讲清楚，配合简单示例，帮你搞清楚它们各自的使用场景和差异。

1. Request 简介

在正式介绍注解之前，先快速了解一下 HTTP 请求的数据结构。一个典型的 HTTP 请求由三部分组成：

• 请求行：包括 URL 路径、方法（GET、POST）等；
• 请求头（Headers）：携带客户端信息、Token 等；
• 请求体（Body）：通常用于 POST/PUT 请求，存放结构化数据（如 JSON）。

四种注解的本质，就是从这些不同部分中把参数提取出来。

2. 四种方式速览

Spring Boot 接收前端数据，常用的方式有哪几种？下面这四种就是最常见的：

• @PathVariable：用于接收 URL 路径中的参数；
• @RequestParam：用于接收查询参数或表单数据；
• @RequestHeader：用于接收请求头中的信息；
• @RequestBody：用于接收 JSON 或 XML 格式的请求体数据。

后文会依次展开，说清楚每个注解怎么用、什么时候用。

3. @PathVariable 注解

用于接收 URL 路径中的变量，比如 /user/{id}。这在 RESTful 风格的接口里非常常见。

示例：

@GetMapping("/user/{id}")
public String getUser(@PathVariable Long id) {
    return "User ID: " + id;
}

想从路径里拿用户ID？直接写个 {id} 占位，再用 @PathVariable 绑定参数，干净利落。

4. @RequestHeader 注解

用于接收请求头里的参数，最典型的场景就是读取 Token、User-Agent 这类信息。

示例：

@GetMapping("/device")
public String getDevice(@RequestHeader("User-Agent") String userAgent) {
    return "User-Agent: " + userAgent;
}

如果你需要根据客户端类型做差异化处理，直接从请求头里拿 User-Agent 就行。

5. @RequestParam 注解

用于接收 URL 中的查询参数，或者表单提交的数据。GET 请求的查询参数拼接在 URL 后面，POST 请求如果 Content-Type 是 application/x-www-form-urlencoded，表单数据也会以键值对形式编码放在请求体里。这两种情况，@RequestParam 都能搞定。

示例：

@GetMapping("/search")
public String search(@RequestParam String keyword) {
    return "Searching: " + keyword;
}

比如搜索接口，参数直接拼在 URL 上，用 @RequestParam 接收，简单粗暴。

6. @RequestBody 注解

用于接收请求体中的 JSON 或 XML 数据，通常配合 POST/PUT 请求和实体类一起使用。

示例：

@PostMapping("/login")
public String login(@RequestBody User user) {
    return "Welcome " + user.getUsername();
}

注意：GET 请求没有请求体，不能使用 @RequestBody。只有 Content-Type 为 application/json 的 POST/PUT 请求，才适合用它来接收 JSON 数据。而且一个方法中只能有一个 @RequestBody 注解，通常用 Ja va Bean、DTO 或 Map 来接收整体结构化数据。

7. 总结

回顾一下，Spring Boot 接收前端参数的四种常用注解，选用哪种完全取决于你的业务场景和前端的请求结构：

• URL 参数：@PathVariable
• 查询参数 / 表单数据：@RequestParam
• 请求头信息：@RequestHeader
• JSON 请求体：@RequestBody

把这些基础注解吃透，开发 Web 接口时就能更得心应手，API 也会更清晰、更规范。