當遇到包含 Basic Auth 驗證憑證、明確指定的連接埠、百分比編碼斜線 (%2F)、多層公共後綴(如 .co.uk)或雜湊片段內嵌問號的複雜網址時,手寫正規表示式與簡單的 split('/') 輔助函式經常會失效。符合規範的解析器會嚴格按照語法優先順序掃描分隔符號,接著才對個別組件進行解碼。
以下列包含驗證憑證、多層子網域、非預設 TLS 連接埠、編碼路徑區段、查詢參數與片段錨點的複雜 Webhook 傳遞 URL 為例:
https://deploy:tok_9f8a@staging.api.example.co.uk:8443/v2/orgs/acme%20corp/webhooks?event=push&active=true#delivery-log
拆解此 URI 後,會產生各自獨立且可單獨編輯的屬性:
{
"href": "https://deploy:tok_9f8a@staging.api.example.co.uk:8443/v2/orgs/acme%20corp/webhooks?event=push&active=true#delivery-log",
"protocol": "https:",
"scheme": "https",
"username": "deploy",
"password": "tok_9f8a",
"origin": "https://staging.api.example.co.uk:8443",
"host": "staging.api.example.co.uk:8443",
"hostname": "staging.api.example.co.uk",
"subdomain": "staging.api",
"domain": "example.co.uk",
"tld": "co.uk",
"port": "8443",
"pathname": "/v2/orgs/acme%20corp/webhooks",
"pathSegments": ["v2", "orgs", "acme corp", "webhooks"],
"search": "?event=push&active=true",
"queryParams": {
"event": "push",
"active": "true"
},
"hash": "#delivery-log"
}
修改組件而不損壞跳脫序列
在跨環境除錯時,我們常需要將擷取到的正式機或測試機回呼 URL 指向本機服務,同時保留完整的路徑編碼與已簽章的查詢負載 (Payload)。只要將 scheme 改為 http、hostname 改為 localhost、port 改為 3000,並清除 username/password,即可乾淨地重組出:
http://localhost:3000/v2/orgs/acme%20corp/webhooks?event=push&active=true#delivery-log
請注意,第三個路徑區段 (acme corp) 在 pathname 內部會自動保留其 %20 百分比編碼,避免在 HTTP 請求行或 Markdown 日誌中因為空白字元而導致網址截斷。