現代 REST 介面、基於 GET 的 GraphQL 查詢以及 Webhook 回呼端點經常將多值陣列、巢狀篩選物件、Base64 分頁游標以及經過 URL 編碼的搜尋字詞打包進單一查詢字串或 application/x-www-form-urlencoded 請求主體中。若直接將這些負載當作扁平的原始字串進行人工檢視或修改,極易造成損壞的 %26 跳脫字元或括號不對稱。
以下方這個綜合性的 API 搜尋查詢為例,其中同時包含 + 編碼的空白、重複鍵名、巢狀方括號篩選條件、帶有百分比編碼 = 填充字元的 Base64 分頁游標,以及一個無值的純旗標參數:
?q=distributed+tracing&tag=otel&tag=grpc&filter[status]=open&filter[priority]=high&cursor=eyJpZCI6NDIwfQ%3D%3D&dry_run
解析此字串後,即可產生清晰易讀、結構嚴謹的 JSON 表示法:
{
"q": "distributed tracing",
"tag": [
"otel",
"grpc"
],
"filter": {
"status": "open",
"priority": "high"
},
"cursor": "eyJpZCI6NDIwfQ==",
"dry_run": ""
}
為什麼必須在百分比解碼之前拆分分隔符號
請注意 cursor=eyJpZCI6NDIwfQ%3D%3D 是如何被準確還原為 "eyJpZCI6NDIwfQ==" 的。合規的解析器會先依 & 拆分原始字串,再依第一個字面值 = 切分每個鍵值對,最後才對鍵與值分別執行 + 與 %XX 序列解碼。如果撰寫腳本時錯誤地先對整條查詢字串呼叫 decodeURIComponent(),再依 & 與 = 拆分,那麼任何包含跳脫 & 符號(R%26D -> R&D)的參數值都會被錯誤地截斷成兩個無效參數。
由於 JSON 檢視與互動式鍵值表格保持即時雙向同步,你也可以直接將應用程式碼中的 JSON 篩選物件貼入,立即序列化為跳脫完備、可直接用於 HTTP 請求的查詢字串。