Свой маршрутизатор: сегменты, параметры, строка запроса, 404 и 405

Из разборщика запрос выходит с полем target — куском текста из стартовой строки; node:http кладёт его же в req.url. Маршрутизатору нужно из него две вещи: путь, по которому ищут обработчик, и строка запроса, которая поедет к обработчику отдельно. Делит их первый ? — и только первый: в пути вопросительный знак невозможен, там он обязан быть записан как %3F, а значит, все следующие принадлежат уже строке запроса.

Сегменты пути даёт split("/"). Прогноз: сколько сегментов окажется у /notes/ и у / — и что выйдет из цели *?

// RAW, parseHead и RequestParser — в подложке
const parser = new RequestParser();
parser.onRequest = (request) => console.log(`разборщик отдал: метод «${request.method}», цель «${request.target}»`);
parser.feed(RAW);

// Первый «?» делит цель надвое; все следующие принадлежат строке запроса
function splitTarget(target) {
  const mark = target.indexOf("?");
  return mark === -1
    ? { pathname: target, search: "" }
    : { pathname: target.slice(0, mark), search: target.slice(mark + 1) };
}

for (const target of ["/notes", "/notes/17", "/notes/", "/", "/notes?tag=a?b", "*"]) {
  const { pathname, search } = splitTarget(target);
  const segments = pathname.split("/").slice(1);
  console.log(`${target} → путь «${pathname}», запрос «${search}», сегменты ${JSON.stringify(segments)}`);
}

Слэш в начале пути есть всегда, поэтому первый кусок после split — пустая строка; её и снимает slice(1). Слэш в конце такой заботы не получает: у /notes/ сегментов два, и второй пустой — для маршрутизатора /notes и /notes/ разные пути, и это решение придётся принять сознательно (задача в конце статьи как раз о нём). У корня / сегмент один, и он тоже пустой. А у цели * сегментов нет вовсе: это не путь, а особая форма записи — так спрашивают OPTIONS * HTTP/1.1, «что вообще умеет сервер». Отсюда простое правило перед всяким сопоставлением: цель, не начинающаяся со слэша, — не адрес вашего приложения.

Вторая половина цели в выборе обработчика не участвует вовсе: /notes, /notes?page=2 и /notes?page=3 — один адрес и один обработчик. Это не упрощение, а договор: путь отвечает на вопрос «что», строка запроса — «какое именно», и как только выбор обработчика начнёт зависеть от параметра, ваш сервер перестанут понимать и кеши, и журналы, и вы сами через полгода.

Имя req.url историческое: настоящего URL — со схемой и хостом — в нём нет и не было, там лежит ровно то, что клиент написал в стартовой строке.

Маршрут — это метод, шаблон пути и обработчик. Шаблон пишут той же строкой, что и адрес, только переменные места отмечают двоеточием: /notes/:id. Сравнивать шаблон с путём целиком бессмысленно — на этом и сломался браузерный маршрутизатор части IV, где строки сверялись как есть и /tasks/42 в списке не находился. А посегментно — легко: длины должны совпасть, буквальные сегменты — совпасть точно, а сегмент с двоеточием забирает что угодно и кладёт добычу в params. Переменный сегмент вы уже собирали — там он был папкой со скобками в имени, а спор «буква или скобки» решался порядком двух проверок. Дерева здесь нет — есть плоский список маршрутов, и спор за сегмент он разрешает иначе; к этому мы вернёмся, когда список появится.

Прогноз: какие из пяти путей подойдут шаблону /notes/:id/comments?

// Шаблон разбирается один раз, при объявлении маршрута: «/notes/:id» → ["notes", ":id"]
const pattern = "/notes/:id/comments".split("/").slice(1);

