Guards určují, zda je požadavek povolen pokračovat k handleru trasy — jedná se o vyhrazený mechanismus NestJS pro autorizaci (a často i ověření autentičnosti). Guard vrátí true pro povolení požadavku nebo false/vyhodí výjimku pro jeho zablokování.
@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 implementuje canActivate(), která vrací boolean (nebo Promise/Observable z něj). Vrácení false zablokuje požadavek s chybou 403; můžete také vyhodit specifickou výjimku (např. 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 lze aplikovat na úrovni metody, kontroléru nebo globálně.
@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
}
}
Kombinace dekorátoru @Roles() (metadata) s guardem, který jej čte (přes Reflector), je standardní vzor pro řízení přístupu na základě rolí.
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 jsou vyhrazený, idiomatický mechanismus NestJS pro autorizaci — kontrolu, které požadavky mohou dosáhnout handlerů na základě ověření a oprávnění.
Jejich pochopení je nezbytné, protože prakticky každá skutečná aplikace potřebuje chránit trasy (vyžadovat přihlášení, kontrolovat role/oprávnění) a guards jsou správný nástroj pro to (podstatně čistší než vsouvání logiky ověření do middleware nebo jednotlivých handlerů).
Standardní vzory — guard JWT/autentizace, který ověřuje přihlašovací údaje a připojuje uživatele k požadavku, a guardy na základě rolí kombinující dekorátor @Roles() s guardem čtoucím Reflector pro RBAC — jsou zásadní pro zabezpečení NestJS API.
Přístup guardů k bohatému ExecutionContext (znalost cílového handleru, třídy a požadavku) je přesně to, co je činí vhodnými pro autorizační rozhodnutí, která middleware nemůže čistě provádět.
Vědomí, jak psát, aplikovat (metoda/kontrolér/globálně) a kombinovat guardy s dekorátory metadat, je základní znalostí pro budování bezpečných aplikací NestJS a je to často vyskytující se a architektonicky důležité téma v rámci.