RFC 10008 HTTP QUERY 方法 2026 年 6 月
Reschke 等 标准跟踪 [页码]
文档流：
互联网工程任务组 (IETF)
RFC：
10008
类别：
标准跟踪
发布日期：
ISSN：
2070-1721
作者：
J. Reschke
greenbytes
J.M. Snell
Cloudflare
M. Bishop
Akamai

RFC 10008

HTTP QUERY 方法

摘要

本规范定义了 HTTP 的 QUERY 方法。 QUERY 请求要求请求目标以安全且幂等的方式处理其中包含的 内容，然后以该处理的结果进行响应。这类似于 POST 请求，但 QUERY 请求 可以自动重复或重新启动，而无需担心 部分状态更改。

本备忘录的状态

这是一份互联网标准跟踪文档。

本文档是互联网工程任务组 (IETF) 的成果。它代表了 IETF 社区的共识。本文档已经 过公开评审，并已获互联网工程指导组 (IESG) 批准发布。有关 互联网标准的更多信息，请参阅 RFC 7841 第 2 节。

有关本文档当前状态、任何 勘误以及如何提供反馈的信息，可在 https://www.rfc-editor.org/info/rfc10008 获取。

▲

目录

1. 引言

本规范定义了 HTTP QUERY 请求方法，作为一种 发出安全、幂等请求（[HTTP] 的 第 9.2 节）的方式，该请求 包含一个表示形式，用于描述目标资源应如何处理该请求。

一种常见的查询模式是：

GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
Host: example.org

但是，当所传递的数据量太大，无法编码到请求的 URI 中时， 这种模式就会出现问题：

作为使用 GET 的替代方案，许多实现会使用 HTTP POST 方法来执行查询，如下面的示例 所示。在这种情况下，查询操作的输入 作为请求内容传递，而不是使用 请求 URI 的查询组件。

使用 HTTP POST 请求查询的一种典型方式是：

POST /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

然而，在这种变体中，如果不了解该请求所发送到的 资源和服务器的具体信息，就无法轻易看出正在执行的是一个安全、 幂等的查询。

QUERY 方法提供了一种跨越 GET 和 POST 使用方式之间差距的解决方案，上面的 示例可以表示为：

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

与 POST 一样，查询操作的输入作为请求内容传递， 而不是作为请求 URI 的一部分。但是，与 POST 不同，该方法明确是安全且 幂等的，因此可以使用缓存和自动重试等功能。

鉴于任何重要资源都应当由 URI 标识这一设计原则，本规范描述了服务器如何为查询本身或 特定查询结果分配 URI，以便以后在 GET 请求中使用。

总结如下：

表 1： 相关方法 属性摘要
GET QUERY POST
安全 是 是 可能不是
幂等 是 是 可能不是
查询本身的 URI 是（按定义） 可选（Location 响应字段） 否
查询结果的 URI 可选（Content-Location 响应字段） 可选（Content-Location 响应字段） 可选（Content-Location 响应字段）
可缓存 是 是 是，但仅用于未来的 GET 或 HEAD 请求
内容（正文） “没有定义的语义” 预期存在（语义由目标资源定义） 预期存在（语义由目标资源定义）

1.1. 术语

本文档使用 [HTTP] 第 3 节中定义的术语。

此外，它使用术语 URI 查询参数 指代 URI 查询组件中的参数（[HTTP] 的 第 4.2.2 节），并使用 查询内容 指代 QUERY 请求的请求内容（[HTTP] 的 第 6.4 节）。

1.2. 符号约定

本文档中的关键词“必须（MUST）”、“不得（MUST NOT）”、“要求（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“建议（RECOMMENDED）”、“不建议（NOT RECOMMENDED）”、 “可以（MAY）”和“可选（OPTIONAL）” 仅当它们像此处所示以全大写形式出现时， 才应按照 BCP 14 [RFC2119] [RFC8174] 中的描述进行解释。

2. QUERY 方法

QUERY 方法用于发起服务器端查询。与 GET 方法不同，GET 方法请求由目标 URI 标识的资源的 表示形式 （如 [HTTP] 的 第 7.1 节所定义），QUERY 方法用于请求目标资源在 该目标资源的范围内执行查询操作。