// Переменный сегмент забирает что угодно, кроме пустоты; остальные должны совпасть посимвольно
function matchRoute(parts, segments) {
  if (parts.length !== segments.length) return null;
  const params = {};
  for (let i = 0; i < parts.length; i += 1) {
    if (parts[i].startsWith(":")) {
      if (segments[i] === "") return null;
      params[parts[i].slice(1)] = segments[i];
      continue;
    }
    if (parts[i] !== segments[i]) return null;
  }
  return params;
}

for (const pathname of ["/notes/17/comments", "/notes/17", "/notes/17/comments/3", "/notes//comments", "/Notes/17/comments"]) {
  const params = matchRoute(pattern, pathname.split("/").slice(1));
  console.log(`${pathname} → ${params ? JSON.stringify(params) : "не подходит"}`);
}

Двоих отсекает длина: у /notes/17 сегментов меньше, у /notes/17/comments/3 больше. Третий, /notes//comments, по длине подошёл — и всё-таки отвергнут: сегмент пустой, а пустой id не идентификатор, а забытая переменная в коде клиента. Пропустить его — значит отдать обработчику params.id === "" и узнать об этом уже в запросе к базе. Четвёртый случай важнее всех: /Notes/17/comments не подошёл, потому что путь в HTTP чувствителен к регистру — в отличие от схемы и хоста, которые сравниваются без его учёта. Если вы хотите отвечать и на /Notes, это отдельное решение и отдельный код.

Стоит заметить, где именно шаблон превращается в массив сегментов. Разбирать его на каждом запросе незачем: маршрутов в приложении десятки, а запросов — тысячи, и шаблоны между ними не меняются. Поэтому строку режут один раз, при объявлении маршрута, а на запросе остаётся сравнение двух готовых массивов. Ровно так устроены и взрослые маршрутизаторы, только вместо массива у них дерево или скомпилированное регулярное выражение — механика поиска от этого не меняется, меняется цена одного сравнения.

Имя параметра становится ключом в params, и двух одинаковых имён в одном шаблоне быть не должно: второй :id молча затрёт первый.

Пока в адресах была одна латиница, всё сходилось. Но в путях бывают кириллица, пробелы и слэши внутри имён, а по проводу такое не ездит: RFC 3986 держит в адресе ограниченный набор символов, всё остальное записывается процентами. Кодирует клиент — fetch делает это молча и сам, — а декодировать вам. Прогноз: что окажется в req.url у адреса с кириллицей и куда денется #top?

// Что на самом деле доезжает до сервера в req.url: адрес с кириллицей, «/» внутри
// значения и фрагмент. Клиент — настоящий fetch, адреса он собирает сам.
import { createServer } from "node:http";

const server = createServer((req, res) => {
  const mark = req.url.indexOf("?");
  const pathname = mark === -1 ? req.url : req.url.slice(0, mark);
  const search = mark === -1 ? "" : req.url.slice(mark + 1);

  console.log(`  req.url: ${req.url}`);
  const afterSplit = pathname.split("/").slice(1).map((part) => decodeURIComponent(part));
  const beforeSplit = decodeURIComponent(pathname).split("/").slice(1);
  console.log(`  split, потом decodeURIComponent — сегментов ${afterSplit.length}: ${afterSplit.join(" | ")}`);
  console.log(`  decodeURIComponent, потом split — сегментов ${beforeSplit.length}: ${beforeSplit.join(" | ")}`);
  if (search !== "") {
    console.log(`  строка запроса: ${search}`);
    console.log(`  URLSearchParams: search = ${new URLSearchParams(search).get("search")}`);
  }
  res.end();
});

server.listen(0, "127.0.0.1", async () => {
  const { port } = server.address();
  const base = `http://127.0.0.1:${port}`;
  console.log(`сервер слушает ${base}`);
  for (const target of ["/время/Москва", "/files/a%2Fb", "/notes?search=кот и пёс#top"]) {
    console.log(`fetch просили о: ${target}`);
    await fetch(base + target);
  }
  server.close();
});

