Guard xác định xem một request có được phép tiếp tục đến route handler hay không — chúng là cơ chế chuyên dụng của NestJS cho phân quyền (authorization) (và thường cả kiểm tra xác thực). Một guard trả về true để cho phép request hoặc false/ném để chặn nó.
@Injectable()
export class AuthGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean {
const request = context.switchToHttp().getRequest();
return !!request.headers.authorization; // true = cho phép, false = chặn (403)
}
}
Một guard implement canActivate(), trả về một boolean (hoặc Promise/Observable của boolean). Trả về false chặn request với 403; bạn cũng có thể ném một exception cụ thể (vd. UnauthorizedException).
@UseGuards(AuthGuard) // trên một route đơn lẻ
@Get("profile")
getProfile() {}
@UseGuards(AuthGuard) // trên cả một controller (tất cả route)
@Controller("admin")
export class AdminController {}
app.useGlobalGuards(new AuthGuard()); // toàn cục (tất cả route)
Guard có thể được áp dụng ở cấp method, controller, hoặc toàn cục.
@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); // gắn user vào
return true;
} catch {
throw new UnauthorizedException("Invalid token");
}
}
}
// một decorator @Roles lưu các role yêu cầu dưới dạng metadata
@Roles("admin")
@Get("users")
listUsers() {}
// RolesGuard đọc metadata và kiểm tra role của user
@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)); // cho phép nếu user có role yêu cầu
}
}
Kết hợp một decorator @Roles() (metadata) với một guard đọc nó (qua Reflector) là pattern chuẩn cho kiểm soát truy cập dựa trên role (RBAC).
ExecutionContext cho guard thông tin phong phú (handler, class, request) — nhiều
hơn middleware thuần — đây là lý do guard (không phải middleware) là nơi đúng
cho các quyết định phân quyền.
Guard là cơ chế chuyên dụng, thành ngữ của NestJS cho phân quyền — kiểm soát request nào được phép đến handler dựa trên xác thực và quyền hạn.
Hiểu chúng là thiết yếu vì gần như mọi ứng dụng thực tế đều cần bảo vệ các route (yêu cầu đăng nhập, kiểm tra role/quyền), và guard là công cụ đúng đắn cho việc này (sạch sẽ hơn nhiều so với nhồi nhét logic auth vào middleware hoặc từng handler).
Các pattern chuẩn — một JWT/auth guard xác minh thông tin xác thực và gắn user vào request, và các guard dựa trên role kết hợp một decorator @Roles() với một guard đọc bằng Reflector cho RBAC — là nền tảng để bảo mật các API NestJS.
Quyền truy cập của guard vào ExecutionContext phong phú (biết handler, class, và request đích) chính là điều khiến chúng phù hợp với các quyết định phân quyền mà middleware không thể đưa ra một cách sạch sẽ.
Biết cách viết, áp dụng (method/controller/toàn cục), và kết hợp guard với các metadata decorator là kiến thức cốt lõi để xây dựng các ứng dụng NestJS an toàn và là một chủ đề thường gặp, quan trọng về mặt kiến trúc trong framework.