«Арете — сервер мессенджеров, Max edition»

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

Функция СобратьРоутер(Бот) Экспорт
	
	// Обязательная первая строка функции
	Роутер = АСМ_Роутинг.ИнициализироватьРоутер(Бот);
	
	// Переменные, используемые ниже в именованном условии и роуте
	Роутер.Вставить("Администраторы", Справочники.АСМ_Пользователи.НайтиПоКоду(5));
	Роутер.Вставить("ПривилегированныеПользователи", ПривилегированныеПользователи());
	
	// Одно именованное условие
	АСМ_Роутинг.ДобавитьИменованноеУсловие("ЭтоАдминистратор", Роутер, "Пользователь ВИерархии #Администраторы");
	
	// Два обычных роута
	АСМ_Роутинг.ДобавитьРоут("Привет", Роутер, "Текст = 'Привет'");
	АСМ_Роутинг.ДобавитьРоут("СтартБота", Роутер, "ТипСобытия = 'bot_started'");
	// Роут с именованным условием
	АСМ_Роутинг.ДобавитьРоут("ОтправитьОтчетПоПродажам", Роутер, "@ЭтоАдминистратор И ИмяКнопки = 'Отчет'");
	// Роут с переменной
	АСМ_Роутинг.ДобавитьРоут("ОборотыЗаГод", Роутер, "Пользователь ВСписке #ПривилегированныеПользователи И Текст = 'Обороты'");
	
	Возврат Роутер;
	
КонецФункции

Процедура ОбработатьСобытие(Бот, Событие, Вход) Экспорт
	
	// обязательная часть
	Роутер = АСМ_НастройкиПовтИсп.СобратьРоутер(Бот);
	
	// в режиме разработки замените строку выше на эту:
	// Роутер = СобратьРоутер(Бот);
	
	Привет						("Привет", 						Роутер, Бот, Событие, Вход);
	ОтправитьОтчетПоПродажам	("ОтправитьОтчетПоПродажам", 	Роутер, Бот, Событие, Вход);
	
КонецПроцедуры

Процедура, вызываемая из ОбработатьСобытие, принимает параметры (Ключ, Роутер, Бот, Событие, Вход). Её первой исполняемой строкой должна быть проверка: Если АСМ_Роутинг.Нет(Ключ, Роутер, Событие, Вход) Тогда Возврат КонецЕсли;

Процедура Привет(Ключ, Роутер, Бот, Событие, Вход)
	
	// Обязательная первая строка любой процедуры,
	// вызываемой из ОбработатьСобытие
	Если АСМ_Роутинг.Нет(Ключ, Роутер, Событие, Вход) Тогда Возврат КонецЕсли;
	
	// Необязательный учёт сработавших маршрутов
	Роутер.Сработало = Роутер.Сработало + 1;
	
	// Код ниже выполняется только при соответствии события условию роута
	ПараметрыМетода = Новый Структура;
	ПараметрыМетода.Вставить("text", "И Вам привет, сейчас " + ТекущаяДата());
	АСМ_М.ОтправитьСообщение(Бот, ПараметрыМетода, Вход);
	
КонецПроцедуры

АСМ_Роутинг.Нет находит условие по ключу и сопоставляет его с событием. Если условие не выполнено, процедура сразу завершается. Если выполнено — исполняется весь код после этой строки. Поэтому проверка занимает одну строку и играет роль входного фильтра для процедуры.

Увеличение Роутер.Сработало не является обязательной частью роутинга. Этот счётчик полезен, если в конце обработки есть запасной маршрут для событий, которые не подошли ни под одно условие. При необходимости связанную логику можно вынести в собственную обёртку над АСМ_Роутинг.Нет.

Реализуем простой сценарий: на сообщение Привет бот отвечает строкой И тебе привет, сейчас и добавляет текущую дату.

Функция СобратьРоутер(Бот) Экспорт
	
	Роутер = АСМ_Роутинг.ИнициализироватьРоутер(Бот);
	АСМ_Роутинг.ДобавитьРоут("Привет", Роутер, "Текст = 'Привет'");
	Возврат Роутер;
	
КонецФункции

Процедура ОбработатьСобытие(Бот, Событие, Вход) Экспорт
	
	Роутер = АСМ_НастройкиПовтИсп.СобратьРоутер(Бот);
	Привет("Привет", Роутер, Бот, Событие, Вход);
	
КонецПроцедуры

Процедура Привет(Ключ, Роутер, Бот, Событие, Вход)
	
	Если АСМ_Роутинг.Нет(Ключ, Роутер, Событие, Вход) Тогда Возврат КонецЕсли;
	
	ПараметрыМетода = Новый Структура;
	ПараметрыМетода.Вставить("text", "И тебе привет, сейчас " + ТекущаяДата());
	АСМ_М.ОтправитьСообщение(Бот, ПараметрыМетода, Вход);
	
