REST API：何时使用查询参数、路径参数或请求体传参？

1. 路径参数（Path Parameters） #

用来精准定位特定资源，是资源URI的核心组成部分，本质是告诉API“我要操作的是哪一个具体资源”。

• 适用场景：
  • 访问单个唯一资源：比如获取某用户详情、某篇帖子内容
  • 层级资源定位：比如某篇帖子下的所有评论、某个用户发布的所有动态
• 示例：
  GET /users/123（获取ID为123的用户信息）
  GET /posts/456/comments（获取ID为456的帖子下的所有评论）
• 注意点：路径参数一般是必填的，值通常是短格式的标识（如ID、枚举值），不适合传递大量或可变的内容。

2. 查询参数（Query Parameters） #

用来对资源集合进行过滤、排序、分页，或者调整返回内容的格式，属于附加的可选条件，不影响资源的核心定位。

• 适用场景：
  • 过滤资源集合：比如获取带“科技”标签的帖子、近7天发布的评论
  • 分页查询：控制每页数量和页码
  • 排序：按创建时间、热度等字段排序
  • 自定义返回字段：只返回资源的部分字段，减少数据传输量
• 示例：
  GET /posts?tag=tech&page=2&size=10（获取第2页、每页10条的科技类帖子）
  GET /comments?sort=createdAt,desc（按创建时间倒序返回评论）
• 注意点：查询参数是可选的，数据量不宜过大（受URI长度限制），通常用于GET请求的附加条件。

3. 请求体（Request Body） #

用来传递需要创建或修改的资源数据，适合处理复杂、结构化、较大体量的内容，主要用于POST、PUT、PATCH这类会改变资源状态的请求。

• 适用场景：
  • 创建新资源：比如发布帖子、添加评论、注册用户
  • 更新资源内容：比如修改用户昵称、编辑帖子正文
  • 传递多字段结构化数据：比如包含文本、图片链接、隐私设置的表单数据
• 示例：
  POST /posts/456/comments
  请求体内容：

  {
    "content": "这个观点很有意思！",
    "parentCommentId": 789,
    "isAnonymous": false
  }
  

• 注意点：GET请求不建议使用请求体（不符合REST最佳实践，部分服务器/工具不支持），适合传递可变的、非标识性的核心数据。

针对你提到的“添加评论”场景 #

把评论内容放入请求体是最优选择。因为评论是你要创建的新资源，内容是资源的核心数据，还可能附带父评论ID、匿名设置等额外字段，用请求体可以灵活传递这些结构化信息，完全符合REST创建资源的规范。

选择优先级总结 #

1. 要定位特定资源 → 用路径参数
2. 要过滤/调整资源集合的返回结果 → 用查询参数
3. 要创建/修改资源，或传递大量复杂数据 → 用请求体

内容的提问来源于stack exchange，提问作者Bianca