Перейти до основного вмісту

HTTP Інтерсептори

Інтерсептори дуже близькі по функціональності до контролерів, але вони не створюють роутів, вони прив'язуються до вже існуючих роутів. На одному роуті може працювати ціла група інтерсепторів, що запускаються один за одним. Інтерсептори - це аналог middleware в ExpressJS, але інтерсептори можуть використовувати DI.

Як правило, інтерсептори використовують для автоматизації стандартної обробки, такої як:

  • парсинг тіла запиту чи заголовків;
  • валідація запиту;
  • збирання та логування різних метрик роботи застосунку;
  • кешування;
  • і т.д.

Інтерсептори можна централізовано підключати або відключати, не змінюючи при цьому код методів контролерів, до яких вони прив'язуються. Як і контролери, інтерсептори можуть працювати в режимі request-scoped чи route-scoped. На відміну від route-scoped, в режимі request-scoped вони мають доступ до інжектора на рівні запиту, тому вони можуть викликати сервіси на рівні запиту, роуту, модуля чи застосунку. З іншого боку, в режимі route-scoped їхні інстанси створюються на рівні роуту, відповідно - для них доступні сервіси на рівні роуту, модуля чи застосунку.

Схема обробки HTTP-запиту​

Робота в режимі request-scoped​

Обробка HTTP-запиту має наступний робочий потік:

  1. Holu створює інстанс RequestDispatcher на рівні застосунку.
  2. RequestDispatcher за допомогою роутера шукає обробника запиту відповідно до URI.
  3. Якщо обробника запиту не знайдено, RequestDispatcher видає помилку зі статусом 404.
  4. Якщо знайшовся обробник запиту, Holu створює інстанс провайдера з токеном HttpFrontend на рівні запиту, ставить його першим у черзі інтерсепторів і автоматично викликає. By default, цей інтерсептор відповідає за встановлення значень для провайдерів з токенами QUERY_PARAMS та PATH_PARAMS.
  5. Якщо в поточному маршруті є ґарди, то по-дефолту запускається RequestScopedGuardedInterceptor зразу після HttpFrontend.
  6. Наступними можуть запуститись інші інтерсептори, це залежать від того, чи запустить їх попередній у черзі інтерсептор.
  7. Якщо усі інтерсептори відпрацювали, Holu запускає HttpBackend, інстанс якого створюється на рівні запиту. By default, HttpBackend запускає безпосередньо метод контролера, що відповідає за обробку поточного запиту.

Отже, приблизний порядок обробки запиту такий:

  1. RequestDispatcher;
  2. HttpFrontend;
  3. RequestScopedGuardedInterceptor;
  4. інші інтерсептори;
  5. HttpBackend, який запускає метод контролера.

Оскільки ланцюжок промісів починається від RequestDispatcher, і закінчується методом контролера, то резолвиться цей ланцюжок у зворотньому порядку - від методу контролера до RequestDispatcher. Це означає, що в інтерсепторі ви можете слухати результат резолву проміса, що повертає метод контролера.

Окрім цього, оскільки інстанси RequestDispatcher, HttpFrontend, RequestScopedGuardedInterceptor та HttpBackend створюються за допомогою DI, ви можете їх підміняти своєю версією відповідних класів. Наприклад, якщо ви хочете не просто відправити 404-ий статус у випадку відсутності потрібного роута, а хочете ще й додати певний текст чи змінити заголовки, ви можете підмінити RequestDispatcher своїм класом.

Робота в режимі route-scoped​

Інтерсептор в режимі route-scoped працює дуже подібним чином до режиму request-scoped, але при цьому він не використовує інжектор на рівні запиту. Робочий потік за його участі відрізняється у пункті 4 та 7, оскільки інстанс інтерсептора в режимі route-scoped створюється на рівні роуту:

  1. Holu створює інстанс RequestDispatcher на рівні застосунку.
  2. RequestDispatcher за допомогою роутера шукає обробника запиту відповідно до URI.
  3. Якщо обробника запиту не знайдено, RequestDispatcher видає помилку зі статусом 404.
  4. Якщо знайшовся обробник запиту, Holu використовує інстанс провайдера з токеном HttpFrontend на рівні роуту, ставить його першим у черзі інтерсепторів і автоматично викликає. By default, цей інтерсептор відповідає за встановлення значень pathParams та queryParams для RequestContext.
  5. Якщо в поточному маршруті є ґарди, то по-дефолту запускається RouteScopedGuardedInterceptor зразу після HttpFrontend.
  6. Наступними можуть запуститись інші інтерсептори, це залежать від того, чи запустить їх попередній у черзі інтерсептор.
  7. Якщо усі інтерсептори відпрацювали, Holu запускає HttpBackend, інстанс якого використовується на рівні роуту. By default, HttpBackend запускає безпосередньо метод контролера, що відповідає за обробку поточного запиту.

Створення інтерсептора​

Кожен інтерсептор повинен бути класом, що впроваджує інтерфейс HttpInterceptor, та має анотацію з декоратором injectable:

import { injectable } from '@holu/core';
import { RequestContext, HttpHandler, HttpInterceptor } from '@holu/rest';

@injectable()
export class MyHttpInterceptor implements HttpInterceptor {
  intercept(next: HttpHandler, ctx: RequestContext) {
    return next.handle(); // Here returns Promise<any>;
  }
}

Як бачите, метод intercept() має два параметри: у перший передається інстанс обробника, що викликає наступний інтерсептор, а у другий - RequestContext, що містить нативні об'єкти запиту та відповіді від Node.js. Якщо для своєї роботи інтерсептор потребує додаткових даних, їх можна отримати в конструкторі через DI, як і в будь-якому сервісі.

Передача інтерсептора в інжектор​

Інтерсептор для режиму request-scoped передається в інжектор на рівні запиту за допомогою мульти-провайдерів з токеном HTTP_INTERCEPTORS:

import { HTTP_INTERCEPTORS, restModule } from '@holu/rest';
import { MyHttpInterceptor } from './my-http-interceptor.js';

@restModule({
  // ...
  providersPerReq: [{ token: HTTP_INTERCEPTORS, useClass: MyHttpInterceptor, multi: true }],
})
export class SomeModule {}

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

import { HTTP_INTERCEPTORS, restModule } from '@holu/rest';
import { MyHttpInterceptor } from './my-http-interceptor.js';

@restModule({
  // ...
  providersPerApp: [{ token: HTTP_INTERCEPTORS, useClass: MyHttpInterceptor, multi: true }],
})
export class SomeModule {}

В даному разі інтерсептор передано на рівні застосунку, але майте на увазі, що якщо ви передасте також інтерсептори на нижчих рівнях, то даний інтерсептор буде ігноруватись. Саме так працюють мульти-провайдери.

В даному разі інтерсептори передаються в метадані модуля. Так само вони можуть передаватись у метадані контролера. Тобто інтерсептори можуть працювати або для усіх контролерів у модулі без виключень, або тільки для конкретного контролера. Якщо інтерсептори потрібно додати лише до окремих роутів у межах контролерів, це ви можете зробити за допомогою розширень (таким чином додаються інтерсептори для парсингу тіла запиту).