小編精選 - 技術文章翻譯 · 07月06日

新的 HTTP 方法：QUERY

你有在使用 REST API 嗎？你知道 GET、POST、PUT、DELETE……

但你知道有一個新的 HTTP 方法在 2026 年 6 月 標準化了嗎？它叫做 QUERY，而且它解決了一個開發者已經繞路處理了 16 年的問題。

這是自 PATCH（2010）以來第一個新的標準 HTTP 方法。沒錯，你沒看錯：HTTP 動詞已經 16 年 沒有重大創新了。

`GET` 方法的問題

你想在後端建立一個端點來取得訂單資訊，並加入篩選條件。因為你是在取得資源，而且這也是 REST 規範，所以這個端點會使用 GET 方法。

你在 URL 上加上不同參數來篩選結果，只回傳符合搜尋條件的訂單：

GET /orders?select=surname,givenname,email&limit=10&match="email=*@example.*"

問題：

URL 有長度限制（通常最多 8000 字元）
參數會出現在記錄檔中（安全性問題）
無法做複雜查詢（進階篩選、SQL 查詢、JSONPath）
編碼正確性很麻煩

那改用 `POST` 呢？

為了處理 GET 請求的各種問題，你可能會改用 POST 請求：

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

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

問題：

POST 不是冪等的 → 如果網路中斷，你不能安全地重新送出同一個請求
沒有標準的 HTTP 快取機制
代理伺服器不知道能不能安全地拒絕或重試
每個框架都會實作自己的一套「安全 POST」系統

解決方案：`QUERY`

QUERY 給你兩全其美的好處：

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

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

優點：

沒有 URL 長度限制 – 請求本文可以包含不限大小的 SQL 查詢、JSONPath 或複雜篩選條件
冪等 – 執行這個請求 10 次 = 執行 1 次

什麼是冪等性？

如果一個操作被呼叫多次，產生的結果和呼叫一次相同，那它就是冪等的。

具體例子：

✅ GET /users/123（冪等）→ 呼叫 1 次 = 呼叫 10 次 = 相同資料

✅ QUERY /users（冪等）→ 重送 = 相同結果

❌ POST /users（非冪等）→ 呼叫 1 次建立 1 位使用者，呼叫 2 次就建立 2 位使用者

為什麼這很重要？ 如果網路中斷，你可以安全地重送，不會產生重複資料或資料損壞。

可快取 – 代理伺服器、CDN、瀏覽器都能快取回應（像 GET 一樣）
可在請求本文中傳資料 – 在本文送出複雜資料（像 POST 一樣），而不是放在 URL 裡
安全 – 絕不修改伺服器狀態（唯讀）
可安全重放 – 如果網路中斷，你可以有把握地重送請求
請求的 URI – 伺服器可以建立一個永久網址來重放同一個請求

請求的 URI 與結果的 URI

傳統 POST（結果的 URI）：
POST /orders → 200 OK

Content-Location: /results/xyz789
QUERY（請求的 URI）：
QUERY /orders → 200 OK

Location: /saved-queries/42
神奇之處：重放 /saved-queries/42 會以 更新後的資料 重新執行同一個 SQL/JSONPath 查詢。

具體來說：
# 之後...

GET /saved-queries/42

# → 伺服器重新執行原本的 SQL 查詢

# → 你會拿到最新結果

它的用途：

分享查詢（把連結寄給同事）
將搜尋加入書籤
快取查詢（不只是快取結果）
定期重放，而不需要每次都重新送出本文

多虧了 QUERY，我們終於能對複雜請求做出真正可用的 HTTP 快取。代理伺服器、CDN 和瀏覽器現在都能快取帶有請求本文的請求。這對效能來說非常重要。

我們也得到了 REST API 設計上的演進。與其寫成：

GET /api/users/active
GET /api/users/inactive
GET /api/users/premium

現在你可以：

QUERY /api/users

只要一個端點，就更容易維護、保護和監控。

總結：GET vs POST vs QUERY

功能	GET	POST	QUERY
安全	✅ 是	❌ 否	✅ 是
冪等	✅ 是	❌ 否	✅ 是
允許本文	❌ 否	✅ 是	✅ 是
可快取	✅ 是	⚠️ 複雜	✅ 是
可安全重放	✅ 是	❌ 有風險	✅ 是
請求的 URI	✅ 預設	❌ 否	✅ 可選