сервер слушает http://127.0.0.1:<порт>
fetch просили о: /время/Москва
  req.url: /%D0%B2%D1%80%D0%B5%D0%BC%D1%8F/%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0
  split, потом decodeURIComponent — сегментов 2: время | Москва
  decodeURIComponent, потом split — сегментов 2: время | Москва
fetch просили о: /files/a%2Fb
  req.url: /files/a%2Fb
  split, потом decodeURIComponent — сегментов 2: files | a/b
  decodeURIComponent, потом split — сегментов 3: files | a | b
fetch просили о: /notes?search=кот и пёс#top
  req.url: /notes?search=%D0%BA%D0%BE%D1%82%20%D0%B8%20%D0%BF%D1%91%D1%81
  split, потом decodeURIComponent — сегментов 1: notes
  decodeURIComponent, потом split — сегментов 1: notes
  строка запроса: search=%D0%BA%D0%BE%D1%82%20%D0%B8%20%D0%BF%D1%91%D1%81
  URLSearchParams: search = кот и пёс

Кириллица приезжает процентами — по три знака на байт, то есть по шесть на букву, — и оба порядка действий дают одно и то же: два сегмента, «время» и «Москва». А вот на втором адресе они расходятся. %2F — это код слэша, и если декодировать целый путь до split, слэш из значения станет настоящим разделителем: было имя a/b, стало два сегмента a и b. Клиент просил один файл со слэшем в имени, сервер услышал папку и файл в ней. Третий адрес показывает ещё две вещи: фрагмент #top до сервера не доехал вовсе — его отрезает клиент, и серверу он не отправляется никогда, — а строку запроса URLSearchParams разобрал сам, вернув пробелы пробелами.

Повторим оба порядка в песочнице и добавим то, что бывает, когда процент испорчен. Прогноз: что вернёт decodeURIComponent("%2") и что выйдет из пути /notes/%D0?

const pathname = "/files/a%2Fb";

// Два порядка одних и тех же действий — и два разных адреса
console.log(`decodeURIComponent, потом split: ${JSON.stringify(decodeURIComponent(pathname).split("/").slice(1))}`);
console.log(`split, потом decodeURIComponent: ${JSON.stringify(pathname.split("/").slice(1).map((part) => decodeURIComponent(part)))}`);
try {
  decodeURIComponent("%2");
} catch (err) {
  console.log(`decodeURIComponent("%2") → ${err.name}`);
}

// Сегменты пути: сначала разрезать по «/», потом декодировать каждый отдельно
function segmentsOf(pathname) {
  const parts = pathname.split("/").slice(1);
  try {
    return parts.map((part) => decodeURIComponent(part));
  } catch {
    // испорченный процент — это не «нет такого адреса», а «адрес не разобрать»
    return null;
  }
}

for (const path of ["/%D0%B7%D0%B0%D0%BC%D0%B5%D1%82%D0%BA%D0%B8/17", "/notes/a+b", "/notes/%D0"]) {
  const segments = segmentsOf(path);
  console.log(`${path} → ${segments ? segments.map((s) => `«${s}»`).join(" ") : "400: адрес не разобрать"}`);
}

Порядок «сначала разрезать, потом декодировать» — не стилистическая мелочь, а единственный правильный: после split разделители уже расставлены, и декодирование не может их добавить. Оба испорченных процента дают URIError: у %2 не хватает цифры, у %D0 цифр достаточно, но один этот байт не складывается в букву UTF-8. Ловить исключение обязательно, и отвечать на него надо 400, а не 404: «адрес не разобрать» — это не «такого адреса нет». Сравните с /notes/a+b: в пути плюс — обычный символ, декодирование его не трогает. В строке запроса тот же плюс значит пробел — это различие покажет следующий раздел.

Та же ловушка живёт и с другой стороны провода. Собирая адрес, кодировать надо каждое значение отдельно — encodeURIComponent для сегмента, а не encodeURI для целого пути: второй нарочно не трогает разделители, и слэш из имени файла уехал бы к серверу настоящим слэшем. Правило одно и то же в обе стороны: кодируют и декодируют значения, а не адреса.

