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

Question

我一直在试图寻找答案，是否存在某种关于何时/何时不使用上述将信息传递给 REST 调用的方法的标准。

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

Answer 1

<强>1。 @PathParam

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

如果您没有通过 id 作为路径参数找到资源，通常会出现 HTTP 响应代码 404。

<强>2。 @QueryParam

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

发送 id 的响应所获得的单个实体不同。

例如。 /employees?firstname=joe

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

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

<强>3。 @RequestBody

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

Why it's a bad idea to send requestbody with http GET

Why it's a bad idea to send requestbody with http DELETE

以下是我们使用RequestBody的情况

A.状态突变

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

B. READ 操作(这些示例中 READ 不等于 HTTP GET)

• a。 避免冗长的 URL - 如果 GET 所需的参数实体太长，我们通常会使用请求正文来发送它，而不是使用网址。 Http协议(protocol)或Rest原则不限制您可以设置网址大小，但是某些浏览器对最大长度有限制网址。

  What is the maximum length of a URL in different browsers?

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

  c. 安全原因 - 如果您必须发送 secret 数据，例如密码/ token 来获取一些数据，通常你必须发布它在请求正文或 header 中。 (为什么？因为，如果它在 url 中，它很可能最终出现在应用程序日志中)

<强>4。 @RequestHeader

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

<强>5。 @Matrixparam、@CookieParam 等

还有其他不太流行的 HTTP 动词，例如 @Matrixparam和 @CookieParam 都在 JAX-RS 规范中。这是Jersey documentation (请记住，Jersey 是 JAX-RS 的引用实现。您可能在 Spring 中找不到等效的东西)

其他有趣且相关的读物

When to use @QueryParam vs @PathParam

What is the difference between @PathParam and @QueryParam

HTTP POST with URL query parameters -- good idea or not?

How do I POST JSON data with cURL?