Guards huamua iwapo request inaruhusiwa kuendelea kwenda kwa route handler — ndizo utaratibu maalum wa NestJS kwa authorization (na mara nyingi ukaguzi wa authentication). Guard hurudisha true kuruhusu request au false/hutupa kuzuia.
@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 hutekeleza canActivate(), ambayo hurudisha boolean (au Promise/Observable ya boolean). Kurudisha false huzuia request kwa 403; pia unaweza kutupa exception mahususi (mfano 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 zinaweza kutumika katika kiwango cha method, controller, au 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
}
}
Kuunganisha decorator ya @Roles() (metadata) na guard inayoisoma (kupitia Reflector) ndio muundo wa kawaida wa 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 ni utaratibu maalum, wa kawaida wa NestJS kwa authorization — kudhibiti requests gani zinaruhusiwa kufika kwa handlers kulingana na authentication na ruhusa.
Kuzielewa ni muhimu kwa sababu karibu kila programu halisi inahitaji kulinda routes (kuhitaji login, kukagua roles/permissions), na guards ndio chombo sahihi kwa hili (safi zaidi kuliko kubana auth logic ndani ya middleware au kila handler).
Miundo ya kawaida — JWT/auth guard inayothibitisha credentials na kuambatanisha user kwenye request, na role-based guards zinazounganisha decorator ya @Roles() na guard inayosoma Reflector kwa RBAC — ni ya msingi kwa kulinda API za NestJS.
Ufikiaji wa guards kwa ExecutionContext tajiri (kujua handler lengwa, class, na request) ndio hasa unaozifanya kufaa kwa maamuzi ya authorization ambayo middleware haiwezi kufanya kwa usafi.
Kujua jinsi ya kuandika, kutumia (method/controller/global), na kuunganisha guards na metadata decorators ni maarifa ya msingi kwa kujenga programu za NestJS salama na ni eneo linalojitokeza mara kwa mara, lenye umuhimu wa kiusanifu katika framework hii.