Guards تحدد ما إذا كان الطلب مسموحًا بالمتابعة إلى معالج المسار — وهي آلية NestJS المخصصة للـ authorization (وغالبًا فحوصات المصادقة). يُرجع Guard القيمة true للسماح بالطلب أو false/رفع استثناء لحجبه.
()
{
(: ): {
request = context.().();
!!request..;
}
}
يُنفذ Guard واجهة canActivate()، التي تُرجع قيمة boolean (أو 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() (metadata) و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 للـ authorization — التحكم في الطلبات المسموحة بالوصول إلى المعالجات بناءً على المصادقة والصلاحيات.
فهمها ضروري لأن كل تطبيق حقيقي تقريبًا يحتاج لحماية المسارات (طلب تسجيل الدخول، التحقق من الأدوار/الصلاحيات)، وGuards هي الأداة الصحيحة لهذا (أنظف بكثير من حشر منطق المصادقة في middleware أو كل معالج).
الأنماط القياسية — guard JWT/مصادقة يتحقق من بيانات الاعتماد ويرفق المستخدم بالطلب، وguards قائمة على الأدوار تجمع بين مزخرف @Roles() وguard يقرأ Reflector للـ RBAC — أساسية لتأمين APIs في NestJS.
وصول Guards إلى ExecutionContext الغني (معرفة معالج الهدف والفئة والطلب) هو بالضبط ما يجعلها مناسبة لقرارات التفويض التي لا يمكن للـ middleware أن تتخذها بنظافة.
معرفة كيفية كتابة وتطبيق (method/controller/global) ودمج Guards مع مزخرفات metadata هي معرفة أساسية لبناء تطبيقات NestJS آمنة وموضوع متكرر ومهم معماريًا في الإطار.