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

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

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

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

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

Таблица замен влияет только на сопоставление URL-адресов определенным приложениям. Пользователь продолжает видеть в адресной строке браузера исходный URL-адрес до замены. При этом сопоставление маршрута и все контролы роутинга будут работать с измененным адресом.

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

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

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

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

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

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

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

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

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

Добавление адресов в файл router.json должно быть согласовано с ответственным за приложение. Для online.sbis.ru такое согласование должно быть с Новиковым Д.В.. Также для online.sbis.ru такая замена должна быть описана в конфигурации онлайн-роутинга.

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

В 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 то, что слева - это префикс URL-адреса, который виден в адресной строке. А то, что справа - это маршрут, с которым будет работать роутинг. Рассмотрим следующий файл router.json.

// router.json
{
   "/task": "ModuleName/task",
   "/contacts": "ModuleName/contacts"
}

При переходе по URL-адресу вида /task/name?query=value роутинг будет работать со строкой вида ModuleName/task/name?query=value. Соответственно и маску следует писать так, чтобы она разбирала эту строку. Напр. маской вида ModuleName/:sectionId после разбора этой строки получим значение

sectionId = 'task'

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

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

// router.json
{
   "/": "RootModule/",
   "/regex:^([0-9a-f]{36})$": "ModuleName/$1",
   "/doc": "Docs/doc",
   "/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.