Декодировать сегмент надо через decodeURIComponent, а не decodeURI: второй нарочно оставляет %2F и %3F как есть — он умеет разбирать целый адрес, а не его кусок.

Путь отвечает на вопрос «что», строка запроса — «какое именно»: страница, размер страницы, поиск, фильтры. Разбирать её руками не нужно: URLSearchParams есть и в браузере, и в Node, и проценты, плюсы вместо пробелов и повторы он уже умеет. С другой стороны провода вы собирали такую строку тем же классом — теперь разбираете. Прогноз: что вернёт get для повторённого tag и для параметра draft, записанного без знака равенства?

const query = new URLSearchParams("page=2&limit=999&search=%D0%BA%D0%BE%D1%82+%D0%B8+%D0%BF%D1%91%D1%81&tag=js&tag=node&draft");

console.log(`search: «${query.get("search")}»`);
console.log(`tag: get «${query.get("tag")}», getAll «${query.getAll("tag").join(" ")}»`);
console.log(`draft: get «${query.get("draft")}», has ${query.has("draft")}`);
console.log(`нет такого: get ${query.get("sort")}`);

Три вещи стоит запомнить сразу. Повтор не ошибка и не замена: get отдаёт первое значение, getAll — все, и выбор между ними делаете вы (у фильтра «тег» честнее getAll, у страницы — get). Параметр без значения — это пустая строка, а не отсутствие: has говорит true, get отдаёт "". И только у параметра, которого нет, get возвращает null. Разница между "" и null кажется схоластикой ровно до следующего примера.

Теперь то, ради чего строка запроса и нужна серверу: страница и её размер. Обязанностей здесь три — умолчание, проверка и потолок. Прогноз: во что превратятся limit= без значения, limit=12 котов и page=-3?

// Число с границы: значение пришло из адреса, и годным его делает проверка, а не Number
function toInt(value, fallback) {
  if (value === null || value.trim() === "") return fallback;
  const number = Number(value);
  return Number.isInteger(number) ? number : fallback;
}

function readList(search) {
  const query = new URLSearchParams(search);
  return {
    page: Math.max(1, toInt(query.get("page"), 1)),
    // потолок не про аккуратность: без него ?limit=1000000 — это «отдай всю таблицу»
    limit: Math.min(100, Math.max(1, toInt(query.get("limit"), 20))),
    search: (query.get("search") ?? "").trim(),
  };
}

for (const search of ["", "page=3&limit=5", "limit=999", "limit=", "limit=12 котов", "page=-3", "limit=10.5", "search=+кот+"]) {
  console.log(`«${search}» → ${JSON.stringify(readList(search))}`);
}

Функция toInt длиннее, чем хочется, и каждая её строка — про отдельную ловушку. Number("") — это ноль, а не NaN, поэтому ?limit= без проверки на пустоту дал бы предел в ноль строк и пустую страницу вместо умолчания. Number("12 котов") — NaN, а parseInt того же вернул бы 12, то есть сервер сделал бы вид, что понял написанное; на границе такое поведение дороже, чем кажется. Number.isInteger отсекает разом и NaN, и дробное 10.5. А потолок — не про аккуратность: без него ?limit=1000000 означает «отдай всю таблицу», и выполнит эту просьбу ваша база. Умолчание, проверка и потолок в одном месте — это и есть разбор границы; отдельная статья главы 6 соберёт из них общий механизм, который делает то же самое со всем входом сразу.

limit из строки запроса — то, что попросил клиент, а не то, что вы обязаны отдать. Ответ честнее, когда рядом с данными едет применённый предел: клиент попросил тысячу, получил сто и знает об этом.

