Самописные регулярные выражения и наивные конструкции вроде split('/') часто ломаются при встрече с учетными данными basic-auth, явными портами, процентно-кодированными слэшами (%2F), составными публичными суффиксами вроде .co.uk или вопросительными знаками внутри хэш-фрагментов. Парсер, следующий спецификации, сканирует разделители в строгом синтаксическом порядке перед декодированием отдельных компонентов.
Рассмотрим сложный URL доставки вебхука, содержащий учетные данные, многоуровневый поддомен, нестандартный TLS-порт, закодированный сегмент пути, параметры запроса и хэш-якорь:
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"
}
Модификация компонентов без повреждения экранирования
При отладке между окружениями часто требуется перенаправить перехваченный production- или staging-коллбэк на локальный сервис, сохранив точное кодирование пути и подписанные полезные нагрузки в query. Изменение scheme на http, hostname на localhost, port на 3000 и очистка username/password чисто реконструирует адрес:
http://localhost:3000/v2/orgs/acme%20corp/webhooks?event=push&active=true#delivery-log
Обратите внимание, что третий сегмент пути (acme corp) автоматически сохраняет свое процентное кодирование %20 внутри pathname, предотвращая обрезку по пробелу в строках HTTP-запросов или логах Markdown.