Guard'lar, bir isteğin route handler'a ilerlemesine izin verilip verilmeyeceğini belirler — bunlar NestJS'nin yetkilendirme (ve sıklıkla kimlik doğrulama kontrolleri) için özel mekanizmasıdır. Bir guard isteğe izin vermek için true döndürür veya false döndürür/istisna fırlatır.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = allow, false = block (403)
}
}
Bir guard canActivate() uygular; bu, bir boolean (veya bunun Promise/Observable) döndürür. false döndürmek isteği 403 ile bloke eder; belirli bir istisna fırlatabilirsiniz (örneğin 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)
Guard'lar method, controller veya global seviyede uygulanabilir.
@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
}
}
Bir @Roles() decorator'ünü (metadata) bunu okuyan bir guard ile birleştirmek (via Reflector) rol tabanlı erişim kontrolü için standart desendir.
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.
Guard'lar, yetkilendirme — hangi isteklerin kimlik doğrulama ve izinlere göre handler'lara ulaşmasına izin verildiğini kontrol etmek — için özel, idiyomatik NestJS mekanizmasıdır.
Bunları anlamak gereklidir çünkü pratik olarak her gerçek uygulamanın route'ları koruması gerekir (giriş gerektir, rol/izin kontrolleri), ve guard'lar bunun için doğru araçtır (middleware'e veya her handler'a auth mantığı sıkıştırmaktan çok daha temiz).
Standart desenler — kimlik bilgilerini doğrulayan ve kullanıcıyı isteğe bağlayan bir JWT/auth guard'ı ve RBAC için @Roles() decorator'ünü Reflector-okutan bir guard ile birleştiren rol tabanlı guard'lar — NestJS API'larını güvence altına almak için temeldir.
Guard'ların zengin ExecutionContext'e erişimi (hedef handler, sınıf ve isteği bilmek) tam olarak onları middleware'in temiz bir şekilde yapamayacağı yetkilendirme kararları için uygun kılan şeydir.
Guard'ları yazma, uygulama (method/controller/global) ve metadata decorator'ler ile birleştirme yolunu bilmek, güvenli NestJS uygulamaları oluşturmak için temel bilgidir ve framework'te sık görülen, mimaride önemli bir konudur.