上周筆者在 github 沖浪的時候發(fā)現(xiàn)了這樣一個 issues！說起 HTTP method 大家最熟悉的就是 GET 和 POST，今天我們一起來聊聊這個 HTTP QUERY method。

圖片

一、介紹

HTTP QUERY 請求方法，這是一種安全、冪等的請求方式，它可包含請求內(nèi)容。 GET 請求中傳達的數(shù)據(jù)量過大，無法編碼到請求的 URI 中時，通常需要使用 QUERY 方法。例如，雖然下面的查詢是常見且可互操作的：

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

但如果查詢參數(shù)擴展到幾千字節(jié)或更多，可能就不行了，因為許多實現(xiàn)對它們的大小有限制。作為使用GET的替代方案，許多實現(xiàn)使用 HTTP POST 方法執(zhí)行查詢，如下例所示。在這種情況下，搜索操作的輸入?yún)?shù)在請求有效載荷中傳遞，而不是使用請求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一樣，存在同樣的基本限制，即在沒有特定知識的情況下，不容易明顯地看出正在執(zhí)行安全、冪等的查詢。

QUERY方法提供了一個介于使用GET和POST之間的解決方案。與POST一樣，查詢操作的輸入在請求的有效載荷中傳遞，而不是作為請求URI的一部分。然而，與POST不同，該方法明確是安全的和冪等的，允許緩存和自動重試等功能正常工作。

二、QUERY method

QUERY方法用于啟動服務器端查詢。與HTTP GET方法不同，GET方法請求服務器返回由目標URI標識的資源的表示，QUERY方法用于請求服務器對有效請求URI范圍內(nèi)的某些數(shù)據(jù)集執(zhí)行查詢操作（由請求有效載荷描述）。對QUERY的響應返回的有效載荷不能假定是有效請求URI標識的資源的表示。

請求的有效載荷定義了查詢。實現(xiàn)可以使用任何具有適當查詢語義的內(nèi)容類型與QUERY方法。

QUERY請求對于請求URI標識的資源是安全和冪等的。也就是說，QUERY請求不會改變目標資源的狀態(tài)。然而，在處理QUERY請求時，可以預期服務器將分配計算和內(nèi)存資源，甚至可能創(chuàng)建額外的HTTP資源，通過這些資源可以檢索響應。

對QUERY請求的成功響應預計將提供有關(guān)操作最終結(jié)果的某些指示。例如，一個成功的查詢?nèi)绻麤]有結(jié)果，可以用204 No Content響應來表示。如果響應包括內(nèi)容，預計它將描述操作的結(jié)果。在某些情況下，服務器可能選擇通過返回一個帶有Location頭字段的3xx重定向來間接響應QUERY請求，指定一個替代的請求URI，可以使用HTTP GET請求從該URI檢索結(jié)果。第4節(jié)展示了各種非規(guī)范的成功QUERY響應示例。

如果請求消息包括If-Modified-Since、If-Unmodified-Since、If-Match、If-None-Match或If-Range頭字段，則QUERY方法的語義變?yōu)椤皸l件QUERY”。條件QUERY請求僅在條件頭字段(們)描述的情況下執(zhí)行查詢。然而，需要注意的是，這些條件是針對目標資源本身的狀態(tài)進行評估，而不是搜索操作收集的結(jié)果。

2.1. 緩存

QUERY方法的響應是可以緩存的；緩存可以根據(jù) HTTP-CACHING 使用它來滿足隨后的QUERY請求。

查詢的緩存鍵必須包含請求內(nèi)容。在這樣做時，緩存應首先規(guī)范化請求內(nèi)容，以去除語義上不重要的差異，從而提高緩存效率：

• 移除內(nèi)容編碼
• 根據(jù)請求的Content-Type字段中的任何媒體類型后綴（例如，“+json”）基于格式約定進行規(guī)范化
• 根據(jù)請求的Content-Type字段指示的內(nèi)容本身的語義進行規(guī)范化

請注意，任何此類規(guī)范化僅用于生成緩存鍵；它不會更改請求本身。

2.2. “Accept-Query”頭字段

“Accept-Query”響應頭字段可以由服務器使用，以直接信號支持QUERY方法，同時識別可以使用的特定查詢格式媒體類型。

Accept-Query = 1#media-type

Accept-Query頭字段指定了由[RFCHTTP]第8.3.1節(jié)定義的媒體類型（及可選參數(shù)）的逗號分隔列表。

Accept-Query頭字段列出的類型順序無關(guān)緊要。

三、 示例

本節(jié)中的非規(guī)范示例使用基于SQL的簡單、假設(shè)的純文本查詢語法，并以逗號分隔值的形式返回結(jié)果。這只是為了說明目的。實現(xiàn)可以在請求和響應中自由使用任何格式。

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

五、總結(jié)

HTTP QUERY method 是個非常不錯的提案，期待各個 http 服務端和客戶端能夠早日實現(xiàn)，服務端數(shù)據(jù)請求接口再也不用去糾結(jié)該使用 GET 還是 POST。對于示例中 QUERY 方法的類 sql 傳參，筆者認為可能不會這樣實現(xiàn)。但是還是比較期待能有數(shù)據(jù)庫廠商能夠提供類 http QUERY 的 sql api。