Guards определяют, разрешено ли запросу продолжить путь к обработчику маршрута — они являются выделенным механизмом NestJS для авторизации (и часто для проверок аутентификации). Guard возвращает true для разрешения запроса или false/выбрасывает исключение для его блокировки.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Guard реализует canActivate(), который возвращает логическое значение (или Promise/Observable от него). Возврат false блокирует запрос с кодом 403; вы также можете выбросить конкретное исключение (например UnauthorizedException).
@UseGuards(AuthGuard) // on a single route
@Get("profile")
getProfile() {}
@UseGuards(AuthGuard) // on a whole controller (all routes)
@Controller("admin")
export class AdminController {}
app.useGlobalGuards(new AuthGuard()); // globally (all routes)
Guards могут быть применены на уровне метода, контроллера или глобально.
@Injectable()
export class JwtAuthGuard implements CanActivate {
constructor(private jwtService: JwtService) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest();
const token = request.headers.authorization?.split(" ")[1];
if (!token) throw new UnauthorizedException();
try {
request.user = await this.jwtService.verifyAsync(token); // attach the user
return true;
} catch {
throw new UnauthorizedException("Invalid token");
}
}
}
// a @Roles decorator stores required roles as metadata
@Roles("admin")
@Get("users")
listUsers() {}
// the RolesGuard reads the metadata and checks the user's roles
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(ctx: ExecutionContext): boolean {
const roles = this.reflector.get<string[]>("roles", ctx.getHandler());
const { user } = ctx.switchToHttp().getRequest();
return roles.some(role => user.roles?.includes(role)); // allow if the user has a required role
}
}
Объединение декоратора @Roles() (метаданные) с guard, который его читает (через Reflector), является стандартным паттерном для role-based access control.
The ExecutionContext gives guards rich info (the handler, class, request) — more
than plain middleware — which is why guards (not middleware) are the right place
for authorization decisions.
Guards являются выделенным, идиоматичным механизмом NestJS для авторизации — контроля того, какие запросы разрешены достигать обработчиков на основе аутентификации и разрешений.
Понимание guards необходимо, потому что практически каждое реальное приложение нуждается в защите маршрутов (требование входа, проверка ролей/разрешений), и guards — это правильный инструмент для этого (намного чище, чем встраивание логики аутентификации в middleware или каждый обработчик).
Стандартные паттерны — JWT/auth guard, который проверяет учётные данные и прикрепляет пользователя к запросу, и role-based guards, объединяющие декоратор @Roles() с guard, читающим через Reflector для RBAC — являются основополагающими для защиты NestJS API.
Доступ guards к богатому ExecutionContext (знание целевого обработчика, класса и запроса) — это именно то, что делает их пригодными для принятия решений об авторизации, которые middleware не может чисто выполнить.
Знание того, как писать, применять (на уровне метода/контроллера/глобально) и объединять guards с декораторами метаданных — это основные знания для разработки защищённых NestJS приложений и частая, архитектурно важная тема в фреймворке.