请求的内容及其媒体类型定义查询。 源服务器根据目标资源确定操作的范围。

如果 Content-Type 请求字段 （[HTTP]，第 8.3 节） 缺失或与请求内容不一致，服务器必须使请求失败。

与所有 HTTP 方法一样，目标 URI 的查询部分 参与标识被查询的资源。它是否以及如何 直接影响查询结果由资源本身决定， 不属于本规范的范围。

QUERY 请求对于目标资源而言是安全的 （[HTTP]，第 9.2.1 节）； 也就是说，客户端不会请求或期望对 目标资源的状态作任何更改。这并不妨碍服务器 创建额外的 HTTP 资源，通过这些资源可以检索额外 信息（参见第 2.3 节和第 2.4 节）。

此外，QUERY 请求是幂等的 （[HTTP]，第 9.2.2 节）； 它们可以在需要时重试或重复，例如在 连接失败之后。

根据 [HTTP] 的 第 15.3 节，2xx（成功）响应代码表示 请求已被成功接收、理解并接受。

特别是，200（OK）响应表示查询 已被成功处理，并且该处理的结果 包含在响应内容中。

2.1. 媒体类型和 内容协商

QUERY 请求的语义同时取决于请求内容和相关的 元数据，例如媒体类型（[HTTP]，第 8.3.1 节）。 一般而言，任何内容与元数据不一致的请求问题都必须 使用 4xx（客户端错误）响应拒绝（[HTTP]，第 15.5 节）。

下面的列表描述了各种失败情况，并建议了具体的状态代码：

  • 如果请求缺少媒体类型信息，则根据定义它是不正确的，需要以 4xx 状态代码失败，例如 400（客户端错误）。
  • 如果指定了媒体类型，但资源不支持该类型，则 415（不支持的媒体 类型） 是适当的。这尤其包括媒体类型原则上 已知，但对于针对目标资源的 QUERY 缺乏特定语义的情况。在 这两种情况下， 可以使用 Accept-Query 响应字段（第 3 节）告知 客户端所支持的媒体类型。
  • 如果指定了媒体类型，但它与实际请求内容不一致， 可以返回 400（错误请求）。也就是说，不允许服务器从 请求内容推断媒体类型，然后覆盖缺失或“错误”的值 （即“内容嗅探”）。
  • 如果媒体类型已指定且可理解，并且内容确实与该 类型一致，但由于查询的实际内容而无法处理查询， 可以使用状态 422（无法处理的内容）。例如，一个语法上 正确但标识了不存在表的 SQL 查询。
  • 如果客户端使用 Accept 字段（[HTTP]，第 12.5.1 节）请求资源不支持的特定响应媒体类型， 则状态代码 406（不可接受）是适当的。

2.2. 等效资源

对于任何给定的 QUERY 请求，其等效资源是这样一种资源： 它响应 GET 请求，表示该 QUERY 请求及其目标，并同时考虑 消息内容和元数据（[HTTP] 的 第 6 节）。 特别是，这包括表示形式元数据（[HTTP] 的 第 8 节）， 例如内容的媒体类型。

换句话说，等效资源是通过纳入请求内容， 从实现 QUERY 的资源派生出来的。

术语等效资源用于定义 其他 HTTP 方面的行为，例如所选择的表示形式。服务器可以 为这些资源分配 URI，但并非必须如此（参见 [URI] 的 第 1.1 节）。如果这样做，这些资源将 可通过 GET 请求访问。

2.3. Content-Location 响应字段

成功响应（2xx，[HTTP] 的 第 15.3 节） 可以包含一个 Content-Location 标头字段，其中包含一个与 操作结果相对应的资源标识符；详情参见 [HTTP] 的 第 8.7 节。 这表示服务器声称客户端可以向 指示的 URI 发送 GET 请求，以检索刚刚执行的查询 操作的结果。所指示的资源可能是临时的。

示例参见附录 A.4.1。

2.4. Location 响应 字段

服务器可以为 QUERY 请求的等效资源（第 2.2 节） 分配 URI。如果服务器这样做，该资源的 URI 可以包含在 2xx 响应的 Location 标头字段中（参见 [HTTP] 的 第 10.2.2 节）。这表示服务器声称客户端可以 向所指示的 URI 发送 GET 请求，以重复刚刚 执行的查询操作，而无需重新发送查询内容。该资源的 URI 可能是 临时的；如果未来的请求失败，客户端可以使用 原始 QUERY 请求目标和先前提交的内容重试。

