RFC 10008: HTTP QUERY 方法

# RFC 10008：HTTP QUERY 方法 | RFC 编辑器 来源：https://www.rfc-editor.org/info/rfc10008/ ## 摘要 (https://www.rfc-editor.org/info/rfc10008/#abstract) 本规范定义了 HTTP 的 QUERY 方法。QUERY 请求要求请求目标以安全和幂等的方式处理所包含的内容，并返回该处理的结果。这类似于 POST 请求，但 QUERY 请求可以自动重复或重新启动，而无需担心部分状态变化。¶ (https://www.rfc-editor.org/info/rfc10008/#section-abstract-1) ## 本备忘录的状态 (https://www.rfc-editor.org/info/rfc10008/#name-status-of-this-memo) 这是一份互联网标准跟踪文档。¶ (https://www.rfc-editor.org/info/rfc10008/#section-boilerplate.1-1) 本文档是互联网工程任务组（IETF）的产品。它代表了 IETF 社区的共识。它已接受公开审查，并经互联网工程指导组（IESG）批准发布。有关互联网标准的更多信息，请参阅 RFC 7841 的第 2 节。¶ (https://www.rfc-editor.org/info/rfc10008/#section-boilerplate.1-2) 关于本文档的当前状态、任何勘误以及如何提供反馈的信息，可在以下网址获取：https://www.rfc-editor.org/info/rfc10008。¶ (https://www.rfc-editor.org/info/rfc10008/#section-boilerplate.1-3) ## 版权声明 (https://www.rfc-editor.org/info/rfc10008/#name-copyright-notice) 版权所有 (c) 2026 IETF 信托基金及被认定为文档作者的个人。保留所有权利。¶ (https://www.rfc-editor.org/info/rfc10008/#section-boilerplate.2-1) 本文档受 BCP 78 及本文档发布之日有效的 IETF 信托基金与 IETF 文档相关的法律条款（https://trustee.ietf.org/license-info）的约束。请仔细阅读这些文档，因为它们描述了您对本文档的权利和限制。从本文档中提取的代码组件必须包含修订后的 BSD 许可文本，如信托法律条款第 4.e 节所述，并且按修订后的 BSD 许可提供，不提供任何担保。¶ (https://www.rfc-editor.org/info/rfc10008/#section-boilerplate.2-2) ## 1. (https://www.rfc-editor.org/info/rfc10008/#section-1) 引言 (https://www.rfc-editor.org/info/rfc10008/#name-introduction) 本规范定义了 HTTP QUERY 请求方法，作为发起一个安全、幂等的请求（参见 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 的第 9.2 节 (https://rfc-editor.org/rfc/rfc9110#section-9.2)）的手段，该请求包含一个表示，描述目标资源应如何处理该请求。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-1) 一种常见的查询模式是：¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-2) 然而，当要传递的数据过于庞大而无法编码到请求的 URI 中时，这种模式就变得有问题：¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-4) 作为使用 GET 的替代方案，许多实现使用 HTTP POST 方法来执行查询，如下例所示。在这种情况下，查询操作的输入作为请求内容传递，而不是使用请求 URI 的查询组件。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-6) 使用 HTTP POST 请求查询的典型用法是：¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-7) 然而，在这种变体中，如果不具体了解请求所发送到的资源和服务器，就不容易明显看出正在执行一个安全、幂等的查询。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-9) QUERY 方法提供了弥合 GET 和 POST 使用之间差距的解决方案，上面的示例可以表示为：¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-10) 与 POST 一样，查询操作的输入作为请求的内容传递，而不是作为请求 URI 的一部分。然而，与 POST 不同的是，该方法明确是安全且幂等的，允许缓存和自动重试等功能正常运行。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-12) 认识到任何重要资源都应由 URI 标识的设计原则，本规范描述了服务器如何为查询本身或特定的查询结果分配 URI，以便稍后在 GET 请求中使用。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-13) 总结：¶ (https://www.rfc-editor.org/info/rfc10008/#section-1-14) ### 1.1. (https://www.rfc-editor.org/info/rfc10008/#section-1.1) 术语 (https://www.rfc-editor.org/info/rfc10008/#name-terminology) 本文档使用 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 3 节 (https://rfc-editor.org/rfc/rfc9110#section-3) 中定义的术语。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1.1-1) 此外，它使用术语 *URI 查询参数* 指代 URI 查询组件中的参数（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 4.2.2 节 (https://rfc-editor.org/rfc/rfc9110#section-4.2.2)），使用术语 *查询内容* 指代 QUERY 请求的请求内容（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 6.4 节 (https://rfc-editor.org/rfc/rfc9110#section-6.4)）。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1.1-2) ### 1.2. (https://www.rfc-editor.org/info/rfc10008/#section-1.2) 表示法约定 (https://www.rfc-editor.org/info/rfc10008/#name-notational-conventions) 本文档中的关键词“MUST”、“MUST NOT”、“REQUIRED”、“SHALL”、“SHALL NOT”、“SHOULD”、“SHOULD NOT”、“RECOMMENDED”、“NOT RECOMMENDED”、“MAY”和“OPTIONAL”应按照 BCP 14 [RFC2119](https://www.rfc-editor.org/info/rfc10008/#RFC2119) [RFC8174](https://www.rfc-editor.org/info/rfc10008/#RFC8174) 中的描述进行解释，且仅当它们以全大写形式出现时，如下所示。¶ (https://www.rfc-editor.org/info/rfc10008/#section-1.2-1) ## 2. (https://www.rfc-editor.org/info/rfc10008/#section-2) QUERY 方法 (https://www.rfc-editor.org/info/rfc10008/#name-query-method) QUERY 方法用于发起服务器端查询。与 GET 方法（请求目标 URI 标识的资源的表示，如 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 7.1 节 (https://rfc-editor.org/rfc/rfc9110#section-7.1) 所定义）不同，QUERY 方法用于要求目标资源在该目标资源的范围内执行查询操作。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-1) 请求的内容及其媒体类型定义了查询。源服务器根据目标资源确定操作的范围。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-2) 如果 Content-Type 请求字段（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 8.3 节 (https://rfc-editor.org/rfc/rfc9110#section-8.3)）缺失或与请求内容不一致，服务器必须（MUST）使请求失败。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-3) 对于所有 HTTP 方法，目标 URI 的查询部分参与标识正在被查询的资源。它是否以及如何直接影响查询的结果是特定于资源的，不在本规范的范围内。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-4) QUERY 请求对于目标资源是安全的（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 9.2.1 节 (https://rfc-editor.org/rfc/rfc9110#section-9.2.1)）；也就是说，客户端不请求也不期望目标资源的状态发生任何变化。这并不阻止服务器创建额外的 HTTP 资源，以便通过它们检索附加信息（参见第 2.3 (https://www.rfc-editor.org/info/rfc10008/#content-location) 节和第 2.4 (https://www.rfc-editor.org/info/rfc10008/#location) 节）。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-5) 此外，QUERY 请求是幂等的（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 9.2.2 节 (https://rfc-editor.org/rfc/rfc9110#section-9.2.2)）；它们可以在需要时重试或重复，例如在连接失败后。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-6) 根据 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 15.3 节 (https://rfc-editor.org/rfc/rfc9110#section-15.3)，2xx（成功）状态码表示请求已成功接收、理解并接受。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-7) 特别是，200（OK）响应表示查询已成功处理，并且该处理的结果作为响应内容包含在内。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2-8) ### 2.2. (https://www.rfc-editor.org/info/rfc10008/#section-2.2) 等价资源 (https://www.rfc-editor.org/info/rfc10008/#name-equivalent-resource) 对于任何给定的 QUERY 请求，*等价资源* 是一个响应 GET 请求的资源，它表示该 QUERY 请求及其目标，并同时考虑消息内容和元数据（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 6 节 (https://rfc-editor.org/rfc/rfc9110#section-6)）。特别是，这包括表示元数据（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 8 节 (https://rfc-editor.org/rfc/rfc9110#section-8)），例如内容的媒体类型。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.2-1) 换句话说，等价资源是通过将请求内容并入实现 QUERY 的资源而派生出来的。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.2-2) 术语 *等价资源* 用作定义其他 HTTP 方面（如选定的表示）行为的手段。服务器可以但不必须为这些资源分配 URI（参见 [URI](https://www.rfc-editor.org/info/rfc10008/#RFC3986) 第 1.1 节 (https://rfc-editor.org/rfc/rfc3986#section-1.1)）。如果它们这样做了，这些资源将变得可通过 GET 请求访问。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.2-3) ### 2.3. (https://www.rfc-editor.org/info/rfc10008/#section-2.3) Content-Location 响应字段 (https://www.rfc-editor.org/info/rfc10008/#name-content-location-response-f) 成功的响应（2xx，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 15.3 节 (https://rfc-editor.org/rfc/rfc9110#section-15.3)）可以包含一个 Content-Location 头部字段，其中包含对应于操作结果的资源的标识符；详细信息请参见 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 8.7 节 (https://rfc-editor.org/rfc/rfc9110#section-8.7)。这表示服务器声称客户端可以向指示的 URI 发送 GET 请求，以检索刚刚执行的查询操作的结果。所指示的资源可能是临时的。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.3-1) 示例请参见附录 A.4.1 (https://www.rfc-editor.org/info/rfc10008/#example.content-location)。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.3-2) ### 2.4. (https://www.rfc-editor.org/info/rfc10008/#section-2.4) Location 响应字段 (https://www.rfc-editor.org/info/rfc10008/#name-location-response-field) 服务器可以为 QUERY 请求的等价资源（第 2.2 (https://www.rfc-editor.org/info/rfc10008/#equivalent-resource) 节）分配一个 URI。如果服务器这样做，该资源的 URI 可以包含在 2xx 响应的 Location 头部字段中（参见 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 10.2.2 节 (https://rfc-editor.org/rfc/rfc9110#section-10.2.2)）。这表示客户端可以向指示的 URI 发送 GET 请求，以重复刚刚执行的查询操作，而无需重新发送查询内容。该资源的 URI 可能是临时的；如果将来的请求失败，客户端可以使用原始 QUERY 请求目标和之前提交的内容进行重试。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.4-1) 示例请参见附录 A.4.2 (https://www.rfc-editor.org/info/rfc10008/#example.location)。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.4-2) ### 2.5. (https://www.rfc-editor.org/info/rfc10008/#section-2.5) 重定向 (https://www.rfc-editor.org/info/rfc10008/#name-redirection) 在某些情况下，服务器可能选择通过将用户代理重定向到不同的 URI 来间接响应 QUERY 请求（参见 [HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 15.4 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4)）。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.5-1) 状态码为 301（永久移动，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 15.4.2 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4.2)）或 308（永久重定向，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 15.4.9 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4.9)）的响应表示目标资源已永久移动到由 Location 响应字段（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 10.2.2 节 (https://rfc-editor.org/rfc/rfc9110#section-10.2.2)）引用的不同 URI。类似地，状态码为 302（发现，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 15.4.3 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4.3)）或 307（临时重定向，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 15.4.8 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4.8)）的响应表示目标资源已临时移动。在这四种情况下，服务器建议用户代理可以通过向 Location 引用的新目标 URI 发送类似的 QUERY 请求来完成其原始的 QUERY 请求。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.5-2) 请注意，在 301 或 302 响应后将 POST 重定向为 GET 请求的例外情况不适用于 QUERY 请求。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.5-3) 对 QUERY 的响应中状态码为 303（参见其他，[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 15.4.4 节 (https://rfc-editor.org/rfc/rfc9110#section-15.4.4)）表示原始查询可以通过对 Location 响应字段（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110)，第 10.2.2 节 (https://rfc-editor.org/rfc/rfc9110#section-10.2.2)）所引用 URI 的正常检索请求来完成。对于 HTTP，这意味着向新的目标 URI 发送 GET 请求，如附录 A.4.3 (https://www.rfc-editor.org/info/rfc10008/#example.indirect) 中的示例所示。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.5-4) ### 2.6. (https://www.rfc-editor.org/info/rfc10008/#section-2.6) 条件请求 (https://www.rfc-editor.org/info/rfc10008/#name-conditional-requests) QUERY 请求的选定表示（[HTTP](https://www.rfc-editor.org/info/rfc10008/#RFC9110) 第 3.2 节 (https://rfc-editor.org/rfc/rfc9110#section-3.2)）与向该 QUERY 请求的等价资源（第 2.2 (https://www.rfc-editor.org/info/rfc10008/#equivalent-resource) 节）发送 GET 请求时的选定表示相同。¶ (https://www.rfc-editor.org/info/rfc10008/#section-2.6-1) 条件 QUERY 请求要求仅在条件所描述的情况下返回选定的表示（即，任何内容协商后的查询结果）。