Проміжні обробники (middleware)

Обробники оновлень, які передаються в bot.on(), bot.command() та інші методи, називаються проміжними обробниками. Хоча цілком правильно називати їх “обробниками оновлень”, спрощено можна ще називати їх просто “обробниками”.

У цьому розділі пояснюється, що таке проміжні обробники, а grammY використовується для прикладу, щоб проілюструвати, як їх можна використовувати. Якщо ви шукаєте конкретну документацію про те, що робить реалізацію проміжних обробників у grammY особливою, перегляньте можливості проміжних обробників у просунутій документації.

Стек проміжних обробників

Припустимо, ви написали такого бота:

const bot = new Bot("");

bot.use(session());

bot.command("start", (ctx) => ctx.reply("Бот запущений!"));
bot.command("help", (ctx) => ctx.reply("Довідка"));

bot.on(":text", (ctx) => ctx.reply("Текст!")); // (*)
bot.on(":photo", (ctx) => ctx.reply("Фото!"));

bot.start();

Після надходження оновлення зі звичайним текстовим повідомленням, будуть виконані наступні кроки:

1. Ви надсилаєте боту “Привіт!”.
2. Проміжний обробник плагіну для роботи сесій отримує оновлення і виконує необхідні дії для забезпечення сесії.
3. Оновлення буде перевірено на наявність команди /start, яка в даному випадку відсутня.
4. Оновлення буде перевірено на наявність команди /help, яка в даному випадку відсутня.
5. Оновлення буде перевірено на наявність тексту, що в данному випадку буде успішним.
6. На рядку, позначеному (*), буде викликано проміжний обробник, який обробить оновлення, відповівши "Текст!".

Оновлення не перевіряється на наявність фото, оскільки проміжний обробник на рядку (*) вже обробив оновлення.

Тож, як це працює? Давайте дізнаємося.

Ви можете переглянути тип Middleware у довідці grammY тут:

// Деякі параметри типу пропущено для спрощення.
type Middleware = MiddlewareFn | MiddlewareObj;

Ага! Проміжний обробник може бути функцією або обʼєктом. Поки що ми використовували лише функції ((ctx) => { ... }), тому давайте наразі залишимо обʼєкти проміжних обробників та заглибимося в тип MiddlewareFn (довідка):

// Знову пропущено параметри типу для спрощення.
type MiddlewareFn = (ctx: Context, next: NextFunction) => MaybePromise<unknown>;
// де
type NextFunction = () => Promise<void>;

Отже, проміжний обробник приймає два параметри! Поки що ми використовували лише один: обʼєкт контексту ctx. Ми вже знаємо, що таке ctx, але ми також бачимо функцію next. Для розуміння, що таке next, ми маємо загалом розглянути як працюють проміжні обробники, які ви встановлюєте в свого бота.

Ви можете розглядати всі встановлені функції проміжних обробників як кілька рівнів, які розташовані один на одному. Перший проміжний обробник, у нашому прикладі це session, є найвищим рівнем, тому він першим отримує кожне оновлення. Далі він може вирішити, чи завершити обробку оновлення, чи передати його на наступний рівень. В нашому випадку на наступному рівні обробник команди /start. Для виклику наступного проміжного обробника, який часто називають нижнім проміжним обробником, використовується функція next. Також це означає, що якщо ви не викличете next у вашому проміжному обробнику, то усі наступні нижні рівні проміжних обробників не будуть викликані.

Цей стек функцій називається стеком проміжних обробників.

(ctx, next) => ...    |
(ctx, next) => ...    |—————вищий проміжний обробник відносно X
(ctx, next) => ...    |
(ctx, next) => ...       <— проміжний обробник X. Викликаємо `next`, щоб передати оновлення 🡳
(ctx, next) => ...    |
(ctx, next) => ...    |—————нижчий проміжний обробник відносно X
(ctx, next) => ...    |

