Что такое middleware в NestJS и чем он отличается от guards/interceptors?

Question

Accepted Answer

**Middleware** — это функция, которая запускается **перед обработчиком маршрута**, с доступом к объектам request и response — то же самое понятие, что и Express middleware. NestJS также имеет guards, interceptors, pipes и filters, каждый из которых запускается в определённой точке жизненного цикла запроса с отчётливой целью. Знание того, какой использовать — ключевой навык.

## Middleware — запускается первым, имеет доступ к req/res

```ts
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);   // logging, modifying req
    next();                                      // MUST call next() to continue
  }
}

// register in a module
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes("*");   // apply to routes
  }
}
```

Middleware запускается раньше всех — перед guards/interceptors/pipes — и работает с сырыми `req`/`res`, хорош для логирования, изменения запроса, CORS и других Express-совместимых задач.

## Полный порядок жизненного цикла запроса

```text
Request →
  1. Middleware     (req/res; runs first, Express-style)
  2. Guards         (return true/false → AUTHORIZE or block the request)
  3. Interceptors   (BEFORE the handler)
  4. Pipes          (validate/transform the handler's arguments)
  5. → Route Handler ←
  6. Interceptors   (AFTER the handler — transform the response)
  7. Exception Filters (if an error was thrown anywhere)
→ Response
```

## Для чего каждый нужен (выбор нужного инструмента)

```text
Middleware  → general pre-processing with req/res (logging, CORS, raw request work)
Guards      → AUTHORIZATION — decide if a request may proceed (auth, roles)
              (return true = allow, false/throw = block)
Interceptors→ wrap the handler — transform request/response, add logging/caching/timing
              (can run logic BEFORE and AFTER the handler)
Pipes       → VALIDATE/TRANSFORM the handler's input arguments (DTO validation)
Filters     → catch and format EXCEPTIONS into responses
```

Ключевые различия: middleware — это общая предварительная обработка в стиле Express; **guards** специально занимаются авторизацией (отличное, выделенное место для auth в отличие от размещения её в middleware); **interceptors** оборачивают обработчик для трансформации ответов или добавления сквозных функций; **pipes** валидируют входные данные; **filters** обрабатывают ошибки.

## Когда использовать middleware vs guards vs interceptors

```text
Auth check?           → Guard (dedicated, has execution context, returns boolean)
Logging requests?     → Middleware OR an interceptor (interceptor sees the response too)
Transform responses?  → Interceptor (runs after the handler)
Validate a DTO?       → Pipe
Modify raw req early?  → Middleware
```

## Почему это важно

Понимание middleware и того, чем он отличается от guards, interceptors, pipes и filters, критически важно для правильной структурирования NestJS приложений — каждый инструмент имеет определённую роль и запускается в определённой точке жизненного цикла запроса, и выбор правильного инструмента приводит к чистому, идиоматическому коду.

Middleware обрабатывает общую предварительную обработку в стиле Express с сырыми req/res.

Критические различия в том, что **guards** — это выделенное, правильное место для авторизации (auth/roles) — намного чище, чем middleware для этих целей — и **interceptors** оборачивают обработчик для трансформации ответов и добавления сквозных функций (логирование, кэширование, измерение времени), которые middleware не может легко реализовать (так как он запускается перед обработчиком и не видит ответ).

Знание полного порядка жизненного цикла (middleware → guards → interceptors → pipes → handler → interceptors → filters) и выбор правильного инструмента для каждой задачи (auth → guard, трансформация ответа → interceptor, валидация → pipe, ошибки → filter) — признак компетентности в NestJS и предотвращает распространённую ошибку неправильного использования middleware для всего подряд.

Это часто тестируемая, архитектурно важная тема в этом фреймворке.