Spring Boot 接口设计：@RequestBody 与 @RequestParam 的核心区别与选用原则

在 Spring Boot 项目中进行接口开发时，如何选择 @RequestBody 和 @RequestParam 来接收参数？这不仅仅是语法选择，更关乎接口的设计原则。如果选错了，接口虽然能用，但随着业务迭代，会变得越来越别扭，维护成本也随之增高。

一、@RequestParam：适用于简单查询的参数

让我们先看一个典型的使用 @RequestParam 的例子：

@GetMapping("/user/list")
public List<User> list(
        @RequestParam Integer page,
        @RequestParam Integer size) {
    ...
}

这个注解的语义非常明确：

• 参数是“零散的”：每个参数独立存在于URL中。
• 参数数量较少：通常用于传递少量信息。
• 主要用于查询操作：特别是配合 GET 请求。

典型适用场景包括：

• 分页参数（如 page, size）
• 简单的筛选条件（如 name=xxx&status=1）
• 标准的 GET 请求

然而，一旦出现以下情况，就应该考虑放弃使用 @RequestParam：

• 参数数量超过 3 个，使得接口签名冗长。
• 参数之间存在明显的“结构关系”（例如，都属于一个用户信息）。
• 参数本身可以很自然地抽象成一个独立的对象。

二、@RequestBody：用于接收结构化业务对象

当参数是一个有明确业务含义的整体时，@RequestBody 是更合适的选择。

@PostMapping("/user/save")
public void save(@RequestBody UserDTO dto) {
    ...
}

@RequestBody 非常适合以下情况：

• 参数本身是一个逻辑整体：比如创建或更新一个用户、订单。
• 有明确的业务含义：参数直接对应业务模型。
• 需要进行集中校验或未来扩展。

它带来的工程优势非常直接：

• 参数可复用：同一个 DTO 对象可以在多个接口中使用。
• 校验集中：可以方便地使用 @Valid 注解进行统一校验。
• 接口签名稳定：新增字段只需修改 DTO 类，无需改变接口方法签名。

public class UserDTO {
    @NotBlank
    private String name;
    // 未来新增字段，如 email, address， 只需在此添加
}

一旦将参数抽象成对象，接口的演进成本就会显著下降，这是面向对象设计和 Java 开发中非常重要的一个实践。

三、最容易出错的几种场景

在实际开发中，以下几种错误用法颇为常见。

1. 用 @RequestParam 硬凑一个对象

public void save(
    @RequestParam String name,
    @RequestParam Integer age,
    @RequestParam String phone) {
}

这里核心问题在于：这明明是一个对象（用户信息），却被强行拆解成了多个零散参数。后期每增加一个字段（比如 email），接口的方法签名就必须跟着修改，违反了开闭原则，维护性很差。

2. 在 GET 请求中使用 @RequestBody

GET 请求搭配 @RequestBody，从技术上讲，部分框架或客户端可能支持，但很多 HTTP 客户端和规范根本不推荐或支持这种做法。一个简单的规则可以避免困惑：

• GET 请求：使用 @RequestParam（参数附在URL后）。
• POST / PUT / PATCH 请求：使用 @RequestBody（参数在请求体中）。

3. 两者混用但语义不清晰

public void save(
    @RequestParam Long id,
    @RequestBody UserDTO dto) {
}

这种写法本身并没有错，但它必须语义清晰：

• id：通常用于资源的定位或标识（如更新哪个用户）。
• dto：承载业务数据的对象（如用户的新信息）。

如果混用但没有明确的区分逻辑，就是在无形中增加其他开发者的阅读和理解成本，影响 后端开发 的协作效率。

小结

总结一下 @RequestBody 和 @RequestParam 的选用原则：

• 简单查询与筛选：使用 @RequestParam。
• 接收业务对象（创建、更新等）：使用 @RequestBody。
• 重要原则：参数如果能自然地组织成一个对象，就不要拆成多个零散参数。
• HTTP方法约定：避免在 GET 请求中使用 @RequestBody。

一句话总结核心思想：@RequestParam 通常表示“查询条件”，而 @RequestBody 则表示“业务数据体”。理解并遵循这一语义区别，能帮助你设计出更清晰、更稳定、更易维护的 RESTful API。

希望这篇解析能帮助你厘清这两个常用注解的区别。如果你想深入探讨更多关于 Spring Boot 或系统设计的话题，欢迎来 云栈社区 与其他开发者交流。