Сопоставление маршрутов - router.json

В этой статье описаны правила настройки перенаправления ссылок (redirect) и сопоставления маршрутов.

Таблица замен собирается из файлов router.json, которые могут содержаться в любом интерфейсном модуле. Она содержит информацию о том, как необходимо изменить URL-адрес перед поиском соответствующего ему приложения.

При переходе по URL-адресу определяется соответствующее ему приложение:

1. Изменяется префикс URL-адреса согласно таблице замен router.json. Подробнее об этом файле будет сказано далее.
2. Из получившегося адреса извлекается подстрока между первыми двумя слэшами. Она используется в качестве названия интерфейсного модуля.
3. Данный URL-адрес соответствует приложению в контроле Index полученного интерфейсного модуля.

Создать файл router.json можно в любом каталоге интерфейсного модуля, поскольку билдер при сборке проекта соберет все router.json в один файл и положит его в корень проекта. Этот файл представляет собой единую таблицу замен и в последствии будет использоваться для механизма маршрутизации.

Файл router.json должен находиться в корне интерфейсного модуля и иметь следующий формат:

// router.json
{
   "префикс url": "замена префикса",
   "префикс url 2": "замена 2",
   ...
}

На первом шаге маршрутизации выполняется обход этого списка. В нем ищется самый длинный префикс, который совпадает с началом текущего URL-адреса. После завершения поиска, если такой префикс был найден, выполняется его замена в URL-адресе на соответствующую строку.

Это можно использовать например для того, чтобы сделать приложения доступными по адресам, отличным от названий их интерфейсного модуля. Например:

// router.json
{
   "/Books": "BookShop",
   "/Books/Bestselling": "ExpensiveShop/Books/Best",
   "/Tickets": "TicketShop"
}

В этом примере при переходе по адресу /Books/ будет найден самый длинный подходящий префикс Books и совершен переход по адресу /BookShop/, то есть будет загружено приложение BookShop/Index.

При переходе по адресу /Books/Bestselling/2019 наиболее подходящий префикс — Books/Bestselling, поэтому будет совершен переход по адресу /ExpensiveShop/Books/Best/2019, и загружено приложение ExpensiveShop/Index.

Для адреса /Buy/Tickets в таблице префикса нет, поэтому он останется без изменений, и будет загружено приложение Buy/Index.

Корневая замена

В router.json также может задаваться особая "корневая" замена с помощью префикса "/". Эта замена применяется только при переходе на корневой URL с возможностью наличия в адресе query-параметров, то есть параметров вида name=value.

Это можно применить, чтобы контрол Travel/Index был доступен по корневому маршруту:

// router.json
{
   "/": "Travel"
}

При такой замене, по адресам /, /?promo=true и т.д. будет открываться приложение Travel/Index. При этом, по адресу /abc будет доступно уже приложение abc/Index.

Динамичная корневая замена

Бывают сценарии, когда для какого-либо сервиса есть необходимость в корневом URL использовать динамичное значение, например идентификатор какого-то объекта. В таком случае в router.json допускается использование регулярного выражения.

Например, есть необходимость в URL адресе service.sbis.ru/2171a35b-c1da-4292-9602-6b5bf821b212, в котором кусок после корня может быть любым валидным GUID. Для такой ситуации в router.json можно добавить следующую строку замены:

// router.json
{
   "/regex:^([0-9a-f]{36})$": "ModuleName/$1"
}

При такой замене по адресу /2171a35b-c1da-4292-9602-6b5bf821b212 и т.п. будет открываться приложение ModuleName/Index.

Здесь можно использовать "любые" регулярные выражения, учитывая некоторые особенности:

1. перед регулярным выражением необходимо указать строку "regex:".
2. регулярные выражения имеет смысл использовать только, если есть динамичная часть в корне приложения/сервиса, т.к. в остальных сценариях можно обойтись без них.
3. регулярное выражение следует задавать наиболее точно соответствующим вашим данным, иначе могут быть ложные "соответствия".
4. в регулярном выражении необходимо использовать "захватывающие скобки", а в значении замены должен быть идентификатор ($1 - нумерация начинается с 1) "захваченной строки". Это нужно, чтобы соответствующее регулярному выражению значение было добавлено в итоговый URL.
5. вы это делаете на свой страх и риск, т.к. использование неоптимальных регулярных выражений может привести к замедлению разбора маршрутов. Необходимо четко понимать зачем этот риск.

Примеры маршрутов в router.json

Разберем все типичные сценарии задания маршрутов на примере следующего router.json:

// router.json
{
   "/": "RootModule/",
   "/regex:^([0-9a-f]{36})$": "ModuleName/$1",
   "/doc": "Docs/",
   "/edo": "NewModule/edo/standard",
   "/edo/standard": "NewModule/edo/standard"
}

1. Корневой маршрут

   "/": "RootModule/"

   при такой замене по адресам /, /?promo=true и т.д. будет открываться приложение Travel/Index.

2. Динамичный корневой маршрут

   "/regex:^([0-9a-f]{36})$": "ModuleName/$1",

   при такой замене по адресу /2171a35b-c1da-4292-9602-6b5bf821b212 и т.п. будет открываться приложение ModuleName/Index.

3. Обычный маршрут

   "/doc": "Docs/",

   при такой замене по адресам /doc, /doc/path, /doc?promo=true и т.д. будет открываться приложение Doc/Index.

4. Дублирующий маршрут

   "/edo": "NewModule/edo/standard",
   "/edo/standard": "NewModule/edo/standard"

   такая замена задается, когда по разным маршрутам необходимо открывать одно и то же приложение с заданными параметрами. В данном случае по адресам /edo, /edo/standard и т.д. будет открываться приложение NewModule/Index.