Повертаючись до попереднього прикладу, тепер ми знаємо, чому bot.on(":photo") навіть не перевірявся: проміжний обробник в bot.on(":text", (ctx) => { ... }) вже обробив оновлення, тому й не викликав next. Фактично, next навіть не вказаний як аргумент функції. Таким чином, ми просто проігнорували next, отже, не передали обробку оновлення далі.

Давайте спробуємо щось інше з нашими новими знаннями!

const bot = new Bot("");

bot.on(":text", (ctx) => ctx.reply("Текст!"));
bot.command("start", (ctx) => ctx.reply("Команда!"));

bot.start();

Якщо ви запустите бота, написаного над цим рядком, та надішлете /start, ви ніколи не побачите відповідь Команда!. Перевіримо, що відбувається:

1. Ви надсилаєте "/start" боту.
2. Проміжний обробник ":text" отримує оновлення та перевіряє текст, що завершується успішно, оскільки будь-які команди також є текстовими повідомленнями. Оновлення негайно обробляється першим проміжним обробником, і ваш бот відповідає Текст!.

Повідомлення ніколи не буде перевірятися, чи містить воно команду /start! Порядок, у якому ви реєструєте проміжні обробники, має значення, оскільки він визначає послідовність рівнів у стеку проміжних обробників. Ви можете вирішити проблему, помінявши місцями 3-й та 4-й рядок. Якщо ви викличете next у 3-у рядку, то буде надіслано дві відповіді.

Метод bot.use() реєструє проміжний обробник, який отримує всі оновлення. Ось чому session() встановлюється через bot.use(): ми хочемо, щоб плагін працював з усіма оновленнями, незалежно від даних оновлення.

Наявність стеку проміжних обробників є надзвичайно потужною властивістю будь-якого фреймворку, і цей шаблон широко популярний не лише для ботів Telegram.

Давайте напишемо наш власний невеликий проміжний обробник, щоб краще проілюструвати, як це працює.

Написання власного проміжного обробника

Ми проілюструємо концепцію проміжних обробників, написавши просту функцію проміжного обробника, яка може вимірювати час відповіді вашого бота, тобто скільки часу потрібно вашому боту, щоб обробити повідомлення.

Ось сигнатура функції для нашого проміжного обробника. Ви можете порівняти його з типом проміжного обробника, наведеного вище, і переконатися, що ми дійсно створили проміжний обробник.

TypeScript

/** Вимірюємо час відповіді бота та виводимо його у `console` */
async function responseTime(
  ctx: Context,
  next: NextFunction, // це псевдонім для: () => Promise<void>
): Promise<void> {
  // TODO: реалізувати
}

JavaScript

/** Вимірюємо час відповіді бота та виводимо його у `console` */
async function responseTime(ctx, next) {
  // TODO: реалізувати
}

Ми можемо встановити його в обʼєкт bot за допомогою bot.use():

bot.use(responseTime);

Почнемо його реалізовувати. Ось що ми хочемо зробити:

1. Щойно надходить оновлення, ми зберігаємо Date.now() у змінній.
2. Ми викликаємо нижні проміжні обробники, отже, дозволяємо виконувати всю подальшу обробку повідомлень. Це включає обробку команд, відповідання та все інше, що робить ваш бот.
3. Ми знову беремо Date.now(), порівнюємо його зі старим значенням та використовуємо console.log для виведення різниці в часі в консоль.

Дуже важливо встановити наш проміжний обробник responseTime у бота у самому початку, на верхній рівень стеку. Це важливо тому, що ми хочемо вимірювати час усіх операцій обробки оновлення.

TypeScript

/** Вимірюємо час відповіді бота та виводимо його у `console` */
async function responseTime(
  ctx: Context,
  next: NextFunction, // це псевдонім для: () => Promise<void>
): Promise<void> {
  // зберігаємо поточний час до виконання
  const before = Date.now(); // мілісекунд
  // викликаємо нижні проміжні обробники
  await next(); // переконуємося, що дочекалися (`await`)!
  // зберігаємо поточний час після виконання
  const after = Date.now(); // мілісекунд
  // виводимо різницю у консоль
  console.log(`Час обробки: ${after - before} мс`);
}

