Guarzi determină dacă o cerere este permisă să procedeze spre handlerul rutei — sunt mecanismul dedicat NestJS pentru autorizare (și adesea verificări de autentificare). Un guard returnează true pentru a permite cererea sau false/aruncă o excepție pentru a o bloca.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Un guard implementează canActivate(), care returnează o valoare booleană (sau Promise/Observable de una). Returnarea false blochează cererea cu un 403; puteți de asemenea arunca o excepție specifică (de ex. 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)
Guarzi pot fi aplicați la nivel de metodă, controller sau global.
@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
}
}
Combinarea unui decorator @Roles() (metadata) cu un guard care o citește (via Reflector) este modelul standard pentru control de acces bazat pe roluri.
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.
Guarzi sunt mecanismul dedicat și idiomativ NestJS pentru autorizare — controlul căreia cereri li se permite să ajungă la handleri pe baza autentificării și permisiunilor.
Înțelegerea lor este esențială deoarece practic fiecare aplicație reală trebuie să protejeze rutele (să necesite autentificare, să verifice roluri/permisiuni), iar guarzi sunt instrumentul corect pentru aceasta (mult mai curat decât comprimarea logicii de autentificare în middleware sau în fiecare handler).
Modelele standard — un guard JWT/autentificare care verifică credențialele și atașează utilizatorul la cerere, și guarzi bazați pe roluri combinând un decorator @Roles() cu un guard care citește cu Reflector pentru RBAC — sunt fundamentali pentru securizarea API-urilor NestJS.
Accesul guarzi la ExecutionContext bogat (știind handlerul țintă, clasa și cererea) este exact ceea ce le face potrivite pentru decizii de autorizare pe care middleware nu le poate face curat.
Cunoscerea cum să scrieți, aplicați (metodă/controller/global) și să combinați guarzi cu decoratori metadata este cunoaștere de bază pentru construirea aplicațiilor NestJS sigure și un subiect frecvent, important din punct de vedere arhitectural, în framework.