URL: структура и компоненты

URL (Uniform Resource Locator) — стандартизированная строка для адресации ресурсов в сети, состоящая из нескольких обязательных и необязательных компонентов.

Зачем нужно

Понимание структуры URL необходимо для корректного формирования запросов, парсинга ссылок, редиректов и проектирования маршрутов. Работа с URL API позволяет безопасно собирать и разбирать URL в JavaScript без ручной конкатенации строк.

Где используется

  • Маршрутизация в Express, React Router, Next.js
  • Парсинг входящих запросов на сервере (req.url, req.query)
  • Формирование ссылок с query-параметрами в клиентском коде
  • Редиректы, канонические URL, SEO

Анатомия URL

https://user:pass@api.example.com:8080/api/v1/users?role=admin&page=2#results
|_____|  |_______|  |_____________| |__| |_________|  |_____________| |_____|
scheme  credentials    hostname     port    pathname     search/query  fragment

scheme   = https
username = user
password = pass
hostname = api.example.com
port     = 8080
pathname = /api/v1/users
search   = ?role=admin&page=2
hash     = #results

URL API в JavaScript

// Парсинг URL
const url = new URL('https://api.example.com/users?page=2&role=admin#list');

console.log(url.protocol);  // 'https:'
console.log(url.hostname);  // 'api.example.com'
console.log(url.port);      // '' (дефолтный 443 — не указывается)
console.log(url.pathname);  // '/users'
console.log(url.search);    // '?page=2&role=admin'
console.log(url.hash);      // '#list'

// URLSearchParams — работа с query-параметрами
const params = url.searchParams;
console.log(params.get('page'));     // '2'
console.log(params.get('role'));     // 'admin'
console.log(params.has('token'));    // false

// Изменение
url.pathname = '/products';
params.set('page', '3');
params.append('sort', '-price');
params.delete('role');
console.log(url.toString());
// 'https://api.example.com/products?page=3&sort=-price#list'

Безопасное формирование URL с параметрами

// Небезопасно — ручная конкатенация
const unsafe = `/api/search?q=${query}&page=${page}`; // XSS при специальных символах

// Безопасно — URL API кодирует значения автоматически
function buildUrl(base, params) {
  const url = new URL(base);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== null && value !== undefined) {
      url.searchParams.set(key, value);
    }
  });
  return url.toString();
}

const searchUrl = buildUrl('https://api.example.com/search', {
  q: 'ноутбук & планшет',  // специальные символы закодируются
  page: 1,
  limit: 20,
});
// 'https://api.example.com/search?q=%D0%BD%D0%BE%D1%83%D1%82%D0%B1%D1%83%D0%BA+%26+%D0%BF%D0%BB%D0%B0%D0%BD%D1%88%D0%B5%D1%82&page=1&limit=20'

Относительные URL

// Разрешение относительного URL относительно base
const base = new URL('https://example.com/docs/api/');
const relative = new URL('../images/logo.png', base);
console.log(relative.href); // 'https://example.com/docs/images/logo.png'

// В Node.js для resolve путей в файловой системе
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);

Частые ошибки

  • Конкатенация URL строками вместо URL API — не кодируются спецсимволы
  • Путаница pathname и полного URL — url.pathname не включает host
  • Дублирование ? при ручной сборке: url + '?' + params если search уже есть
  • Хранение чувствительных данных (токенов) в URL — видны в логах и браузере

Связанные темы

Ресурсы