URL и URLSearchParams в JavaScript: парсинг URL

Хватит парсить URL строковыми трюками

До появления API URL все резали адреса через split('?'), регулярки и молитвы. Работало — ровно до того момента, пока в значении не появлялся &, =, пробел или какой-нибудь не-ASCII символ. И тут всё разваливалось. И в браузере, и в Node есть нормальный парсер. Пользуйтесь им.

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

Один вызов — и весь URL уже разобран на части и корректно декодирован. При невалидном вводе конструктор бросает TypeError, и это как раз то, что нужно в большинстве случаев: мусорный URL должен падать громко, а не тихо протаскивать мусор дальше по коду.

Как получить query-параметры из URL

У каждого объекта URL есть свойство .searchParams — это объект URLSearchParams, который умеет читать и изменять query string:

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

Несколько моментов, на которые стоит обратить внимание:

• Значения возвращаются уже декодированными. ?name=Ada%20Lovelace превратится в "Ada Lovelace".
• Всё — это строка. "2" — это не 2. Если нужно число, преобразуйте через Number().
• Повторяющиеся ключи — это нормально. get вернёт первое совпадение, а getAll — все.
• Для отсутствующих ключей возвращается null, а не undefined — так что ?? "default" отлично с ними работает.

Как собрать query string в JavaScript

Собрать query-строку с нуля можно через URLSearchParams — без ручного экранирования и склейки через &:

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

А ещё его можно собрать из объекта — подойдёт любой итерируемый набор пар [ключ, значение], да и обычный объект тоже сгодится:

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set и append: set перезаписывает уже существующее значение по этому ключу, а append добавляет ещё одно. append удобно использовать, когда ключ может законно повторяться (теги, фильтры); set — для параметров с единственным значением.

Как изменить URL

Объект URL живой, поэтому любые изменения в searchParams автоматически отражаются в .search и .href:

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // перезаписывает
u.searchParams.delete("utm_source");       // ничего не делает, если отсутствует

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

Это идиоматичный способ добавить query-параметр к уже существующему URL. Не нужно проверять, есть ли в URL знак ?, и ломать голову над тем, ставить & или ?.

Точно так же можно менять и другие части URL:

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

Перебор параметров

URLSearchParams — это итерируемый объект. for...of выдаёт пары [key, value], а ещё есть привычные помощники keys(), values() и entries():

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

Учти, что повторяющиеся ключи попадают в итерацию отдельными записями — сначала увидишь tag = web, затем tag = beginner. Это честное отражение того, что реально лежит в query-строке.

Если нужно по-быстрому вывести всё как обычный объект для отладки, подойдёт Object.fromEntries — правда, он схлопывает дубликаты и оставляет только последнее значение:

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

Пригодится для отладки. Но если какой-то ключ может повторяться — это уже неверный подход.

Относительные URL требуют базы

Вызов new URL("/search?q=js") сам по себе выбросит исключение — относительный путь без базы не является валидным URL. Передайте базовый адрес вторым аргументом:

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

Правила разрешения здесь те же, что браузер применяет к <a href>: ведущий / — это абсолютный путь от хоста, без слеша — относительно текущего пути, .. поднимается на уровень выше. Очень удобно, когда вы собираете URL к API из заранее заданной базы.

В браузере window.location.href — это готовая база для парсинга URL текущей страницы:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Обработка невалидных URL

Конструктор URL бросает исключение на некорректных данных. С одной стороны, это удобно, с другой — значит, что при парсинге URL в JavaScript нужно оборачивать в try/catch всё, что ввёл пользователь или прислала внешняя система:

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // объект URL
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

В современных средах также доступен метод URL.canParse(input) — булева проверка, которая избавляет от плясок с try/catch, когда нужно просто провалидировать URL:

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

Небольшой рабочий пример

Соберём всё вместе: прочитаем текущие фильтры из URL, немного их подправим и получим новый URL, на который можно перейти:

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

Передача null удаляет параметр. Любое другое значение устанавливает или перезаписывает его. Этот паттерн вы так или иначе будете писать каждый раз, когда делаете фильтры, пагинацию или диплинки.

Что стоит запомнить

• new URL(string) разбирает URL на именованные части. На мусоре кидает исключение.
• url.searchParams — это URLSearchParams, у него есть get, getAll, set, append, delete, has.
• Кодирование происходит автоматически. Не лезьте за encodeURIComponent, если только не собираете строку руками.
• Передавайте базовый URL вторым аргументом, чтобы разрешить относительные пути.
• URL.canParse (или try/catch) — ваш инструмент валидации для недоверенного ввода.

Каждый раз, когда рука тянется разбить URL через .split('?') или выдернуть query-параметр регуляркой, берите вместо этого встроенные API. Код короче, работает корректно, и всё это уже есть в рантайме.