[元件] Guard

2026/5/2 發布

段落

架構
部分套用
全域套用
小結
參考資料

guard 會在 interceptor 前執行，通常會使用上下文來進行條件判斷，不符條件的請求就會被擋下。

架構

canActivate 是元件實際會執行的內容。

同 interceptor，可以透過 ExecutionContext 取得執行環境的上下文。

回傳值可以是 Promise 或 Observable，所以 guard 的程序可以是非同步的，程序會鎖在這裡，直到 NestJS 處理這些回傳值，取得 boolean，才會決定是否進行這個請求：

1
@Injectable()
2
export class TestAuthGuard implements CanActivate {
3
  canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
4
    return true;
5
  }
6
}

利用 context 取得的資料進行條件判斷：

1
@Injectable()
2
export class TestAuthGuard implements CanActivate {
3
  canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
4
    const ctx = context.switchToHttp();
5
    const request = ctx.getRequest<Request>();
6
    const auth = request.headers.authorization;
7
    const mockToken = 'Bearer TEST';
8

9
    return auth === mockToken;
10
  }
11
}

部分套用

使用 @UseGuards 套用在 handler 或是整個 controller：

1
@Get('/:id')
2
@UseGuards(TestAuthGuard)
3
testId(@Param('id') id: string) {
4
  return `test ${id}`;
5
}

1
@UseGuards(TestAuthGuard)
2
@Controller('test')
3
export class TestController {
4
  //...
5
}

全域套用

在根模組進行注入：

1
import { APP_INTERCEPTOR } from '@nest/core';
2

3
@Module({
4
  controllers: [AppController],
5
  providers: [
6
    {
7
      provide: APP_GUARD,
8
      useClass: TestAuthGuard,
9
    },
10
  ],
11
})
12
export class AppModule {}

或是在啟動程序裡面呼叫 useGlobalGuards 並傳入實例：

1
async function bootstrap() {
2
  const app = await NestFactory.create(AppModule);
3
  // 建立實例
4
  app.useGlobalGuards(new TestAuthGuard());
5
  await app.listen(process.env.PORT ?? 3000);
6
}

小結

其他元件都可以透過拋出 exception 的方式中斷請求，但中斷的原因是依元件的職責而有所不同。

Guard 的主要職責是過濾權限的問題，例如 token、RBAC 等驗證。

參考資料

Guard