使用 Query String Parser 時，可選擇 query-to-JSON 或 JSON-to-query，貼上查詢元件或扁平 JSON 物件，執行轉換，檢查重複或空值，並針對接收 API 驗證複製的結果。Query String Parser 可在瀏覽器中雙向處理：將 application/x-www-form-urlencoded 查詢元件轉為易讀的 JSON，或從刻意受限的扁平 JSON 物件建立查詢元件。解析時，它接受含有或不含開頭問號的文字、解碼百分比跳脫序列、將加號視為空格、保留空值，並依出現順序將重複名稱轉為陣列。建立時，它接受字串、有限 JSON 數值、布林值、null，以及上述純量值的陣列；它會拒絕巢狀物件和巢狀陣列，而非猜測其巢狀格式。產生的結果不包含開頭問號，因此可將其放入 URL、請求本文、日誌測試資料或測試中。它是轉換與檢查輔助工具，並非完整的 URL 驗證器，也不能保證每個伺服器都以相同方式處理重複值、null 或參數順序。
選擇正確的轉換方向
首先決定轉換的哪一方是你需要的。Query-to-JSON 用於檢查查詢元件中已攜帶的參數。JSON-to-query 用於從結構化輸入建立編碼參數。請勿對任意 JSON 文件使用 JSON-to-query，因為可接受的物件刻意設計為扁平格式，其值必須遵循已定義的純量規則。
| 模式 | 輸入 | 輸出 | 主要限制 |
|---|---|---|---|
| Query-to-JSON | 含有或不含開頭問號的查詢元件 | 易讀且已解碼的 JSON | 不會為解析出的文字推斷數值類型 |
| JSON-to-query | 扁平 JSON 物件 | 不含開頭問號的編碼查詢元件 | 拒絕巢狀資料；省略空陣列 |
查詢元件包含的是參數文字，而非完整的網址。對於一般 URL，請隔離問號之後、片段之前的文字。Query-to-JSON 接受開頭可選的問號，但產生的查詢輸出絕不包含問號。因此，將結果插入較大的 URL 時，可以自行加入適當的分隔符號。
使用 Query String Parser 轉換資料
- 選擇方向。檢查現有元件時，選擇 query-to-JSON；從扁平物件建立元件時，選擇 JSON-to-query。
- 貼上支援的輸入並執行轉換。對於 query-to-JSON，只貼上查詢元件。對於 JSON-to-query，請使用包含可接受純量值或這些純量之陣列的扁平物件。貼上的輸入不得超過 200,000 個字元的限制。
- 檢查結構與編碼。檢查重複名稱、單次出現、空值、null 序列化、保留字元和 Unicode 跳脫序列。確認所有陣列都只包含所選方向允許的值。
- 複製並驗證結果。只有在依照接收 API 對重複值、null、類型及省略值的規則進行檢查後，才可將輸出用於預期的 URL、請求本文、測試資料或測試。
依此順序執行，可讓轉換規則在資料送入應用程式之前清楚可見，也能避免將完整 URL、簽章網址或不支援的巢狀物件誤認為單純的查詢元件轉換。
讀取重複值、空值和編碼值
最重要的輸出判斷依據，是每個參數名稱出現一次或多次。單次出現的值會保留為 JSON 字串，而重複名稱則依出現順序轉為陣列。例如，tag=a&tag=b 會產生包含 a 和 b 的 JSON 陣列，而 tag=a 則會保留為字串 a。解析器不會執行類型推斷，因此 page=2 會變成 JSON 字串 "2"，而不是 JSON 數值。
| 輸入或情況 | 已定義的行為 |
|---|---|
| 重複的參數名稱 | 每次出現的值都會依出現順序保留在陣列中。 |
| 參數只出現一次 | 值會保留為字串，維持來源中單次與重複出現的區別。 |
| name= | 空值會保留，而不是捨棄。 |
| 使用加號表示空格 | Query-to-JSON 會將其視為空格；產生的查詢資料會將空格序列化為加號。 |
| 加號字面值 | 產生的值會將其編碼為 %2B，避免與空格混淆。 |
| 值內含 ampersands、等號及其他保留字元 | 這些字元會經過百分比編碼，而不會作為參數分隔符號。 |
| Unicode 字元 | 這些字元會透過 UTF-8 百分比編碼表示。 |
| 可選的開頭問號 | Query-to-JSON 會接受問號，但產生的查詢輸出會在沒有問號的情況下傳回。 |
這些規則遵循與瀏覽器相容的 URLSearchParams 模型。MDN URLSearchParams 參考資料與 WHATWG URL 標準 說明其底層解析及 application/x-www-form-urlencoded 序列化行為。
從扁平 JSON 建立查詢字串
對於 JSON-to-query，請從單一 JSON 物件開始，其值必須是可接受的純量，或可接受純量的一維陣列。例如 {"page":"2","active":true,"note":null,"tag":["a","b"]} 的物件可呈現支援的格式，而不引入巢狀結構。
- 字串會變成經過編碼的表單值。
- 有限 JSON 數值會變成其文字形式。
- 布林值會變成文字 true 或 false。
- null會變成空的參數值。
- 純量陣列會依陣列順序變成重複的參數出現值。
- 空陣列會被省略，因為其中沒有可附加的值。
巢狀物件和巢狀陣列會遭到拒絕。查詢字串沒有通用的巢狀資料表示法：括號名稱、點分隔名稱、索引名稱和內嵌 JSON 都是彼此競爭的慣例。因此，自動扁平化巢狀物件，可能產生看似有效、卻向接收端傳達不同含義的資料。
資料透過網路傳輸時，類型差異也會縮小。解析出的查詢值會保留為文字，因為查詢格式不會宣告 JSON 類型。同樣地，JSON 數值會序列化為文字，但接收框架可能會套用特定結構描述的強制轉換。請勿期待解析器自動將看似數值的字串轉換為數值。
區分查詢元件與完整 URL
Query String Parser 不會驗證完整 URL、主機名稱、路徑、片段、簽章或授權政策。如果貼上完整 URL，其路徑可能會被誤認為參數名稱的一部分。需要驗證 URL 元件時，請先使用 URL Parser 隔離網址，再只將其查詢元件傳入 Query String Parser。
排序或重新建立查詢參數，也可能使簽章 URL 失效或變更快取索引鍵。簽章可能涵蓋參數順序、重複出現值、百分比跳脫序列的寫法，以及加號與 %20 之間的選擇。如果不知道正規化規則，請保留原始序列化位元組。當通訊協定定義正規順序或簽章演算法時，請使用該協定的官方編碼器，而非依賴一般用途的轉換工具。指南 如何解析查詢參數而不破壞簽章 會針對這項限制提供簡明說明。
注意輸入限制與隱私邊界
目前工具將處理範圍限制為貼上的 200,000 個字元。較大的輸入超出支援的工作限制，因此只有在不會改變參數順序、重複出現值或其他對通訊協定敏感的細節時，才可拆分工作。
轉換與寫入剪貼簿的作業都留在瀏覽器中。不會上傳任何查詢文字、JSON、權杖、識別資訊或 URL。不過，在本機處理並不會使敏感的 URL 資料變得無害：瀏覽器、歷史記錄系統、分析工具、Proxy、referrer 和伺服器日誌可能會保留查詢字串。請避免將機密資訊放在 URL 中，並在分享轉換後的輸出前，遮蔽識別資訊或其他敏感值。
整合前診斷不相符情況
如果轉換結果看似正確，但接收應用程式的行為卻不同，請將其預期與解析器的明確規則進行比較，而不是任意變更值。
- 類型不相符：查詢值，例如 2，會保留為 JSON 字串 "2"。請確認伺服器是否會依結構描述進行強制轉換。
- 重複值不相符：工具會保留每次出現的值，但框架可能會保留第一個值、最後一個值、一律建立陣列，或拆分以逗號分隔的內容。
- 空值不相符：解析出的空值會保留，建立時 null 會變成空值，空陣列則會被省略。請針對接收端檢查每項規則。
- 巢狀結構不相符：請使用應用程式要求的確切括號、點分隔、索引或內嵌 JSON 格式，不要讓解析器自行猜測。
- 簽章不相符：需要正規化時，請保留原始查詢位元組，或使用該通訊協定的官方編碼器。
可靠的結果來自讓轉換的兩方一致：工具的 form-urlencoded 規則，以及接收應用程式有文件記載的契約。在將輸出用於正式環境資料前，請先驗證重複名稱、空值、純量處理方式與參數順序。