Как написать свой собственный Typesafe React Router в 500 строк

Когда я изучал React около 6 лет назад, реакции-маршрутизатор была одной из первых сторонних библиотек, которые я взял на вооружение. Я имею в виду, что это имеет смысл: маршрутизация является одним из ключевых аспектов современного одностраничного приложения. Я принял это как должное. Для меня React-Router был волшебной коробочкой, я понятия не имел, как он работает внутри. Итак, когда через какое-то время я естественным образом разобрался, как вообще работает маршрутизация, стало немного грустно. Никакого волшебства, да :( Но я рад, что оставил позади концепцию «волшебных черных ящиков». Я думаю, что это очень вредная идея. Понимание того, что технология когда-либо была создана инженерами, как и мы с вами, меня очень вдохновляет, и я надеюсь, что то же самое произойдет и с вами. каждая Итак, присоединяйтесь ко мне в этом посте, где мы с нуля создадим собственный типобезопасный маршрутизатор, чтобы открыть этот черный ящик и понять его внутреннюю работу. В этой статье предполагается, что вы уже знаете React и умеете работать с TypeScript. Особенности и ограничения Позвольте мне обозначить, какие возможности нашего роутера будут рассмотрены в этой статье. Нашей убийственной особенностью будет типобезопасность. Это означает, что вам нужно будет заранее определить свои маршруты, и TypeScript проверит, чтобы вы не передали какую-то ерунду вместо URL-адреса и не попытались получить параметры, отсутствующие в текущем маршруте. Это потребует некоторой гимнастики, но не волнуйтесь, я вам все расскажу. Кроме того, наш маршрутизатор будет поддерживать все, что вы ожидаете от обычного маршрутизатора: навигацию по URL-адресам, сопоставление маршрутов, анализ параметров маршрута, навигацию вперед/назад и блокировку навигации. Теперь об ограничениях. Наш маршрутизатор будет работать только в браузере (извините, React Native!) и не будет поддерживать SRR. Поддержка SSR должна быть относительно простой, но этот пост уже большой, поэтому я не буду его освещать. Терминология Теперь, когда у нас есть видение того, что мы хотим сделать, нам нужно поговорить о структуре и терминологии. Подобных концепций будет довольно много, поэтому крайне важно определить их заранее. В нашей библиотеке будет два типа маршрутов: необработанные маршруты и проанализированные маршруты. — это просто строка, которая выглядит как или ; это шаблон для URL-адресов. Необработанный маршрут может содержать параметры, которые представляют собой разделы, начинающиеся с двоеточия, например . Необработанный маршрут /user/:id/info /login :id Этот формат удобен для разработчиков, но не для программ; мы преобразуем эти маршруты в более удобный для машины формат и назовем его . анализируемым маршрутом Но пользователи не открывают маршруты, они открывают URL-адреса. А URL — это идентификатор ресурса (в нашем случае страницы внутри приложения); это может выглядеть так: . Наш маршрутизатор в основном заботится о второй части URL-адреса ( ), которую мы назовем . http://example.app/user/42/info?anonymous=1#bio /user/42/info?anonymous=1#bio path Путь состоит из ( ), ( ) и ( ). Объект, в котором эти компоненты хранятся как отдельные поля, будет называться . имени пути /user/42/info параметров поиска ?anonymous=1 хеша #bio location Общий обзор API При создании библиотек React я предпочитаю выполнять три шага. Прежде всего, императивный API. Его функции можно вызывать из любого места, и они обычно вообще не привязаны к React. В случае маршрутизатора это будут такие функции, как , или . navigate getLocation subscribe Затем на основе этих функций создаются перехватчики, такие как или . А затем эти функции и хуки используются в качестве основы для создания компонентов. По моему опыту, это работает исключительно хорошо и позволяет создать легко расширяемую и универсальную библиотеку. useLocation useCurrentRoute API маршрутизатора начинается с функции . Предполагается, что пользователь передает карту всех необработанных маршрутов функции, которая анализирует маршруты и возвращает отображение той же формы. Все API-интерфейсы, ориентированные на разработчиков, такие как создание URL-адресов или сопоставление маршрутов, будут принимать проанализированные маршруты, а не необработанные. defineRoutes const routes = defineRoutes({ login: '/login', user: { me: '/user/me', byId: '/user/:id/info', } }); Следующий шаг — передать проанализированные маршруты в функцию . Это суть нашего роутера. Эта функция создаст все функции, хуки и компоненты. Это может показаться необычным, но такая структура позволяет нам адаптировать типы принимаемых аргументов и свойств к определенному набору маршрутов, определенных в , гарантируя типобезопасность (и улучшая DX). createRouter routes const { Link, Route, useCurrentRoute, navigate, /* etc... */ } = createRouter(routes); будет возвращать функции, которые можно использовать где угодно в вашем приложении (императивный API), перехватчики, позволяющие вашим компонентам реагировать на изменения местоположения, и три компонента: , и . Этого будет достаточно, чтобы охватить большинство случаев использования, и вы сможете создавать свои собственные компоненты на основе этих API. createRouter Link Route NotFound Программирование на уровне типа для удовольствия и прибыли Начнем с рассмотрения части нашей презентации, посвященной типобезопасности. Как я упоминал ранее, при использовании типобезопасного маршрутизатора TypeScript заранее предупредит вас о такой ситуации: Или вот так: const { userld } = useRoute(routes.user.byId); И если сразу не видно, что в них не так, то вам обязательно нужен типобезопасный роутер :) Система типов в TypeScript очень мощная. Я имею в виду, что вы можете создать , или даже используя программирование на уровне типов. шахматный движок приключенческую игру базу данных SQL, Вы уже знакомы с «программированием на уровне значений», где вы манипулируете значениями, например, объединяя две строки: function concat(a, b) { return a + b; } concat('Hello, ', 'World!'); // 'Hello, World!' Но вы можете сделать это и с типами! type Concat = `${A}${B}`; type X = Concat ; // ^? type X = "Hello, World!" Да, он не такой мощный, как ваши обычные функции, и выглядит иначе. Но это позволяет вам делать довольно крутые и полезные вещи. Мы будем использовать программирование на уровне типов для извлечения параметров из необработанных маршрутов и создания новых типов, которые смогут проверять, не пытается ли разработчик передать неверные значения в или в функцию, создающую URL-адрес. Link Программирование на уровне типов с помощью TS может быстро превратиться в нечитаемый беспорядок. К счастью для нас, уже существует множество проектов, которые скрывают всю эту сложность и позволяют нам писать такой чистый код: export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; Довольно аккуратно, да? Это, кстати, весь код, необходимый для анализа параметров необработанного маршрута. В этом проекте мы будем использовать библиотеку — это поможет нам снизить сложность и объем кода на уровне типа. hotscript Но это не обязательно: если вы любите приключения, вы можете попробовать реализовать все эти типы самостоятельно. Некоторое вдохновение вы можете найти в , который реализует аналогичные функции без использования сторонних библиотек типов. маршрутизаторе Chicane Если вы собираетесь следовать инструкциям, я рекомендую вам создать новый проект React, используя ваш любимый стартер (я использую ), и начать писать код там. Таким образом, вы сможете сразу протестировать свой маршрутизатор. Vite Обратите внимание, что такие платформы, как Next.js, предоставляют собственную маршрутизацию, которая может помешать работе этого проекта, и вместо этого используют «ванильный» React. Если у вас возникнут трудности, вы можете найти полный код . здесь Начните с установки сторонних пакетов: для утилит уровня типа и для анализа параметров из URL/необработанного маршрута. hotscript regexparam npm install hotscript regexparam Первым строительным кирпичиком наших типов является необработанный маршрут. Необработанный маршрут должен начинаться с ; как бы вы это закодировали в TS? Так: / export type RawRoute = `/${string}`; Легко, правда? Но не принимает одиночный необработанный маршрут, он принимает сопоставления, возможно, вложенные, поэтому давайте напишем это. У вас может возникнуть соблазн написать что-то вроде этого: defineRoutes export type RawRoutesMap = { [key: string]: RawRoute | RawRoutesMap }; Это сработает. Однако этот тип может быть бесконечно глубоким, и в некоторых случаях TS будет сложно его вычислить. Чтобы облегчить жизнь TS, мы ограничим уровень разрешенной вложенности. 20 уровней вложенности должно быть достаточно для всех приложений, и TS легко с этим справится. Но как ограничить глубину рекурсивных типов? Я узнал об этом трюке из этого ; вот версия, модифицированная под наши требования: ответа SO export type RecursiveMap = { [key: string]: RecursiveMap_ ; }; type RecursiveMap_ = MaxDepth extends Stack["length"] ? T : T | { [key: string]: RecursiveMap_ }; Это наш первый сложный тип, поэтому позвольте мне его объяснить. Здесь у нас есть два типа: работает как точка входа и вызывает передавая ему дополнительный параметр кортежа. Этот кортеж используется для отслеживания глубины отображения, при каждом вызове мы добавляем в этот массив один элемент. RecursiveMap RecursiveMap_ И мы продолжаем его вызывать до тех пор, пока длина этого кортежа не станет равна . В TS, когда используется с значениями, также называемыми литералами (например, , а не ), это означает «равно». MaxDepth extends конкретными 42 number А поскольку и , и являются конкретными числами, этот код можно прочитать как . Вы увидите, что эта конструкция часто используется. MaxDepth Stack["length"] MaxDepth === Stack["length"] Зачем использовать кортеж вместо простого сложения чисел? Что ж, сложить два числа в TypeScript не так-то просто! Для этого существует , и Hotscript тоже может добавлять числа, но для этого требуется много кода (даже если вы его не видите), что может замедлить работу вашего TS-сервера и редактора кода при чрезмерном использовании. целая библиотека Итак, мое практическое правило — избегать сложных типов, насколько это возможно. С помощью этого типа утилиты мы можем определить наше сопоставление так же просто, как: export type RawRoutesMap = RecursiveMap ; Это все, что касается необработанных типов маршрутов. Следующим в очереди идет разобранный маршрут. Разобранный маршрут — это просто объект JavaScript с несколькими дополнительными полями и одной функцией; вот как это выглядит: export type ParsedRoute = { keys: RouteParam []; build(...params: PathConstructorParams ): Path ; raw: R; ambiguousness: number, pattern: RegExp; }; Начнем распаковку с поля . Это просто массив параметров, необходимых для этого маршрута. Вот как это делается: keys import { Pipe, Strings, Tuples } from "hotscript"; export type RouteParam = Pipe , Tuples.Filter >, Tuples.Map >, Tuples.ToUnion ] >; В Hotscript существует два способа вызова функции: или . полезен, когда вам нужно вызвать одну функцию, но в нашем случае их 4! принимает входные данные и передает их в первую функцию предоставленного кортежа. Call Pipe Call Pipe Возвращаемое значение передается в качестве входных данных во вторую функцию и так далее. В нашем случае, если бы у нас был, например, необработанный маршрут , он был бы преобразован так: /user/:userId/posts/:postId export type Beep = Pipe , // ["user", ":userId", "posts", ":postId"] Tuples.Filter >, // [":userId", ":postId"] Tuples.Map >, // ["userId", "postId"] Tuples.ToUnion // "userId" | "postId" ] >; Видеть? Это магия программирования на уровне типа! Теперь давайте займемся этой функцией . Он принимает параметры маршрута (например и ) и необязательные параметры поиска/хеш и объединяет их в путь. Взгляните на реализацию : build userId postId PathConstructorParams // Allows us to also accept number and // any other type which can be converted into string export type StringLike = { toString: () => string }; export type SearchAndHashPathConstructorParams = { hash?: string, search?: string | { [key: string]: string, } }; export type RouteParamsMap = { [key in RouteParam ]: Val }; export type PathConstructorParams = | [RouteParamsMap ] | [RouteParamsMap , SearchAndHashPathConstructorParams]; Параметры функции определяются как массив (который позже... распространяется в определении ), где первый элемент — , а второй — необязательный . А как насчет возврата значения ? Мы уже установили его путь, но как его описать с помощью TypeScript? build RouteParamsMap SearchAndHashPathConstructorParams build Что ж, этот очень похож на , но требует немного больше гимнастики с типами! RouteParam import { Fn } from "hotscript"; interface ReplaceParam extends Fn { return: this["arg0"] extends `:${string}` ? string : this["arg0"]; } // Leading slashes will be removed by Split , so we need to // add them back after our manipulations type Pathname = `/${Pipe , Tuples.Map , Tuples.Join ] >}${Route extends `${string}/` ? '/' : ''}`; export type Path = Pathname | `${Pathname }?${string}` | `${Pathname }#${string}`; Здесь мы разбиваем наш маршрут на сегменты, сопоставляем каждый сегмент и вызываем для каждого нашу пользовательскую функцию . Он проверяет, является ли текущий сегмент параметром, и заменяет его или возвращает сегмент как есть. «Функция» может выглядеть немного странно, но именно так вы определяете пользовательские функции с помощью Hotscript. ReplaceParam string ReplaceParam Мы явно заявляем, что путь состоит либо из простого пути, пути, за которым следует вопросительный знак (это касается URL-адресов с параметрами поиска и хеша), либо символа решетки (это касается URL-адресов без параметров поиска, но с хешем). Нам также понадобится тип для описания сопоставленного маршрута, т. е. проанализированного маршрута с параметрами, полученными из URL-адреса: // Interface (and not type) because we need to use `this` export interface RouteWithParams { route: ParsedRoute , params: RouteParamsMap , // TS can't properly infer type of route object with simple // check like currentRoute.route === routes.user.byId, so we // need our custom type guard matches: (route: ParsedRoute ) => this is RouteWithParams , } Последний тип — ; это похоже на , но для анализируемых маршрутов. ParsedRoutesMap RawRoutesMap // This accepts RawRoutesMap and transforms it into // mapping of parsed routes of same shape export type ParsedRoutesMap = { [Key in keyof RM]: RM[Key] extends RawRoute ? ParsedRoute : RM[Key] extends RawRoutesMap ? ParsedRoutesMap : never; }; И на этой ноте мы заканчиваем с типами. Будет еще несколько, но они проще, и мы рассмотрим их по мере реализации. Если вам хотелось бы больше попробовать программирование на уровне типа, вы можете ознакомиться с , чтобы узнать больше и попытаться решить (у них также есть хороший ). Typescript на уровне типа проблемы с типами список ресурсов Парсер маршрутов Наконец, мы вернулись к обычному кодированию на уровне значений. Давайте начнем с реализации . defineRoutes export const typedKeys = (obj: T) => { return Object.keys(obj) as Array ; }; export const defineRoutes = (routesMap: T): ParsedRoutesMap => { const entries = typedKeys(routesMap).map((key) => { const entry = routesMap[key]; if (typeof entry === 'string') { return [key, parseRoute(entry)] as const; } else { // Nested map return [key, defineRoutes(entry)] as const; } }); return Object.fromEntries(entries); }; Здесь нет ничего сложного; давайте углубимся в функцию . parseRoute import { parse, inject, type RouteParams as RegexRouteParams } from "regexparam"; export class InvalidRoute extends Error { }; export class InvalidRouteParams extends Error { }; const parseRoute = (route: R): ParsedRoute => { if (!route.startsWith('/')) { throw new InvalidRoute('route should start with slash (/)') } const { keys, pattern } = parse(route); const hasRequiredParams = keys.length > 0; const parsedRoute: ParsedRoute = { build(...args) { const params = ( hasRequiredParams ? args[0] : undefined ) as RouteParamsMap | undefined; const searchAndHash = ( hasRequiredParams ? args[1] : args[0] ) as SearchAndHashPathConstructorParams | undefined; if (hasRequiredParams) { if (!params) { throw new InvalidRouteParams( `Parameters for route ${route} weren't provided` ); } const missingKeys = keys.filter(k => !(k in params)); if (missingKeys.length) { throw new InvalidRouteParams( `Missing parameters for route ${route}: ${missingKeys.join(', ')}` ); } } else if (args.length > 1) { throw new InvalidRouteParams( `Route ${route} doesn't accept any parameters, received ${args[0]}` ); } let path = hasRequiredParams ? inject(route, params as RegexRouteParams ) : route; if (searchAndHash && searchAndHash.search) { if (typeof searchAndHash.search === 'string') { path += searchAndHash.search.startsWith('?') ? searchAndHash.search : '?' + searchAndHash.search; } else { path += '?' + new URLSearchParams(searchAndHash.search).toString(); } } if (searchAndHash && searchAndHash.hash) { path += searchAndHash.hash.startsWith('#') ? searchAndHash.hash : '#' + searchAndHash.hash; } return path as Path ; }, raw: route, keys: keys as RouteParam [] || [], ambiguousness: keys.length, pattern: pattern, }; return parsedRoute; }; также очень прост, хотя и заметно длиннее. Для анализа маршрута и извлечения параметров мы используем библиотеку . Это позволяет нам получить массив параметров, необходимых для маршрута, и генерирует регулярное выражение, которое мы позже будем использовать для сопоставления URL-адреса с маршрутом. parseRoute regexparam Мы храним эту информацию вместе с исходным необработанным маршрутом, использованным для создания этого объекта, и уровнем неоднозначности (который представляет собой всего лишь ряд параметров в маршруте). Обертка истории Каждый маршрутизатор должен где-то хранить свое состояние. В случае приложений в браузере это на самом деле сводится к 4 вариантам: в памяти (либо в переменной состояния внутри корневого компонента, либо в переменной вне дерева компонентов), History API или хэш-часть URL-адреса. Маршрутизация в памяти может быть вашим выбором, если вы вообще не хотите показывать пользователю, что у вас есть маршруты, например, если вы кодируете игру в React. Хранение маршрута в хеше может быть удобно, когда ваше приложение React представляет собой всего лишь одну страницу в более крупном приложении, и вы не можете просто изменить URL-адрес по своему усмотрению. Но в большинстве случаев использование History API будет лучшим вариантом. Он совместим с SSR (другие варианты не поддерживаются), следует шаблонам поведения, к которым привык пользователь, и выглядит максимально чисто. В этом проекте мы тоже будем его использовать. Однако у него есть один заметный недостаток: его практически невозможно использовать без дополнительных оберток. С помощью History AP вы можете подписаться на событие , и браузер сообщит вам, когда URL-адрес изменится. Но только если изменение инициировано пользователем, например, нажав кнопку «Назад». Если изменение URL-адреса инициируется из кода, вам необходимо отслеживать его самостоятельно. popstate Большинство маршрутизаторов, которые я изучал, используют свою собственную оболочку: пакет NPM использования React-Router и Chicane, маршрутизатор TanStack имеет , а у wouter нет полноценной оболочки, но ему все равно приходится . для истории собственную реализацию обновлять историю Итак, давайте реализуем нашу собственную обертку. export type HistoryLocation = Pick ; export type NavigationBlocker = (isSoftNavigation: boolean) => boolean; export const createHistory = () => { const winHistory = window.history; const winLocation = window.location; const getLocation = (): HistoryLocation => { return { origin: winLocation.origin, href: winLocation.href, pathname: winLocation.pathname, search: winLocation.search, hash: winLocation.hash, }; }; /* Some magic code */ return /* something... */; }; Мы будем использовать два типа: и . Первый — это немного ограниченная версия встроенного типа (это тип ), а второй будет рассмотрен, когда мы доберемся до блокировки навигации. Весь дальнейший код из этой главы будет находиться внутри функции . HistoryLocation NavigationBlocker Location window.location createHistory Начнем с реализации подписки на изменения истории. В этом проекте мы будем использовать функции в стиле React для подписки: вы вызываете передавая обратный вызов, и она возвращает другую функцию, которую вам нужно вызвать, когда вы хотите отказаться от подписки. subscribe const subscribers: Set = new Set(); const onChange = () => { subscribers.forEach(fn => { try { fn(); } catch (err) { console.error('Error while handling location update', err); } }) }; const subscribe = (listener: VoidFunction) => { subscribers.add(listener); return () => { subscribers.delete(listener); }; }; Следующий шаг — реагировать на изменения местоположения, в том числе на изменения, внесенные программно. Как бы вы это сделали? Разумеется, с помощью . Это может показаться немного грязным (и это действительно так), но, к сожалению, у нас нет лучшего варианта. обезьяньих патчей const origPushState = winHistory.pushState.bind(winHistory); const origReplaceState = winHistory.replaceState.bind(winHistory); winHistory.pushState = (data, unused, url) => { // tryNavigate will be covered later tryNavigate(() => { origPushState(data, unused, url); onChange(); }); }; winHistory.replaceState = (data, unused, url) => { tryNavigate(() => { origReplaceState(data, unused, url); onChange(); }); }; // This event is emmited when user initiates navigation // or when calling history.go, history.back and history.forward window.addEventListener('popstate', onChange); И последний важный недостающий элемент в нашей истории реализации — это блокировка навигации: функция, которая позволяет перехватить запрос навигации и условно отменить его. Каноническим примером блокировки навигации может быть предотвращение потери пользователем прогресса в форме. let blockers: NavigationBlocker[] = []; const beforeUnloadHandler = (event: Event) => { const blocked = blockers.some(blocker => blocker(false)); if (blocked) { event.preventDefault(); // @ts-ignore For older browsers event.returnValue = ''; return ''; } }; const tryNavigate = (cb: VoidFunction) => { const blocked = blockers.some(blocker => blocker(true)); if (blocked) return; cb(); }; const addBlocker = (blocker: NavigationBlocker) => { blockers.push(blocker); if (blockers.length === 1) { addEventListener('beforeunload', beforeUnloadHandler, { capture: true }); } return () => { blockers = blockers.filter(b => b !== blocker); if (blockers.length === 0) { removeEventListener('beforeunload', beforeUnloadHandler, { capture: true }); } } }; В нашей реализации блокировщик — это функция, которая возвращает логическое значение, указывающее, нужно ли нам заблокировать эту навигацию. Что касается блокировки навигации, существует два типа навигации, и нам придется обращаться с ними по-разному. С одной стороны, существует программная навигация — когда пользователь переходит с одной страницы нашего приложения на другую страницу нашего приложения. Мы полностью контролируем его и, таким образом, можем заблокировать его, отобразить любой пользовательский интерфейс (для подтверждения намерений пользователя) или выполнить действия после блокировки навигации. С другой стороны, есть жесткая навигация — когда пользователь переходит на другой сайт или вообще закрывает вкладку. Браузер не может позволить JavaScript решать, следует ли выполнять эту навигацию, поскольку это будет угрозой безопасности. Но браузер позволяет JavaScript указать, хотим ли мы показать пользователю дополнительное диалоговое окно подтверждения. При блокировке программной навигации вы можете захотеть отобразить дополнительный пользовательский интерфейс (например, настраиваемое диалоговое окно подтверждения), но в случае жесткой навигации это не имеет смысла, поскольку пользователь увидит его только в том случае, если решит остаться на странице и В этот момент это бесполезно и сбивает с толку. Когда наша история вызывает функцию блокировки навигации, она предоставляет логическое значение, указывающее, выполняем ли мы мягкую навигацию. И при всем этом нам просто нужно вернуть наш объект истории: return { subscribe, getLocation, push: winHistory.pushState, replace: winHistory.replaceState, go: (distance: number) => tryNavigate(() => winHistory.go.call(winHistory, distance)), back: () => tryNavigate(() => winHistory.back.call(winHistory)), forward: () => tryNavigate(() => winHistory.forward.call(winHistory)), addBlocker, }; Шаг 1. Императивный API Мы наконец здесь. Императивный API станет основой для всех дальнейших хуков и компонентов и позволит разработчику создавать собственные хуки для удовлетворения своих потребностей. Прежде всего, нам нужно преобразовать нашу карту маршрутов в плоский массив. Таким образом, будет намного проще перебирать все маршруты, что нам пригодится, когда мы начнем работать над сопоставлением маршрутов. Нам нужны как утилита типа (которая преобразует в объединение ), так и функция (которая преобразует в массив проанализированных маршрутов). Начнем с типа: ParsedRoutesMap ParsedRoute routesMap export type Values = T[keyof T]; type FlattenRouteMap = T extends ParsedRoute | RawRoute ? T : T extends ParsedRoutesMap | RawRoutesMap ? AllRoutesFromMap : never; export type AllRoutesFromMap | RawRoutesMap > = FlattenRouteMap >; Разделение этого на два типа может показаться ненужным, но для этого есть одна очень важная причина: если вы реализуете его как один тип, который вызывает сам себя, TS будет жаловаться, что этот тип слишком глубокий и, возможно, бесконечный. Итак, мы обошли эту проблему, разделив его на два типа, которые вызывают друг друга. Для функции уровня значения нам также понадобится защита типа, чтобы проверить, является ли переданное значение проанализированным маршрутом. export const isParsedRoute = ( route: any ): route is ParsedRoute => { return !!route && typeof route === 'object' && typeof route.raw === 'string' && typeof route.build === 'function'; } export const getAllRoutes = ( routesMap: ParsedRoutesMap ): ParsedRoute >[] => { type PossibleRawRoute = AllRoutesFromMap ; return typedKeys(routesMap).flatMap((k) => { const val = routesMap[k]; if (isParsedRoute (val)) { return [val] as const; } // At this point we know that val isn't ParsedRoute, so it has to be map of routes // but TS can't infer that, so we help him a little by casting val to correct type return getAllRoutes(val as ParsedRoutesMap ); }); }; Теперь приступим к реализации нашего маршрутизатора. Как и в истории, в этой и следующих двух главах весь код будет передан в функцию , если не указано иное. createRouter import { useSyncExternalStore, ComponentType, useMemo, MouseEventHandler, ComponentProps, useEffect } from 'react'; export const createRouter = (routesMap: ParsedRoutesMap ) => { // Type for any possible route from passed routesMap type RouteType = AllRoutesFromMap ; // Similar to above, but for matched routes, ie includes URL parameters type BindedRouteWithParams = RouteWithParams ; // Some of our functions will accept route filter, // which can be single parsed route, array or object type RouteFilter = | ParsedRoute | ParsedRoute [] | Record >; const history = createHistory(); const routes = getAllRoutes(routesMap); }; Прежде всего, давайте научим наш маршрутизатор сопоставлять текущее местоположение с одним из известных маршрутов. Несколько утилит могут работать в глобальном масштабе или в отдельных файлах, а не внутри функции : createRouter export const filterOutFalsy = (obj: T[]): Exclude [] => { return obj.filter(Boolean) as Exclude []; }; export class RouteMatchingConflict extends Error { }; // This will be used later export class RouteMismatch extends Error { }; И этот код попадает в функцию . createRouter const extractRouteParams = ( pathname: string, parsedRoute: ParsedRoute ) => { const match = parsedRoute.pattern.exec(pathname); if (!match) return undefined; // Extract all route parameters from match array // and construct object from them return Object.fromEntries(parsedRoute.keys.map((key, index) => { return [key, match[index + 1]]; })) as RouteParamsMap ; }; const findMatchingRoute = ( location: HistoryLocation ): BindedRouteWithParams | undefined => { const matchingRoutes = filterOutFalsy(routes.map(route => { const params = extractRouteParams ( location.pathname, route ); if (!params) return undefined; return { route, params, matches (r: ParsedRoute ) { return route === r; }, }; })); if (matchingRoutes.length === 0) return undefined; if (matchingRoutes.length === 1) return matchingRoutes[0]; // At this point we have multiple matching routes :/ // Gotta decide which one we prefer let lowestAmbiguousnessLevel = Infinity; let lowestAmbiguousnessMatches: BindedRouteWithParams[] = []; matchingRoutes.forEach((match) => { if (match.route.ambiguousness === lowestAmbiguousnessLevel) { lowestAmbiguousnessMatches.push(match); } else if (match.route.ambiguousness m.route.raw).join(', ')}` ); } return lowestAmbiguousnessMatches[0]; }; let currentRoute = findMatchingRoute(history.getLocation()); // This function will be later returned from createRouter function const getCurrentRoute = () => currentRoute; Здесь мы проходим все известные маршруты и пытаемся сопоставить каждый из них с текущим местоположением. Если регулярное выражение маршрута соответствует URL — мы получаем параметры маршрута из URL, в противном случае — . Для каждого сопоставленного маршрута мы создаем объект и сохраняем его в массив. Теперь, если у нас есть 0 или 1 совпадающих маршрутов, всё просто. null RouteWithParams Однако если текущему местоположению соответствует более одного маршрута, нам придется решить, какой из них имеет более высокий приоритет. Чтобы решить эту проблему, мы используем поле . Как вы, наверное, помните, этот маршрут имеет ряд параметров, и приоритет имеет маршрут с наименьшей . ambiguousness ambiguousness Например, если бы у нас было два маршрута и , местоположение соответствовало бы обоим маршрутам. Но совершенно очевидно, что этот URL-адрес должен соответствовать маршруту , а не . /app/dashboard /app/:section http://example.com/app/dashboard /app/dashboard /app/:section Однако этот алгоритм не является пуленепробиваемым. Например, маршруты и будут соответствовать URL-адресу . А поскольку уровень неоднозначности у них одинаковый, наш маршрутизатор не сможет решить, какой из них должен быть приоритетным. /app/:user/settings/:section /app/dashboard/:section/:region http://example.com/app/dashboard/settings/asia Теперь нам нужно соединить этот код, чтобы реагировать на изменения местоположения и обновлять переменную ; currentRoute const areRoutesEqual = ( a: RouteWithParams | undefined, b: RouteWithParams | undefined ): boolean => { if (!a && !b) return true; // Both are undefined if ((!a && b) || (a && !b)) return false; // Only one is undefined if (!a!.matches(b!.route)) return false; // Different routes // Same routes, but maybe parameters are different? const allParamsMatch = a.route.keys.every(key => a.params[key] === b!.params[key]); return allParamsMatch; }; history.subscribe(() => { const newRoute = findMatchingRoute(history.getLocation()); if (!areRoutesEqual(newRoute, currentRoute)) { currentRoute = newRoute; notifyRouteChange(); // Will be covered later } }); Теперь наш роутер реагирует на изменение местоположения, и пользователь всегда может узнать текущий маршрут, ура! Но без возможности подписываться на изменения маршрутов это не очень полезно, поэтому давайте добавим это. Подход очень похож на тот, который мы использовали в обертке истории. const subscribers: Set = new Set(); const subscribe = (cb: VoidFunction) => { subscribers.add(cb); return () => void subscribers.delete(cb); }; const notifyRouteChange = () => { subscribers.forEach(cb => { try { cb(); } catch (err) { console.error('Error in route change subscriber', err); } }); }; Для выполнения навигации мы предоставим функции и , которые представляют собой простую оболочку и : navigate navigateUnsafe history.push history.replace // This function accepts any string path (no type-safety) const navigateUnsafe = ( path: string, { action = 'push' }: { action?: 'push' | 'replace' } = {} ) => { history[action]({}, '', path) }; // And this function accepts only paths that correspond to one of routes const navigate = ( path: Path , options: { action?: 'push' | 'replace' } = {} ) => { navigateUnsafe(path, options); }; Ну вот это настоящий роутер! Очень примитивно, но тем не менее работает. Нам еще нужно реализовать некоторые хуки и компоненты, но дальше все станет намного проще. Шаг 2: Крючки Что касается хуков, мы можем начать с простых, которые возвращают текущее местоположение и текущий маршрут. Сами по себе они довольно просты, но превращает их в однострочные. То, как мы ранее разработали наш императивный API, позволило нам значительно сократить код для этих перехватчиков. использованиеSyncExternalStore const useLocation = () => { return useSyncExternalStore(history.subscribe, history.getLocation); }; const useCurrentRoute = () => { return useSyncExternalStore(subscribe, getCurrentRoute); }; При кодировании компонентов, которые должны отображаться только на определенном маршруте/наборе маршрутов, вы можете использовать чтобы получить текущий маршрут, проверить, соответствует ли он критериям, а затем использовать его параметры (или выдать ошибку). useCurrentRoute Но это настолько распространенная задача, что заставлять наших пользователей писать для этого собственный хук будет преступлением — наш роутер должен обеспечивать это «из коробки». function useRoute (filter: RouteFilter , strict?: true): RouteWithParams ; function useRoute (filter: RouteFilter , strict: false): RouteWithParams | undefined; function useRoute (filter: RouteFilter , strict?: boolean): RouteWithParams | undefined { const currentRoute = useCurrentRoute(); const normalizedFilter = Array.isArray(filter) ? filter : isParsedRoute(filter) ? [filter] : Object.values(filter); const isMatching = !!currentRoute && normalizedFilter.some(route => currentRoute.matches(route)); if (isMatching) return currentRoute as RouteWithParams ; else { if (strict === false) return undefined; throw new RouteMismatch( `Current route doesn't match provided filter(s)` ); } } Этот крючок имеет два варианта: строгий и расслабленный. Если пользователь передает в качестве второго параметра (или ничего не передает, поскольку — значение по умолчанию), этот перехват выдаст ошибку, если текущий маршрут не соответствует одному из предоставленных фильтров. true true Таким образом, вы можете быть уверены, что перехватчик вернет соответствующий маршрут или не вернется вообще. Если второй параметр имеет значение false, то вместо того, чтобы генерировать исключение, перехватчик просто вернет неопределенное значение, если текущий маршрут не соответствует фильтрам. Чтобы описать это поведение в TypeScript, мы используем функцию, называемую . Это позволяет нам определить несколько определений функций разных типов, и TypeScript автоматически выберет одно из них, которое будет использоваться, когда пользователь вызывает такую функцию. перегрузкой функции Помимо параметров пути, некоторые данные могут передаваться в параметрах поиска, поэтому давайте добавим перехватчик для их анализа из строки в сопоставление. Для этого мы воспользуемся встроенным API браузера . URLSearchParams const useSearchParams = () => { const location = useLocation(); return useMemo(() => { return Object.fromEntries( (new URLSearchParams(location.search)).entries() ); }, [location.search]); }; И последний хук в этом разделе — , который тоже довольно прост: он просто принимает обратный вызов и оборачивает вызовы в эффект, чтобы повторно подключить блокировщик, если он изменится. useNavigationBlocker history.addBlocker const useNavigationBlocker = (cb: NavigationBlocker) => { useEffect(() => { return history.addBlocker(cb); }, [cb]); }; Теперь давайте перейдем к компонентам! Шаг 3: Компоненты Какой компонент первым приходит на ум при упоминании библиотек маршрутизации? Могу поспорить, что это или, по крайней мере, что-то подобное. Как вы видели ранее, наши перехватчики были очень простыми благодаря хорошо продуманному императивному API, который выполнял всю тяжелую работу. Route То же самое касается компонентов; они могут быть легко реализованы пользователем с помощью нескольких строк кода. Но у нас серьезная библиотека маршрутизации, давайте добавим в комплект батарейки :) type RouteProps = { component: ComponentType, match: RouteFilter }; const Route = ({ component: Component, match }: RouteProps) => { const matchedRoute = useRoute(match, false); if (!matchedRoute) return null; return ( ); }; Ну, это было легко! Хотите угадать, как мы реализуем компонент ? :) NotFound type NotFoundProps = { component: ComponentType }; const NotFound = ({ component: Component }: NotFoundProps) => { const currentRoute = useCurrentRoute(); if (currentRoute) return null; return ( ); }; И последний компонент, необходимый для нашего маршрутизатора, — , который немного сложнее. Вы не можете просто использовать , поскольку он всегда инициирует жесткую навигацию и не обеспечивает никакой безопасности типов. Итак, давайте разберемся с этими вопросами: Link type LinkProps = Omit , 'href'> & ( // Our link accepts either type-strict href // or relaxed unsafeHref { href: Path , unsafeHref?: undefined } | { href?: undefined, unsafeHref: string } ) & { action?: 'push' | 'replace' }; const Link = ({ action = 'push', onClick, href, unsafeHref, ...props }: LinkProps) => { const hrefToUse = (href ?? unsafeHref)!; const targetsCurrentTab = props.target !== '_blank'; const localOnClick: MouseEventHandler = (event) => { if (onClick) { onClick(event); if (event.isDefaultPrevented()) { // User-defined click handler cacnelled navigation, we should exit too return; } } const inNewTab = !targetsCurrentTab || event.ctrlKey || event.shiftKey || event.metaKey || event.button === 1; if (!isExternal && !inNewTab) { event.preventDefault(); navigateUnsafe(hrefToUse, { action }); } }; const isExternal = useMemo(() => { if (!hrefToUse) return false; return new URL(hrefToUse, window.location.href).origin !== location.origin; }, [hrefToUse]); return }; Подобно функции , тип компонента проверяет URL-адрес, который вы передаете ему, но также позволяет вам предоставить произвольный строковый URL-адрес (в качестве аварийного люка или для внешних ссылок). Чтобы переопределить поведение , мы подключаем наш собственный прослушиватель , внутри которого нам нужно будет вызвать исходный (переданный нашему компоненту ). navigate Link onClick onClick Link После этого мы проверяем, не была ли навигация уже прервана разработчиком (если это было, мы должны игнорировать это событие). Если все хорошо, проверяем, не является ли ссылка внешней и должна ли она быть открыта в текущей вкладке. И только тогда мы сможем отменить встроенную жесткую навигацию и вместо этого вызвать собственную функцию . navigateUnsafe И теперь нам просто нужно вернуть все наши функции, перехватчики и компоненты (вместе с несколькими функциями, реэкспортированными непосредственно из истории) из функции . createRouter return { // Directly re-exported from history go: history.go, back: history.back, forward: history.forward, addBlocker: history.addBlocker, getLocation: history.getLocation, subscribeToLocation: history.subscribe, // Imperative API subscribe, getCurrentRoute, navigate, navigateUnsafe, // Hooks useLocation, useCurrentRoute, useRoute, useSearchParams, useNavigationBlocker, // Components Link, Route, NotFound, }; На этом наш роутер готов. Теперь мы можем создать наше крошечное приложение, чтобы продемонстрировать только что созданный нами крошечный маршрутизатор! Кстати, полный код этого роутера (включая код примера приложения) вы можете найти . здесь Собираем кусочки головоломки вместе Итак, как весь этот код связан вместе? Очень аккуратно, если я так говорю! Представьте, что вы создаете приложение для заметок. Во-первых, вы должны начать с определения маршрутов и создания маршрутизатора следующим образом: export const routes = defineRoutes({ // Yep, this will be very minimal app root: '/', newNote: '/new', note: '/note/:noteId', }); const router = createRouter(routes); // Export functions and component you will be using export const { navigate, Link, Route, NotFound, useRoute, useNavigationBlocker } = router; Затем вы связываете определенные вами маршруты с компонентами страницы: function App() { return ( {/* This is how you build URL for Link */} View all notes Create new ) } В вам необходимо получить идентификатор заметки из URL-адреса, поэтому вы используете перехватчик : NoteDetailsPage useRoute export const NoteDetailsPage = () => { const { getNote } = useNotes(); const { params } = useRoute(routes.note); const note = getNote(params.noteId); return note ? (<> {note.title} {note.text} ) : ( Not found ); }; И при создании новой заметки вы, вероятно, захотите подтвердить намерение пользователя, если он уйдет, не сохранив заметку: export const NewNotePage = () => { const saveNote = () => { isSubmittingNoteRef.current = true; const note = createNote(title, text); // And this is programmatic redirect navigate(routes.note.build({ noteId: note.id })); isSubmittingNoteRef.current = false; }; const [title, setTitle] = useState(''); const [text, setText] = useState(''); const { createNote } = useNotes(); const isSubmittingNoteRef = useRef(false); useNavigationBlocker((isSoftNavigation) => { const dirty = title !== '' || text !== ''; if (!dirty || isSubmittingNoteRef.current) return false; if (isSoftNavigation) { const confirmation = confirm('Do you want to leave?'); return !confirmation; } else { return true; } }); return <> New note setTitle(e.target.value)} /> setText(e.target.value)} /> Save ; }; Возможные улучшения Хотя наш маршрутизатор действительно выполняет маршрутизацию, он не может сравниться с готовыми к использованию решениями, такими как маршрутизатор TanStack, маршрутизатор React-Router или маршрутизатор Next.js. Я имею в виду, что это всего около 500 строк кода, это немного. Но чего именно не хватает? Прежде всего, рендеринг на стороне сервера. Сегодня не всем приложениям может потребоваться SSR, но ожидается, что все библиотеки маршрутизации будут его поддерживать. Добавление рендеринга на стороне сервера в строку (не потоковая SSR!) потребует создания другой , которая будет хранить текущее местоположение в памяти (поскольку на сервере нет API истории) и подключения ее к функции . history createRouter Я не знаю, насколько сложно будет реализовать потоковую SSR, но предполагаю, что это будет сильно связано с поддержкой Suspense. Во-вторых, этот маршрутизатор плохо интегрируется с параллельным рендерингом. В основном из-за того, что мы используем , поскольку он несовместим с . Это работает таким образом, чтобы избежать разрывов: ситуация, когда часть пользовательского интерфейса отображается с определенным значением хранилища, а остальная часть пользовательского интерфейса отображается с другим. useSyncExternalStore неблокирующими переходами И из-за этого маршрутизатор плохо интегрируется с приостановкой, поскольку для каждого приостанавливаемого обновления местоположения будет отображаться резервный вариант. Кстати, о параллелизме в React я рассказывал в этой , а в рассказываю о приостановке, выборке данных и перехватчика. статье этой use Но даже несмотря на эти недостатки, я надеюсь, что эта статья показалась вам интересной и вы создали свой собственный маршрутизатор :)