КонецПроцедуры

Таким образом, маршрут всегда проходит три этапа: регистрация ключа и условия в СобратьРоутер, вызов процедуры с этим ключом из ОбработатьСобытие и проверка АСМ_Роутинг.Нет перед прикладной логикой.

Зарезервированное слово указывает, какое значение входящего события нужно проверить: текст сообщения, команду, пользователя, дату или наличие вложения. Доступные слова хранятся в справочнике «АСМ — Зарезервированные слова». Для каждого элемента справочника заданы допустимые написания и виды сравнений.

Написания можно менять и дополнять под соглашения проекта. Например, если слово Пользователь кажется слишком длинным, добавьте для него написание ПЛЗ. После этого условие можно записать как ПЛЗ ВСписке #Администраторы. После изменения справочника необходимо сбросить кэш повторно используемых значений или перезапустить сеанс.

Вид сравнения определяет, как проверяется значение: равно ли оно указанному, содержит ли строку, входит ли в список и так далее. Поддерживаемые варианты приведены ниже.

Написания также можно менять и дополнять под себя в справочнике «АСМ — Виды сравнений». Например, одному виду сравнения можно назначить полное и сокращённое написания. После изменения справочника следует сбросить кэш повторно используемых значений или перезапустить сеанс.

Условие роута — это строковое выражение. В нём можно использовать зарезервированные слова, виды сравнений, литералы, @именованные условия, #переменные, связки И / ИЛИ и скобки. Ниже приведены примеры от простых проверок до составных выражений.

Именованное условие позволяет один раз описать повторяющуюся проверку и затем использовать её в нескольких роутах. Условие регистрируется вызовом ДобавитьИменованноеУсловие("Имя", Роутер, "…"), а в строке роута указывается как @Имя. При регистрации символ @ перед именем не ставится.

Результат именованного условия всегда имеет тип Булево: Истина или Ложь. Оно не может вернуть строку, число, дату, ссылку или другое значение. Для подстановки таких значений предназначены #переменные.

АСМ_Роутинг.ДобавитьИменованноеУсловие(
	"ЭтоАдминистратор",
	Роутер,
	"Пользователь ВИерархии #Администраторы");

АСМ_Роутинг.ДобавитьРоут("ОтчетАдмина", Роутер, "@ЭтоАдминистратор");
АСМ_Роутинг.ДобавитьРоут("ОтчетАдминаЯвно", Роутер, "@ЭтоАдминистратор = Истина");
АСМ_Роутинг.ДобавитьРоут("НеАдмин", Роутер, "@ЭтоАдминистратор = Ложь");

В первом роуте вид сравнения не указан, поэтому @ЭтоАдминистратор неявно сравнивается с Истина. Во втором роуте та же проверка записана явно. Третий роут срабатывает, когда именованное условие вернуло Ложь.

Переменная подставляет в условие значение, рассчитанное в коде. Её имя указывается с префиксом #, например #Сработало или #НачалоТекущегоДня. Значение добавляется в структуру роутера через Роутер.Вставить. Кроме того, роутеру можно передать Вход.Состояния, чтобы обращаться к состояниям из условий.

Роутер.Вставить("Администраторы", Справочники.АСМ_Пользователи.НайтиПоКоду(5));
Роутер.Вставить("ПривилегированныеПользователи", ПривилегированныеПользователи());
АСМ_Роутинг.ДобавитьРоут(
	"ОборотыЗаГод",
	Роутер,
	"Пользователь ВСписке #ПривилегированныеПользователи И Текст = 'Обороты'");

Роутер.Вставить("Состояния", Вход.Состояния);
Роутер.Вставить("Сработало", 0);
Роутер.Вставить("НачалоТекущегоДня", НачалоДня(ТекущаяДата()));

АСМ_Роутинг.ДобавитьРоут(
	"СвежиеОстатки",
	Роутер,
	"ИмяКнопки = 'Остатки' И Дата > #НачалоТекущегоДня");

• Двойные кавычки в литерале условия — нужны одинарные: Текст = 'Привет'.
• Смешали И и ИЛИ без скобок: И свяжется раньше.
• Команда с кириллицей или дефисом не распознается: шаблон /[a-z0-9_]+.
• В имени callback-кнопки символ |.
• «Начало дня» и состояния положили в СобратьРоутер — значение замёрзнет в кэше сеанса.
• Поменяли справочник написаний или таблицу роутов и ждёте эффект без сброса кэша.
• Запасной роут #Сработало = 0 без увеличения счётчика в рабочих процедурах — он будет срабатывать всегда или никогда, если счётчик не обнуляете на старте события.
• Часовой пояс бота не задан — сравнения по Дата уедут на UTC.