示例参见附录 A.4.2。

2.5. 重定向

在某些情况下，服务器可以选择通过将用户代理重定向到不同的 URI， 以间接方式响应 QUERY 请求（参见 [HTTP] 的 第 15.4 节）。

状态代码为 301（永久移动，[HTTP]，第 15.4.2 节）或 308（永久重定向，[HTTP]，第 15.4.9 节） 的响应表示目标资源已经永久移动到由 Location 响应字段引用的另一个 URI（[HTTP]，第 10.2.2 节）。 同样，状态代码为 302（已找到，[HTTP]，第 15.4.3 节）或 307（临时重定向，[HTTP]，第 15.4.8 节） 的响应表示目标资源已临时移动。在所有这四种情况下，服务器都在 建议用户代理可以通过向 Location 引用的新目标 URI 发送一个 类似的 QUERY 请求来完成其原始 QUERY 请求。

请注意，在 301 或 302 响应后将 POST 重定向为 GET 请求的例外 不适用于 QUERY 请求。

对 QUERY 的状态代码 303（参见其他，[HTTP] 的 第 15.4.4 节） 响应表示原始查询可以通过对 Location 响应字段所引用的 URI 发出普通检索请求来完成 （[HTTP]，第 10.2.2 节）。 对于 HTTP，这意味着向新的目标 URI 发送 GET 请求，如 附录 A.4.3中的示例所示。

2.6. 条件请求

QUERY 请求的所选择表示形式（[HTTP] 的 第 3.2 节） 与向该 QUERY 请求的等效资源 （第 2.2 节）发送 GET 请求时相同。

条件 QUERY 请求要求仅在 条件标头字段所描述的情况下，才在响应中 返回所选择的表示形式 （即经过任何内容协商后的查询结果），如 [HTTP] 的 第 13 节所定义。

示例参见附录 A.5。

2.7. 缓存

QUERY 方法的响应是可缓存的；缓存可以按照 [HTTP-CACHING] 的 第 4 节使用它来 满足后续 QUERY 请求。

QUERY 请求的缓存键（[HTTP-CACHING] 的 第 2 节）必须 纳入请求内容（[HTTP-CACHING] 的 第 6 节）以及相关的 元数据（[HTTP] 的 第 8 节）。

为了提高缓存效率，缓存可以先从请求内容和相关元数据中移除 语义上无关紧要的差异。例如，可以：

  • 移除内容编码（[HTTP] 的 第 8.4 节）。
  • 根据对格式约定的了解进行规范化， 如请求的 Content-Type 字段中任何 媒体子类型后缀所指示的那样（例如“+json”；参见 [RFC6838] 的 第 4.2.8 节）。
  • 根据对内容本身语义的了解进行规范化， 如请求的 Content-Type 字段所指示。

请注意，任何此类转换都仅用于生成缓存键； 它 不会改变请求本身。

客户端可以使用“no-transform”缓存指令（[HTTP-CACHING] 的 第 5.2.1.6 节） 表明它们希望不发生此类转换（但请注意，该指令仅具有 建议性质）。

请注意，缓存 QUERY 方法响应本质上比缓存 GET 响应更复杂，因为需要完整读取请求内容才能确定 缓存键。如果 QUERY 响应提供 Location 响应字段（第 2.4 节） 来指示等效资源（第 2.2 节）的 URI，客户端 可以在后续请求中切换到 GET，从而简化处理。

2.8. 范围请求

QUERY 的范围请求语义与 GET 完全相同， 如 [HTTP] 的 第 14 节所定义。 然而，字节范围请求（撰写本文时唯一已定义的范围单位） 对 QUERY 请求的结果几乎没有价值。

查询格式通常会定义自己限制结果集或对结果集分页的方式， 例如 SQL 中的“FETCH FIRST ... ROWS ONLY”。预期将使用这些 内置功能，而不是 HTTP 范围请求。

3. Accept-Query 标头字段

