在 JavaScript 中，查詢字串是網址中問號之後的文字，依照 WHATWG URL Standard 所規定的 application/x-www-form-urlencoded 規則進行編碼，並透過瀏覽器的 URLSearchParams 介面提供給腳本;解析它意味著將該文字轉換成結構化的物件，你可以讀取它，或將其重新組合成新的查詢字串。遵循這些規則的解析器會解碼百分比跳脫序列、將加號視為空格、保留空值，並將重複鍵的每一次出現保留為有序陣列，而不是靜默地覆寫先前的值。由於查詢字串內部的巢狀資料並沒有一致的通用慣例，最安全的解析器會在重建端拒絕巢狀 JSON，並且只接受扁平純量或扁平純量陣列。同一份來源契約同時驅動兩個方向的轉換，這就是為什麼單一用途的解析器能夠取代手寫的 split-and-decode 例程，因為後者往往會偏離規格、錯誤處理 Unicode，或是在參數重複時當機。
JavaScript 查詢字串的結構
查詢字串是網址中問號之後的所有內容，由以 & 號連接的 name=value 配對組成。在 JavaScript 中，你通常會在 window.location.search、fetch 的第二個參數，或是 application/x-www-form-urlencoded POST 的主體中遇到它。解析意味著將那段扁平的文字轉換成你可以檢查、記錄、重播，或餵給另一個函式的結構化形狀。
瀏覽器為此工作提供了 URLSearchParams，而該物件是任何聲稱遵循 WHATWG URL Standard 的工具背後的參考實作。手動以 & 號與等號分割對於簡單輸入有效，但很快就會出錯:它忽略百分比跳脫序列、錯誤處理加號、捨棄重複的鍵，並且當值包含 & 號、等號或非 ASCII 字元時會無聲地損壞。遵循規格的路徑正是 Query String Parser 工具所執行的，因此你在分頁中看到的結果會與在主控台中執行 new URLSearchParams(text) 所產生的結果一致。當手動解析成為 CI 管線的一部分時，同樣的邊角情況會出現在測試固件和正式流量中，這就是為什麼將工作卸載給一個具確定性的解析器，通常比維護一套私有的正則表達式更划算。
該工具所遵循的雙向工作流程
該工具接受兩個方向的工作，兩者皆錨定於 WHATWG 與 MDN 的規則。行為是固定的:要遵循的只有一份規格，而不是好幾個相互競爭的慣例。
| 方向 | 接受 | 拒絕或標記 |
|---|---|---|
| 查詢字串轉 JSON | 可選擇性包含前導問號的文字、百分比跳脫序列、加號、重複名稱、空值、缺少等號、UTF-8 位元組 | 其路徑可能會被誤認為參數名的完整網址;請先使用 URL Parser |
| JSON 轉查詢字串 | 值為字串、有限數字、布林值、null，或是這些純量之陣列的扁平物件 | 巢狀物件、巢狀陣列，以及空陣列(在編碼時省略，因為沒有內容可附加) |
正是這份單一契約，使得一個圍繞 URLSearchParams 打造的解析器能夠取代典型程式碼集中半打一次性正則表達式。當接收端服務有不同的慣例，例如它會將單一值以逗號分割，或總是輸出陣列，那是一種伺服器端的慣例而非解析錯誤，並且必須在轉換器將結構化資料交給你之後再行處理。
逐步將查詢字串解析為 JSON
這是多數開發者在想要檢查或記錄一組 URL 參數時會採用的方向。Query String Parser 遵循與瀏覽器相同的解碼規則，因此你在分頁中看到的結果與你的程式碼在執行階段所見到的結果一致。
- 複製查詢元件。如果你有完整的網址，請僅在你明確希望該工具將路徑視為資料時才貼上;否則請自行取出第一個問號之後、任何雜湊片段之前的內容。該工具容許前導問號並會將其去除，因此 ?tag=a&tag=b 與 tag=a&tag=b 會產生相同的 JSON。
- 開啟 Query String Parser，並選擇「查詢轉 JSON」方向。
- 將查詢文字貼入輸入欄位，然後執行轉換。
- 檢查 JSON 輸出。首先確認兩件事:任何在輸入中出現超過一次的鍵，現在應該以出現順序排列為一個 JSON 陣列;而任何值為等號後面沒有內容 (key=) 的項目，應該是空字串，而非 null 也不是缺失。
- 複製 JSON 並對照接收系統進行驗證。如果你的 API 僅保留重複鍵的最後一個值，該工具交給你的陣列將會不相符。請改用該 API 文件所記載的伺服器慣例，或是改為送出兩個請求。
若要進行快速的健全性檢查，WHATWG URL Standard 與 MDN 的 URLSearchParams 參考文件記載了相同的行為，因此該工具所產生的任何結果都應該可以在你的主控台中以一行指令重現。
逐步從扁平 JSON 物件建構查詢字串
當你需要建構 API 呼叫、日誌固件或測試主體時，反向方向正是你會採用的方向。形狀刻意受限，因為該工具拒絕猜測巢狀資料應如何扁平化。
- 組成一個扁平的 JSON 物件。鍵必須是字串;值必須是字串、有限數字、布林值、null，或是這些純量所組成的陣列。文字 "2" 必須保持為字串，因為該工具不會執行型別推論;線上格式承載的是文字，而非數值型別宣告。
- 開啟 Query String Parser，並選擇「JSON 轉查詢字串」方向。
- 貼上 JSON 物件，然後執行轉換。
- 檢查編碼後的輸出。空格會變成加號、字面上的加號會變成 %2B、諸如 & 號與等號等保留字元只有在出現在值內部時才會被百分比編碼，而 Unicode 文字則會透過 UTF-8 百分比編碼進行往返處理。
- 複製結果並對照 API 契約進行驗證。null 會變成空值 (key=)，空陣列會被捨棄，因為它們沒有內容可附加;而單一元素的陣列會被保留為一次出現，而不是被升格為字串的重複項目。
規格已為你解決的邊角情況
這些行為屬於契約的一部分，並非可有可無，也是手寫解析器傾向在正式環境中損壞的原因。預先了解它們，正是讓你能夠完全跳過撰寫解析器的關鍵。
| 面向 | 該工具的處理方式 |
|---|---|
| 前導問號 | 於查詢轉 JSON 中為選擇性，在解析前會被去除 |
| 值中的加號 | 讀取時解碼為空格 |
| 作為資料的字面加號 | 必須以 %2B 的形式出現於來源文字中 |
| 空值 (key=) | 保留為空字串，而不會被捨棄 |
| 重複的鍵 | 變成一個有序的 JSON 陣列 |
| 值中的 Unicode | 透過 UTF-8 百分比編碼進行往返處理 |
| 值內部的 & 號或等號 | 進行百分比編碼，而不會被視為分隔符 |
| 諸如 2 等類數字文字 | 保持為 JSON 字串，不執行型別推論 |
類數字文字這一列是最讓人感到意外的部分。查詢格式是文字，因此整數 2 與字串 "2" 在線上是無法區分的;該工具會保留較安全的字串形式，以便下游程式碼自行決定是否要加以強制轉型。如果你的伺服器將 ID 儲存為整數，並且需要以該形式解析回來，請在消費 JSON 的應用程式碼中進行該強制轉型，而不是在解析器中。
何時不應重新編碼:簽章與快取鍵
如果你正在解析的網址或主體帶有簽章、OAuth state 值，或是相依於參數順序的快取鍵，請勿讓該工具將位元組往返處理回查詢字串。重新排序、plus 加號與 %20 之間的選擇，以及百分比跳脫的確切拼法，都可能落在簽章演算法的涵蓋範圍之內。在簽署協定未記載正規化規則時，請保留原始的序列化位元組;若協定確有記載，則使用該協定本身的編碼器。
WHATWG 與 MDN 的行為會產生一個有效且可互通的查詢字串，但「有效」與「此已簽署端點的正規形式」並非同一件事。同樣的注意事項也適用於對原始查詢字串進行雜湊以建立快取的 API 閘道:單一重新編碼後的空格或重新排序的參數，都可能使快取鍵位移，讓快取回應變成快取未命中。請將 Query String Parser 視為除錯器與建構器，而非正規化器;在確認接收系統接受之前，請同時保留一份原始文字與任何往返處理後的輸出。
為何在本地處理查詢資料很重要
查詢字串的洩漏性特別高:搜尋紀錄、來源標頭、伺服器紀錄、分析管線，以及企業代理伺服器都看得到它們。轉換本身是在瀏覽器中執行，不會上傳任何東西，但你貼到工具中的文字仍然帶有你在聊天或截圖時通常不會分享的識別資訊。請在貼上之前先遮罩工作階段權杖、電子郵件地址，以及追蹤參數;當數值較為敏感時，請在 URL 所在的那個分頁中執行 Query String Parser。
目前分頁的工作量上限為 200,000 字元，這對於一般的搜尋、分析與表單承載量已綽綽有餘，但對嘗試貼上深度巢狀已簽署請求的人來說，這是一個實際的天花板。當此上限成為問題時，請將工作拆成較小的片段，或是改用該協定本身的編碼器，而非通用轉換器。
若想更深入了解，請參閱 JavaScript 權杖的正則表達式速查表 API 替代方案。
若想更深入了解，請參閱 在 Python 中解析網址並對照瀏覽器進行驗證。