Три куска готовы: цель делится на путь и строку запроса, путь — на сегменты, сегменты сопоставляются с шаблоном. Осталось сложить их в объект, который принимает маршруты и отвечает на запрос. И тут появляется различие, ради которого написана статья. Если путь не подошёл ни одному маршруту — это 404, «нет такого адреса». Если путь подошёл, а метод не тот — это 405, и вместе с ним обязателен заголовок Allow со списком методов, которые этот адрес умеет: RFC 9110 требует его именно у 405. Разница не косметическая. 404 говорит «такого не существует», 405 — «существует, но не так», и для клиента это разные новости: по первой он ищет опечатку в адресе, по второй — в своём коде.

Прогноз: сколько ответов из восьми будут 405 и что встанет в Allow у PUT /notes/17?

// RAW, разборщик, splitTarget, segmentsOf и matchRoute — в подложке
class Router {
  routes = [];

  add(method, pattern, handler) {
    // шаблон разбирается один раз, при объявлении, а не на каждом запросе
    this.routes.push({ method, parts: pattern.split("/").slice(1), handler });
  }

  find(method, target) {
    const { pathname, search } = splitTarget(target);
    const segments = segmentsOf(pathname);
    if (segments === null) return { status: 400 };
    const allowed = new Set();
    for (const route of this.routes) {
      const params = matchRoute(route.parts, segments);
      if (params === null) continue;
      // путь тот, а метод не тот: адрес существует, и молчать об этом нечестно
      if (route.method !== method) {
        allowed.add(route.method);
        continue;
      }
      return { handler: route.handler, params, query: new URLSearchParams(search) };
    }
    return allowed.size === 0 ? { status: 404 } : { status: 405, allow: [...allowed].join(", ") };
  }
}

const router = new Router();
router.add("GET", "/notes", (params, query) => `список, страница ${query.get("page") ?? 1}`);
router.add("POST", "/notes", () => "создана");
router.add("GET", "/notes/:id", (params) => `заметка ${params.id}`);
router.add("DELETE", "/notes/:id", (params) => `удалена ${params.id}`);
router.add("GET", "/files/:name", (params) => `файл ${params.name}`);

const requests = [
  ["GET", "/notes?page=3"],
  ["POST", "/notes"],
  ["GET", "/notes/17"],
  ["PUT", "/notes/17"],
  ["DELETE", "/notes"],
  ["GET", "/files/a%2Fb"],
  ["GET", "/notes/"],
  ["GET", "/%D0%B7%D0%B0%D0%BC%D0%B5%D1%82%D0%BA%D0%B8"],
];
for (const [method, target] of requests) {
  const found = router.find(method, target);
  const answer = found.handler
    ? `200 ${found.handler(found.params, found.query)}`
    : `${found.status}${found.allow ? ` Allow: ${found.allow}` : ""}`;
  console.log(`${method} ${target} → ${answer}`);
}

Маршрут ищется одним проходом по списку, и заодно в этом проходе копятся методы, которые подошли бы по пути: если ни одного обработчика не нашлось, а множество не пусто — это и есть 405. PUT /notes/17 собрал GET, DELETE, DELETE /notes — GET, POST: в обоих случаях адрес существует, и сервер сказал об этом прямо. /files/a%2Fb дошёл до обработчика с params.name === "a/b" — ровно потому, что декодирование стоит после split. А /notes/ и /заметки получили честный 404: первого адреса у нас нет из-за хвостового слэша, второго — нет вовсе.

Обратите внимание, чего find не делает: он не пишет в сокет, не зовёт обработчик и вообще ничего не отвечает. Он возвращает находку — обработчик с разобранным адресом или код отказа, — а отвечать будет тот, кто его позвал. Разделение не ради красоты: маршрутизатор в таком виде проверяется без сервера, сокета и портов, обычным примером в песочнице, — чем мы весь раздел и занимаемся.

Осталось одно свойство, которое стоит увидеть глазами, потому что оно портит людям вечера. Маршрут ищется первым совпадением, а значит, порядок объявления — часть поведения. Прогноз: что ответит /notes/new в двух одинаковых наборах маршрутов, объявленных в разном порядке?

