HTTP QUERY method，前端传SQL不再是笑话

上周笔者在 github 冲浪的时候发现了这样一个 issues！说起 HTTP method 大家最熟悉的就是 GET 和 POST，今天我们一起来聊聊这个 HTTP QUERY method。

图片

一、介绍

HTTP QUERY 请求方法，这是一种安全、幂等的请求方式，它可包含请求内容。 GET 请求中传达的数据量过大，无法编码到请求的 URI 中时，通常需要使用 QUERY 方法。例如，虽然下面的查询是常见且可互操作的：

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

但如果查询参数扩展到几千字节或更多，可能就不行了，因为许多实现对它们的大小有限制。作为使用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

然而，这种变化与GET一样，存在同样的基本限制，即在没有特定知识的情况下，不容易明显地看出正在执行安全、幂等的查询。

QUERY方法提供了一个介于使用GET和POST之间的解决方案。与POST一样，查询操作的输入在请求的有效载荷中传递，而不是作为请求URI的一部分。然而，与POST不同，该方法明确是安全的和幂等的，允许缓存和自动重试等功能正常工作。

二、QUERY method

QUERY方法用于启动服务器端查询。与HTTP GET方法不同，GET方法请求服务器返回由目标URI标识的资源的表示，QUERY方法用于请求服务器对有效请求URI范围内的某些数据集执行查询操作（由请求有效载荷描述）。对QUERY的响应返回的有效载荷不能假定是有效请求URI标识的资源的表示。

请求的有效载荷定义了查询。实现可以使用任何具有适当查询语义的内容类型与QUERY方法。

QUERY请求对于请求URI标识的资源是安全和幂等的。也就是说，QUERY请求不会改变目标资源的状态。然而，在处理QUERY请求时，可以预期服务器将分配计算和内存资源，甚至可能创建额外的HTTP资源，通过这些资源可以检索响应。

对QUERY请求的成功响应预计将提供有关操作最终结果的某些指示。例如，一个成功的查询如果没有结果，可以用204 No Content响应来表示。如果响应包括内容，预计它将描述操作的结果。在某些情况下，服务器可能选择通过返回一个带有Location头字段的3xx重定向来间接响应QUERY请求，指定一个替代的请求URI，可以使用HTTP GET请求从该URI检索结果。第4节展示了各种非规范的成功QUERY响应示例。

如果请求消息包括If-Modified-Since、If-Unmodified-Since、If-Match、If-None-Match或If-Range头字段，则QUERY方法的语义变为“条件QUERY”。条件QUERY请求仅在条件头字段(们)描述的情况下执行查询。然而，需要注意的是，这些条件是针对目标资源本身的状态进行评估，而不是搜索操作收集的结果。

2.1. 缓存

QUERY方法的响应是可以缓存的；缓存可以根据 HTTP-CACHING 使用它来满足随后的QUERY请求。

查询的缓存键必须包含请求内容。在这样做时，缓存应首先规范化请求内容，以去除语义上不重要的差异，从而提高缓存效率：

• 移除内容编码
• 根据请求的Content-Type字段中的任何媒体类型后缀（例如，“+json”）基于格式约定进行规范化
• 根据请求的Content-Type字段指示的内容本身的语义进行规范化

请注意，任何此类规范化仅用于生成缓存键；它不会更改请求本身。

2.2. “Accept-Query”头字段

“Accept-Query”响应头字段可以由服务器使用，以直接信号支持QUERY方法，同时识别可以使用的特定查询格式媒体类型。

Accept-Query = 1#media-type

Accept-Query头字段指定了由[RFCHTTP]第8.3.1节定义的媒体类型（及可选参数）的逗号分隔列表。

Accept-Query头字段列出的类型顺序无关紧要。

三、 示例

本节中的非规范示例使用基于SQL的简单、假设的纯文本查询语法，并以逗号分隔值的形式返回结果。这只是为了说明目的。实现可以在请求和响应中自由使用任何格式。

3.1. 直接响应的简单QUERY

具有直接响应的简单查询：

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10

响应：

HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, john.smith@example.org
Jones, Sally, sally.jones@example.com
Dubois, Camille, camille.dubois@example.net

3.2. 间接响应的简单QUERY（303 See Other）

具有间接响应（303 See Other）的简单查询：

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10

响应：

HTTP/1.1 303 See Other
Location: http://example.org/contacts/query123

获取查询响应：

GET /contacts/query123 HTTP/1.1
Host: example.org

响应：

HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, john.smith@example.org
Jones, Sally, sally.jones@example.com
Dubois, Camille, camille.dubois@example.net

五、总结

HTTP QUERY method 是个非常不错的提案，期待各个 http 服务端和客户端能够早日实现，服务端数据请求接口再也不用去纠结该使用 GET 还是 POST。对于示例中 QUERY 方法的类 sql 传参，笔者认为可能不会这样实现。但是还是比较期待能有数据库厂商能够提供类 http QUERY 的 sql api。