Конвейер запроса: middleware, guards, interceptors, pipes, filters

Семь стадий, по порядку

Прежде чем писать первую строку guard или interceptor, нужно знать, на какой стадии конвейера он выполняется: стадия определяет, какие данные доступны, — и именно помещение логики не на ту стадию породило трёхнедельную дыру в безопасности из хука.

Каждый HTTP-запрос, доходящий до хендлера Nest, проходит фиксированную полосу препятствий из enhancer’ов. Порядок не настраивается, и спутать его в голове — это как раз способ положить логику авторизации не туда. Слева направо:

middleware → guard → interceptor (pre) → pipe → handler → interceptor (post) → filter (при throw)

1. Middleware идёт первым, на уровне Express/Fastify, биндится в configure(consumer) модуля. У него есть сырые req, res, next — но он работает до того, как Nest определил, какой хендлер обслужит маршрут, поэтому у него нет ExecutionContext, нет ссылки на хендлер, нет метаданных маршрута.
2. Guards идут следующими. canActivate(ctx) возвращает булево (или Promise/Observable от него); false коротит запрос с 403. Здесь живёт авторизация. Guard получает ExecutionContext, поэтому может читать метаданные хендлера через Reflector — но тело запроса ещё не валидировано и не трансформировано.
3. Interceptors (pre-половина) оборачивают хендлер. Код до next.handle() выполняется здесь.
4. Pipes работают над аргументами хендлера — @Body(), @Param(), @Query() — валидируя и трансформируя их (ValidationPipe, ParseIntPipe). Они выполняются после guards и после pre-половины interceptor’а, прямо перед хендлером.
5. Хендлер маршрута выполняется.
6. Interceptors (post-половина) — RxJS-pipe после next.handle() (map, timeout, кеширование, формирование ответа) выполняется на выходе. Один interceptor поэтому даёт тебе две точки выполнения вокруг хендлера.
7. Exception filters ловят всё, что выброшено на любой из стадий выше, и маппят ошибку в HTTP-ответ. Filter — последний рубеж.

// Guard работает на стадии 2 — ДО pipes. Видит метаданные хендлера, а не валидированный DTO.
@Injectable()
export class RolesGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,    // инжектируется — читает метаданные @Roles()
    private readonly users: UsersService,     // инжектируется — проверяет роли в БД
  ) {}

  async canActivate(ctx: ExecutionContext): Promise<boolean> {
    const required = this.reflector.get<string[]>('roles', ctx.getHandler());
    if (!required) return true;                // нет @Roles() → публичный маршрут
    const { user } = ctx.switchToHttp().getRequest();
    return this.users.hasAnyRole(user.id, required);
  }
}

// Interceptor — это две точки выполнения: до next.handle() и после, через RxJS.
@Injectable()
export class TimingInterceptor implements NestInterceptor {
  intercept(ctx: ExecutionContext, next: CallHandler): Observable<unknown> {
    const start = Date.now();                  // половина ДО handler-а
    return next.handle().pipe(                 // ← здесь выполняется handler
      map((data) => ({ data, ms: Date.now() - start })), // половина ПОСЛЕ handler-а
    );
  }
}

Область биндинга: где применяется enhancer

Каждый из четырёх видов enhancer’ов (guards, interceptors, pipes, filters) биндится на одной из четырёх областей: global, controller (@UseGuards() на уровне класса), method (@UseGuards() на хендлере), а для pipes ещё и parameter (@Body(new ValidationPipe())). Внутри вида выполнение идёт global → controller → method, самый внешний первым. Область отвечает на вопрос «где это применяется»; она не меняет порядок стадий выше.

DI-ловушка: new против APP_GUARD

Вот ловушка, которая укусила RolesGuard. Есть два способа зарегистрировать глобальный enhancer, и они не эквивалентны:

// АНТИПАТТЕРН: ты сам делаешь `new`, поэтому guard живёт ВНЕ DI-контейнера.
// Не может инжектить Reflector или UsersService — пришлось бы строить вручную.
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalGuards(new RolesGuard(/* что передать? */));
  await app.listen(3000);
}

// ВЕРНО: регистрируй через токен APP_GUARD в модуле. Nest инстанцирует через DI,
// Reflector и UsersService инжектятся нормально.
@Module({
  providers: [
    UsersService,
    { provide: APP_GUARD, useClass: RolesGuard },  // глобально И DI-aware
  ],
})
export class AppModule {}

app.useGlobalGuards(new X()) нормален для enhancer’а без зависимостей. В тот момент, когда enhancer’у нужно что-то инжектить — Reflector, ConfigService, репозиторий — ты обязан регистрировать его через провайдер-токен: APP_GUARD, APP_INTERCEPTOR, APP_PIPE или APP_FILTER. Они делают enhancer настоящим провайдером, который конструирует Nest, так что зависимости конструктора резолвятся из контейнера, а не оказываются null.

Режимы отказа, на которые натыкаются сеньоры

AuthZ в pipe или guard, ждущий валидированное тело. Поскольку guards выполняются до pipes, guard видит сырое тело — DTO-класс не инстанцирован, числа всё ещё строки. Авторизация, зависящая от валидированного ввода, принадлежит хендлеру или interceptor’у после pipe, а не guard, и никогда не pipe (pipe трансформирует данные, он не граница авторизации).

Ожидание, что interceptor смаппит ошибки. Interceptor может ловить через catchError в своём RxJS-pipe, но каноничный маппинг ошибки в ответ — это exception filter (@Catch, catch(exception, host)). Делать и то, и другое ведёт к двойной обработке. И область важна для того, что filter ловит: guard выбрасывает на стадии 2, до того как в игру вступает method-scoped filter, поэтому исключение, выброшенное внутри guard, ловит только filter более высокой области (глобальный).

Middleware, тянущийся к метаданным хендлера. Middleware выполняется до разрешения маршрута, поэтому нет ExecutionContext и нет способа прочитать @Roles() или любой декоратор хендлера. Если тебе нужны метаданные хендлера — нужен guard; именно поэтому guards существуют как отдельная стадия.