bot.use(responseTime);

JavaScript

/** Вимірюємо час відповіді бота та виводимо його у `console` */
async function responseTime(ctx, next) {
  // зберігаємо поточний час до виконання
  const before = Date.now(); // мілісекунд
  // викликаємо нижні проміжні обробники
  await next(); // переконуємося, що дочекалися (`await`)!
  // зберігаємо поточний час після виконання
  const after = Date.now(); // мілісекунд
  // виводимо різницю у консоль
  console.log(`Час обробки: ${after - before} мс`);
}

bot.use(responseTime);

Готово та працює! ✔️

Не соромтеся використовувати цей проміжний обробник на своєму обʼєкті бота, зареєструйте більше обробників і пограйтеся з прикладом. Це допоможе вам повністю зрозуміти, що таке проміжний обробник.

ЗАСТЕРЕЖЕННЯ: завжди чекайте виконання наступного проміжного обробника!

Якщо ви коли-небудь викличете next() без ключового слова await, дещо вийде з ладу:

• ❌ Ваш стек проміжних обробників буде виконано в неправильному порядку.
• ❌ Ви можете втратити дані.
• ❌ Деякі повідомлення можуть не надіслатися.
• ❌ Ваш бот може випадково аварійно завершити роботу у спосіб, який важко відтворити.
• ❌ Якщо сталася помилка, ваш обробник помилок не буде викликаний. Натомість ви побачите, що зʼявиться UnhandledPromiseRejectionWarning, що може призвести до збою вашого бота.
• ❌ Ламається механізм плагіну для конкурентності (runner), що захищає ваш сервер від перенавантаження, наприклад, під час різких сплесків навантаження.
• 💀 Іноді це також може вбити всіх ваших невинних котиків. 😿

Правило використання await є особливо важливим для next(), але насправді воно стосується будь-якого виразу, який повертає Promise. Це включає bot.api.sendMessage, ctx.reply та всі інші мережеві виклики. Якщо ваш проєкт важливий для вас, ви напевно використовуєте інструменти лінтингу, які попереджають вас, якщо ви забули використати await на Promise.

Увімкніть no-floating-promises

Розгляньте можливість використання ESLint і налаштуйте його на використання no-floating-promises. Це гарантує, що ви ніколи не забудете використати await, адже ESLint крикне на вас.

Властивості проміжних обробників у grammY

У grammY проміжний обробник може повертати Promise, якого слід дочекатися (await), але він також може бути синхронним.

На відміну від інших систем проміжних обробників, таких як система express, ви не можете передати значення помилок у next. next не приймає жодних аргументів. Якщо ви хочете зробити помилку, ви можете просто кинути (throw) її. Ще одна відмінність полягає в тому, що не має значення, скільки аргументів приймає ваш проміжний обробник: () => {} буде оброблятися точно як (ctx) => {} або як (ctx, next) => {}.

Існує два типи проміжних обробників: функції та обʼєкти. Обʼєкти проміжного обробника є просто оболонкою для функцій проміжного обробника. Здебільшого вони використовуються внутрішньо, але іноді також можуть допомогти стороннім бібліотекам або використовуватися у складних випадках: наприклад, із Composer:

const bot = new Bot("");

bot.use(/*...*/);
bot.use(/*...*/);

const composer = new Composer();
composer.use(/*...*/);
composer.use(/*...*/);
composer.use(/*...*/);
bot.use(composer); // composer — обʼєкт проміжного обробника!

bot.use(/*...*/);
bot.use(/*...*/);
// ...

Якщо ви хочете глибше дізнатися, як grammY реалізує проміжні обробники, перегляньте можливості проміжних обробників у просунутій документації.