REST API，何时使用 @PathParam、@QueryParam、@RequestBody 和/或 @RequestHeader

Question

如果在何时/何时不使用上述将信息传递给 REST 调用的方法方面存在某种标准，我一直在努力寻找答案。

我一直在到处寻找，但每篇文章都只讨论列出的方法中的 2 种或 3 种方法之间的区别，而不是全部 4 种方法。

Answer 1

1.@PathParam

PathParam 通常用于使用id获取资源。 例如。 /employees/{emp_id}

如果您没有通过id为path param找到资源，通常它是 HTTP 响应代码 404。

2.@QueryParam

QueryParam通常用于使用除 id 以外的任何其他字段访问实体。 考虑“搜索”或“过滤器”而不是使用“id”来访问实体。 在这种情况下，您将不得不期望一个实体数组作为响应，这与您将作为将id作为pathParam发送的响应所获得的单个实体不同

例如。 /employees?firstname=joe

注意： QueryParam也可以用于其他操作，例如sort 。 例如。 /departments/123/employees?sort_by=salary

如果您没有通过搜索参数或过滤参数找到任何实体，通常它是一个 http 响应代码 200，以一个空数组作为响应主体。

3.@RequestBody

通常它是一个 POST、PUT 或 PATCH http 动词，我们将使用它来发送请求正文。

为什么用 http GET 发送 requestbody 是个坏主意

为什么用 http DELETE 发送 requestbody 是个坏主意

以下是我们使用RequestBody的情况

A. 状态突变

为了实现状态突变，通常实体所需状态的 json/xml 表示将作为带有 POST/PUT/PATCH 动词的requestBody发送。 Rest 原则没有说 json 或 xml，它可以是任何东西； 它可以是压缩的二进制格式，例如 protobuf、avro、cap'n'proto、flatbuffers 等，甚至是纯文本。

B. READ 操作（这些是 READ 不等同于 HTTP GET 的示例）

• a. 避免 Loooong Urls - 如果 GET 实体所需的参数太长，我们通常会使用请求正文来发送它，而不是使用 url。 Http 协议或 Rest 原则不会限制您的 url 大小，但是某些浏览器对 url 的最大长度有限制。

  URL 在不同浏览器中的最大长度是多少？

  湾 graphql - 在这里，您将使用 requestbody 发布查询以获取所需格式的数据

  C. 安全原因- 如果您必须发送密码/令牌等机密数据来获取某些数据，通常您必须将其发布在请求正文或标头中。 （为什么？因为，如果它在 url 中，很有可能它最终会出现在应用程序日志中）

4.@RequestHeader

一般用于发送元数据； 不是实际的实体主体（数据）。 例如。 request-correlation-id、authheader、安全令牌等

5.@Matrixparam、@CookieParam 等

JAX-RS 规范中还有其他不太流行的 HTTP 动词，如@Matrixparam和 @CookieParam。 这是Jersey 文档（请记住 Jersey 是 JAX-RS 的参考实现。您可能在 Spring 中找不到等效的东西）

其他有趣和相关的阅读

何时使用 @QueryParam 与 @PathParam

@PathParam 和 @QueryParam 有什么区别

带有 URL 查询参数的 HTTP POST——好主意与否？

如何使用 cURL POST JSON 数据？