资源可以使用“Accept-Query”响应标头字段 直接表示对 QUERY 方法的支持，同时标识 可以使用的具体查询格式媒体类型。

Accept-Query 包含一个媒体范围列表（[HTTP] 的 第 12.5.1 节）， 使用“结构化字段”语法 [STRUCTURED-FIELDS]。 媒体范围由 Token 或 String 组成的 List 结构化标头字段表示，其中包含不带参数的媒体范围值。

媒体类型参数（如果有）映射到 String 或 Token 类型的结构化字段参数。选择 Token 还是 String 在语义上没有区别。也就是说，接收方可以 将 Token 转换为 String，但不得根据接收到的类型 对它们进行不同处理。

媒体类型并不能完全映射到 Token；例如，它们 允许以数字开头。在此类情况下，需要 使用 String 格式。

通配符唯一受支持的用法是“*/*”（匹配任何类型） 或“xxxx/*”（匹配所指示类型的任何子类型）。

字段值中所列类型的顺序无关紧要。

Accept-Query 字段的值适用于服务器上共享相同路径的每个 URI；换言之， 查询组件会被忽略。如果对同一资源的请求返回 不同的 Accept-Query 值，则使用最近收到的仍然新鲜的值（按照 [HTTP-CACHING] 的 第 4.2 节）。

例如：

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

尽管该字段的语法看起来与其他 字段（例如“Accept”（[HTTP] 的 第 12.5.1 节））相似， 但它是一个结构化字段，因此必须按照 [STRUCTURED-FIELDS] 的 第 4 节中的规定进行处理。

4. 安全注意事项

QUERY 方法与所有 HTTP 方法一样，受到 [HTTP] 中所述的一般安全 注意事项约束。

它可以作为在 URI 中传递请求 信息（例如在查询组件中）的替代方案。在某些 情况下，这是首选方式，因为与请求内容相比，URI 更可能被 中间设备记录或以其他方式处理。在其他情况下，当查询 包含敏感信息时，URI 可能被记录这一点可能 促使使用 QUERY 而不是 GET。

如果服务器创建临时资源来表示 QUERY 请求的结果（例如用于 Location 或 Content-Location 字段），为该资源分配 URI， 并且请求包含不能被记录的敏感信息， 那么该 URI应该选择为不包含原始请求内容的任何敏感 部分。

如果缓存以不正确的方式规范化 QUERY 内容，或者其方式与 资源处理内容的方式存在显著差异， 那么当规范化导致误判时，可能会返回错误响应。

实现跨源资源共享（CORS）的用户代理所发出的 QUERY 请求 将需要“预检”请求， 因为 QUERY 不属于 CORS 安全列出的方法集合 （参见 [FETCH]）。

5. IANA 注意事项

5.1. QUERY 方法的注册

IANA 已将 QUERY 方法添加到位于 <http://www.iana.org/assignments/http-methods> 的“超文本传输协议（HTTP）方法注册表” （参见 [HTTP] 的 第 16.3.1 节）。

表 2： QUERY 方法定义
方法名称 安全 幂等 规范
QUERY 是 是 RFC 10008 的第 2 节

5.2. Accept-Query 字段的注册

IANA 已将 Accept-Query 字段添加到“超文本传输协议（HTTP）字段名称 注册表”， 地址为 <https://www.iana.org/assignments/http-fields> （参见 [HTTP] 的 第 16.1.1 节）。

表 3： Accept-Query 字段 定义
字段名称 状态 结构化类型 参考 注释
Accept-Query 永久 List RFC 10008 的第 3 节

6. 参考文献

6.1. 规范性参考文献

[HTTP]
Fielding, R.，编辑、Nottingham, M.， 编辑和 J. Reschke，编辑，“HTTP 语义”，STD 97，RFC 9110，DOI 10.17487/RFC9110，，<https://www.rfc-editor.org/info/rfc9110>。
[HTTP-CACHING]
Fielding, R.，编辑、Nottingham, M.， 编辑和 J. Reschke，编辑，“HTTP 缓存”，STD 98，RFC 9111，DOI 10.17487/RFC9111，，<https://www.rfc-editor.org/info/rfc9111>。
[RFC2119]
Bradner, S.，“用于 表示 RFC 要求级别的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，，<https://www.rfc-editor.org/info/rfc2119>。
[RFC8174]
Leiba, B.，“RFC 2119 关键词中大写与 小写的歧义”，BCP 14，RFC 8174，DOI 10.17487/RFC8174，，<https://www.rfc-editor.org/info/rfc8174>。
[STRUCTURED-FIELDS]
Nottingham, M. 和 P. Kamp，“HTTP 的结构化字段值”，RFC 9651，DOI 10.17487/RFC9651，，<https://www.rfc-editor.org/info/rfc9651>。
[URI]
Berners-Lee, T.、Fielding, R. 和 L. Masinter，“统一资源标识符 （URI）：通用语法”，STD 66，RFC 3986，DOI 10.17487/RFC3986，，<https://www.rfc-editor.org/info/rfc3986>。

6.2. 资料性参考文献

[FETCH]
WHATWG，“FETCH”，WHATWG 现行标准，<https://fetch.spec.whatwg.org>。提交快照：<https://fetch.spec.whatwg.org/commit-snapshots/3bab31a55154bda73f25b45a23df718616f2f64e/>。
[RFC3253]
Clemm, G.、Amsden, J.、Ellison, T.、Kaler, C. 和 J. Whitehead，“WebDAV （Web 分布式创作和版本控制）的版本控制扩展”，RFC 3253， DOI 10.17487/RFC3253，，<https://www.rfc-editor.org/info/rfc3253>。
[RFC4918]
Dusseault, L.，编辑，“Web 分布式创作和版本控制（WebDAV）的 HTTP 扩展”，RFC 4918， DOI 10.17487/RFC4918，，<https://www.rfc-editor.org/info/rfc4918>。
[RFC5323]
Reschke, J.，编辑、Reddy, S.、Davis, J. 和 A. Babich，“Web 分布式创作和版本控制（WebDAV）SEARCH”，RFC 5323，DOI 10.17487/RFC5323，，<https://www.rfc-editor.org/info/rfc5323>。
[RFC6838]
Freed, N.、Klensin, J. 和 T. Hansen，“媒体类型规范和 注册程序”，BCP 13，RFC 6838，DOI 10.17487/RFC6838，，<https://www.rfc-editor.org/info/rfc6838>。
[RFC8259]
Bray, T.，编辑，“JavaScript 对象表示法 （JSON）数据交换格式”，STD 90，RFC 8259，DOI 10.17487/RFC8259，，<https://www.rfc-editor.org/info/rfc8259>。
[RFC9535]
Gössner, S.，编辑、Normington, G.，编辑 和 C. Bormann，编辑，“JSONPath：JSON 查询表达式”，RFC 9535，DOI 10.17487/RFC9535，，<https://www.rfc-editor.org/info/rfc9535>。
[URL]
WHATWG，“URL”，WHATWG 现行标准，<https://url.spec.whatwg.org>。提交快照：<https://url.spec.whatwg.org/commit-snapshots/52526653e848c5a56598c84aa4bc8ac9025fb66b/>。
[XSLT]
Kay, M.，编辑，“XSL 转换（XSLT） 3.0 版”，W3C 推荐标准，，<https://www.w3.org/TR/2017/REC-xslt-30-20170608/>。 最新版本位于 https://www.w3.org/TR/xslt-30/。

附录 A. 示例

下面的示例仅用于说明；如果确实需要 发送这么短的查询，那么使用 GET 可能更合适。

大多数示例中使用的媒体类型是“application/x-www-form-urlencoded” （如浏览器用户客户端的 POST 请求所使用，并在 [URL] 中的 “application/x-www-form-urlencoded” 中定义）。 为简洁起见，省略了 Content-Length 字段。

A.1. 简单查询

下面是一个带有直接响应的简单查询：

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

响应：

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

A.2. 发现 QUERY 支持

OPTIONS （[HTTP] 的 第 9.3.7 节）方法提供了一种发现 QUERY 支持的简单方式：

OPTIONS /contacts HTTP/1.1
Host: example.org

响应：

HTTP/1.1 200 OK
Allow: GET, QUERY, OPTIONS, HEAD

Allow 响应字段（[HTTP] 的 第 10.2.1 节）表示指定资源上 支持的方法集合。

除使用 OPTIONS 外，还有其他替代方式。例如，可以在 事先不知道服务器是否支持的情况下尝试 QUERY 请求。服务器随后 要么处理该请求，要么可以返回 4xx 状态，例如 405（方法不 允许， [HTTP] 的 第 15.5.6 节），并包含 Allow 响应字段。

A.3. 发现 QUERY 格式

可以通过 Accept-Query 响应字段（第 3 节）发现 QUERY 支持的媒体类型：

HEAD /contacts HTTP/1.1
Host: example.org

响应：

HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sql

哪些请求方法的响应会包含 Accept-Query，取决于 正在访问的资源。

检查 Accept-Query 的另一种方式是发出 QUERY 请求，然后 ——如果返回 4xx 状态，例如 415 响应（不支持的媒体类型，[HTTP] 的 第 15.5.16 节）—— 检查 Accept 响应字段（[HTTP] 的 第 12.5.1 节）：

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/xhtml
Accept: application/x-www-form-urlencoded, application/sql

A.4. Content-Location、 Location 和间接响应

如第 2.3 节和第 2.4 节所述，成功响应中的 Content-Location 和 Location 响应字段 （2xx，[HTTP] 的 第 15.3 节）提供了一种 标识替代资源的方式， 这些资源会响应 GET 请求，既可以用于获取已收到的请求结果，也可以用于未来 执行相同操作的请求。回到附录 A.1中的示例： 

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

响应：

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:24 GMT

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

A.4.1. 使用 Content-Location

上面收到的 Content-Location 响应字段标识了一个保存 其所在 QUERY 响应结果的资源：

GET /contacts/stored-results/17 HTTP/1.1
Host: example.org
Accept: application/json

响应：

HTTP/1.1 200 OK
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:25 GMT

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

请注意，无法保证服务器会无限期地实现此资源， 因此，在收到错误响应后，客户端需要重新发出 原始 QUERY 请求，以获得新的替代位置。

A.4.2. 使用 Location

Location 响应字段标识一个资源，该资源会响应 GET， 返回与原始 QUERY 请求相同过程和参数的当前结果。

GET /contacts/stored-queries/42 HTTP/1.1
Host: example.org
Accept: application/json

在此示例中，一条记录于 2024-11-17T16:12:01Z 被移除（如 Last-Modified 字段所示），因此响应只包含两条记录：

HTTP/1.1 200 OK
Content-Type: application/json
Last-Modified: Sun, 17 November 2024, 16:12:01 GMT
ETag: "42-1"
Date: Sun, 17 Nov 2024, 16:13:17 GMT

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Dubois",
    "givenname": "Camille",
    "email": "camille.dubois@example.net" }
]

假设服务器仍然公开该资源，并且查询结果没有变化， 则随后带有以下内容的条件 GET 请求：

If-None-Match: "42-1"

将产生 304（未修改）响应（[HTTP] 的 第 15.4.5 节）。

A.4.3. 间接响应

服务器可以使用状态代码 303（参见其他， [HTTP] 的 第 15.4.4 节）发送“间接”响应（第 2.5 节）。

对于附录 A.4开头的请求， 服务器可以响应：

HTTP/1.1 303 See Other
Content-Type: text/plain
Date: Sun, 17 Nov 2024, 16:13:17 GMT
Location: /contacts/stored-queries/42

在“/contacts/stored-queries/42”查看已存储的查询。

这类似于在直接响应中包含 Location，只是不会返回 查询结果。这允许服务器仅生成或复用一个 替代 资源。然后可以像 附录 A.4.2中所示那样使用该资源。

A.5. 条件请求

考虑一个实现 QUERY 的资源，它支持“application/sql”和 “application/xslt+xml” [XSLT] 作为请求 媒体类型，并且 可以生成“text/csv”响应。被查询的数据集包含 RFC 文档 信息，并且查询返回按十年分组的信息：

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Content-Type: application/xslt+xml
Accept: text/csv

...Query content using XSLT...

响应：

HTTP/1.1 200 OK
Date: Sun, 7 Sep 2025, 00:00:00 GMT
Location: /stored-queries/4815162342
Content-Type: text/csv
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

此处，服务器已将路径“/stored-queries/4815162342”分配给等效 资源（第 2.4 节），以便随后 与 GET 一起使用。

稍后，客户端重复该查询，但指定只有当结果 发生变化时才返回：

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Date: Mon, 8, Sep 2025, 11:00:00 GMT
Content-Type: application/sql
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

...Same query, but using SQL...

被查询的数据没有变化，因此服务器响应：

HTTP/1.1 304 Not Modified
Date: Mon, 8 Sep 2025, 11:00:00 GMT
Content-Type: text/csv
Location: /stored-queries/4815162342
Accept-Query: "application/sql", "application/xslt+xml"
Last-Modified: Sun, 31 Aug 2025, 08:44:00 GMT
Vary: Accept-Query, Content-Type

由于服务器为等效资源标识了 URI，因此可以 使用 GET 访问该资源。特别是，这避免了重新发送查询请求的 内容：

GET /stored-queries/4815162342 HTTP/1.1
Host: example.org
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Accept: text/csv
If-Modified-Since: Sun, 31 Aug 2025, 00:00:00 GMT

此处，数据集的状态确实发生了变化，因此返回新内容：

HTTP/1.1 200 OK
Date: Sun, 21, Sep 2025, 12:08:00 GMT
Content-Type: text/csv
Last-Modified: Thu, 18 Sep 2025, 19:56:00 GMT
Vary: Accept-Query, Content-Encoding, Content-Type

decade, total, with errata, % with errata, average page count
1960, 26, 5, 19.2, 5.3
1970, 666, 18, 2.7, 6.1
1980, 376, 44, 11.7, 23.4
1990, 1593, 269, 16.9, 25.5
2000, 2888, 1048, 36.3, 27.3
2010, 2954, 895, 30.3, 26.1
2020, 1133, 230, 20.3, 26.2

（请注意本十年对应行中的变化。）

下面的图示说明了条件请求的使用方式，以及当为等效资源分配 URI 时 （以及客户端利用该 URI 时）它们可能有何不同。 虚构的字段名称“Validator”仅用于演示。

客户端 资源 带内容的 QUERY 200 OK Validator: foo 带内容的 QUERY （以“foo”为条件） 304 未修改 Validator: foo 状态变化 带内容的 QUERY （以“foo”为条件） 200 OK Validator: bar
图 1： 仅使用 QUERY 时的数据流
客户端 资源 带内容的 QUERY 等效资源 （生成 /xyz） 200 OK Validator: foo Location: /xyz GET （以“foo”为条件） 304 未修改 Validator: foo 状态变化 GET （以“foo”为条件） 200 OK Validator: bar
图 2： 使用 GET 访问等效 资源时的数据流

A.6. 更多查询格式

以下示例展示了对一个采用 JSON 结构的 [RFC8259] RFC 勘误 数据库发出的请求。

下面的请求使用可扩展样式表语言转换（XSLT）来提取 按年份和 已定义勘误类型汇总的勘误信息。

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/xslt+xml
Accept: application/xml, text/csv

<transform xmlns="http://www.w3.org/1999/XSL/Transform"
  xmlns:j="http://www.w3.org/2005/xpath-functions"
  version="3.0">

  <output method="text"/>

  <param name="input"/>

  <variable name="json"
    select="json-to-xml(unparsed-text($input))"/>

  <variable name="sc">errata_status_code</variable>
  <variable name="sd">submit_date</variable>

  <template match="/">
    <text>year, total, rejected, verified, hdu, reported</text>
    <text>&#10;</text>
    <variable name="en" select="$json//j:map"/>
    <for-each-group select="$en"
      group-by="substring-before(j:string[@key=$sd],'-')">
      <sort select="current-grouping-key()"/>
      <variable name="year" select="current-grouping-key()"/>
      <variable name="errata" select=
        "$en[$year=substring-before(j:string[@key=$sd],'-')]"/>
      <value-of select="concat(
        $year,
        ', ',
        count($errata),
        ', ',
        count($errata['Rejected'=j:string[@key=$sc]]),
        ', ',
        count($errata['Verified'=j:string[@key=$sc]]),
        ', ',
        count(
          $errata['Held for Document Update'=j:string[@key=$sc]]),
        ', ',
        count($errata['Reported'=j:string[@key=$sc]]),
        '&#10;')"/>
    </for-each-group>
  </template>

</transform>

响应：

HTTP/1.1 200 OK
Content-Type: text/csv
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Wed, 19 Feb 2025, 17:10:01 GMT

year, total, rejected, verified, hdu, reported
2000, 14, 0, 14, 0, 0
2001, 72, 1, 70, 1, 0
2002, 124, 8, 104, 12, 0
2003, 63, 0, 61, 2, 0
2004, 89, 1, 83, 5, 0
2005, 156, 10, 96, 50, 0
2006, 444, 54, 176, 214, 0
2007, 429, 48, 188, 193, 0
2008, 423, 52, 165, 206, 0
2009, 331, 39, 148, 144, 0
2010, 538, 80, 232, 222, 4
2011, 367, 47, 170, 150, 0
2012, 348, 54, 149, 145, 0
2013, 341, 61, 169, 106, 5
2014, 342, 73, 180, 72, 17
2015, 343, 79, 145, 89, 30
2016, 295, 46, 122, 82, 45
2017, 303, 46, 120, 84, 53
2018, 350, 61, 118, 98, 73
2019, 335, 47, 131, 94, 63
2020, 387, 68, 117, 123, 79
2021, 321, 44, 148, 63, 66
2022, 358, 37, 198, 40, 83
2023, 262, 38, 121, 33, 70
2024, 322, 33, 125, 23, 141
9999, 1, 0, 0, 1, 0

请注意，Accept-Query 响应字段表明还支持另一种查询格式 JSONPath [RFC9535]。下面的 请求将报告自 2024 年以来提交的所有被拒绝勘误的 标识符： 

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$..[
     ?@.errata_status_code=="Rejected"
     && @.submit_date>"2024"
   ]
   ["doc-id"]

响应：

HTTP/1.1 200 OK
Content-Type: application/json
Accept-Query: "application/jsonpath", "application/xslt+xml"
Date: Thu, 20 Feb 2025, 09:55:42 GMT
Last-Modified: Thu, 20 Feb 2025 06:10:01 GMT

[
  "RFC1185","RFC8407","RFC6350","RFC8467","RFC1157","RFC9543",
  "RFC9076","RFC7656","RFC2822","RFC9460","RFC2104","RFC6797",
  "RFC9499","RFC9557","RFC2131","RFC2328","RFC9001","RFC3325",
  "RFC9438","RFC2526","RFC2985","RFC7643","RFC9132","RFC6376",
  "RFC9110","RFC9460","RFC7748","RFC9497","RFC8463","RFC4035",
  "RFC7239","RFC9083","RFC9537","RFC9537","RFC9420","RFC9000",
  "RFC9656","RFC9110","RFC2324","RFC2549","RFC6797","RFC2549",
  "RFC8894"
]

附录 B. 方法名称 “QUERY”的选择

“超文本传输协议（HTTP）方法注册表”（<http://www.iana.org/assignments/http-methods>） 已经包含另外三个具有“安全”和“幂等”属性的方法： “PROPFIND” [RFC4918]、“REPORT” [RFC3253] 和 “SEARCH” [RFC5323]。

本来可以复用其中任何一个方法，并对其进行更新，使其匹配 本规范定义的新方法“QUERY”。实际上，本规范的早期阶段 使用的是“SEARCH”。

最终选择方法名称“QUERY”的原因是：

致谢

感谢 HTTP 工作组的所有成员提供想法、评审和反馈。

以下人员值得特别致谢： Carsten Bormann、 Mark Nottingham、 Martin Thomson、 Michael Thornburgh、 Roberto Polli、 Roy Fielding 和 Will Hawkins。

贡献者

Ashok Malhotra 参与了促成本 规范形成的早期讨论：

Ashok Malhotra

Asbjørn Ulsberg 在 2019 年 HTTP 研讨会上重新开启了关于该 HTTP 方法的讨论：

Asbjørn Ulsberg
URI： https://asbjor.nu/

作者地址

Julian Reschke
greenbytes GmbH
Hafenweg 16
48155 Münster
德国
URI： https://greenbytes.de/tech/webdav/
James M Snell
Cloudflare
Mike Bishop
Akamai