// Маршрутизатор — в подложке
function routerFor(patterns) {
  const router = new Router();
  for (const pattern of patterns) router.add("GET", pattern, () => pattern);
  return router;
}

const careless = routerFor(["/notes/:id", "/notes/new"]);
const careful = routerFor(["/notes/new", "/notes/:id"]);

for (const pathname of ["/notes/new", "/notes/17"]) {
  console.log(`${pathname}: сначала объявлен :id → ${careless.find("GET", pathname).handler()}; сначала new → ${careful.find("GET", pathname).handler()}`);
}

Один и тот же адрес попал в разные обработчики — вся разница в том, какая строка объявлена раньше. В части IV этот спор решало само дерево: буквальная папка проверялась раньше переменной. Плоскую таблицу маршрутов вы тоже видели — в части V, когда собирали адреса для Expo: там этот спор решал не порядок объявления, а сортировка: таблица сортировалась один раз, при сборке, и маршруты с меньшим числом переменных сегментов вставали выше. Наш список не делает ни того, ни другого — он читается сверху вниз, как написан. Express ведёт себя так же (проверено на 5.2.1): объявите /notes/:id раньше /notes/new — и форма новой заметки станет заметкой с номером «new». Значит, выбор из двух: либо держать точные маршруты выше переменных и помнить об этом — так делает большинство, — либо один раз отсортировать при добавлении и о порядке забыть.

Множество вместо массива у списка методов — не ради скорости: один и тот же метод может подойти по нескольким маршрутам сразу, и в Allow он должен встретиться один раз.

Соберём теперь всё, что написала глава: разборщик превращает байты в запросы, маршрутизатор раздаёт их обработчикам, обработчик отвечает. Прогноз: какой код вернёт PATCH /notes/17 и что окажется в теле ответа у POST?

// RAW, разборщик и маршрутизатор — в подложке
const router = new Router();
router.add("GET", "/notes", (params, query) => ({ status: 200, body: `страница ${query.get("page") ?? 1}` }));
router.add("POST", "/notes", (params, query, request) => ({ status: 201, body: JSON.parse(request.body).title }));
router.add("GET", "/notes/:id", (params) => ({ status: 200, body: `заметка ${params.id}` }));

const parser = new RequestParser();
parser.onRequest = (request) => {
  const found = router.find(request.method, request.target);
  const answer = found.handler
    ? found.handler(found.params, found.query, request)
    : { status: found.status, body: found.allow ? `Allow: ${found.allow}` : "нет такого адреса" };
  console.log(`${request.method} ${request.target} → ${answer.status} ${answer.body}`);
};

parser.feed(RAW);
parser.feed("GET /notes?page=3 HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");
parser.feed("GET /notes/17 HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");
parser.feed("PATCH /notes/17 HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");
parser.feed("GET /health HTTP/1.1\r\nhost: java-script.pro\r\n\r\n");

Пять запросов — пять разных ответов, и ни одной проверки request.target внутри обработчиков: адрес разобран до них. Обработчик POST получил третьим аргументом весь запрос и достал заголовок заметки из тела, GET /notes — страницу из строки запроса, GET /notes/:id — номер из пути. Это Express в зародыше: таблица маршрутов, сопоставление по сегментам, params и query у обработчика на входе.

Маршрутизатор решил, КУДА идёт запрос. Он ничего не решает о том, что должно случиться с каждым запросом по дороге, — а таких дел набирается много, и сейчас они лежали бы копией в каждом обработчике.

Последняя строка таблицы — самая интересная. Когда в главе 7 на месте вашего сервера окажется Nest, @Get("/notes/:id") над методом контроллера будет делать ровно то, что делал router.add("GET", "/notes/:id", …): класть в таблицу маршрутов метод, разобранный шаблон и функцию. Разница только в том, откуда таблица берётся — из ваших вызовов или из метаданных декоратора. Механика поиска при этом не меняется совсем, и узнать её в чужих внутренностях будет легко.