[元件] Interceptor

2026/5/1 發布

段落

架構
錯誤捕捉
部分套用
全域套用
小結
參考資料

interceptor 能取得上下文資訊來擴展邏輯，包含：

統一請求與回應的資料格式、空值處理
效能監控，例如每次請求的耗時
繞過 controller，回傳快取資料

架構

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

intercept 的參數：

ExecutionContext 繼承自 ArgumentsHost，可以取得執行環境的上下文
CallHandler 類似 middleware 的 NextFunction，必須回傳 next.handle() 才能運行流程

在 return 前的邏輯會在請求階段執行，在 next.handle() 串起來的 pipe 會在回應階段執行：

1
import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
2
import { Observable } from 'rxjs';
3

4
@Injectable()
5
export class TestInterceptor implements NestInterceptor {
6
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
7
    console.log('請求階段的 TestInterceptor');
8

9
    return next.handle().pipe(
10
      map((data) => {
11
        console.log('回傳 Data: ', data);
12
        console.log('回傳階段的 TestInterceptor');
13
        return data;
14
      }),
15
    );
16
  }

利用 context 取得的資料，就可以在 pipe 中重組回應物件的格式：

1
@Injectable()
2
export class TestInterceptor implements NestInterceptor {
3
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4
    const ctx = context.switchToHttp();
5
    const response = ctx.getResponse<Response>();
6
    const status = response.statusCode;
7
    const reqTime = new Date();
8

9
    console.log(`TestInterceptor 在 ${reqTime.toISOString()} 攔截了請求`);
10

11
    return next.handle().pipe(
12
      map((data) => {
13
        const resTime = new Date();
14
        const duration = resTime.getTime() - reqTime.getTime();
15
        console.log(`TestInterceptor 在 ${resTime.toISOString()} 回傳了請求`);
16
        console.log(`請求總耗時：${duration} ms`);
17

18
        return {
19
          data,
20
          status,
21
          duration,
22
        };
23
      }),
24
    );
25
  }
26
}

錯誤捕捉

資料格式的轉換也包含錯誤捕捉。

pipe 有提供 catchError 可以讀取 Error 物件，將特定的錯誤轉換後再拋給 exception filter 處理：

1
@Injectable()
2
export class ErrorsInterceptor implements NestInterceptor {
3
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
4
    return next.handle().pipe(
5
      catchError((err) => {
6
        // 1. 判斷是否為特定的業務邏輯錯誤（例如 TypeORM 的 EntityNotFound）
7
        if (err.name === 'EntityNotFoundError') {
8
          return throwError(() => new NotFoundException('找不到該筆資料'));
9
        }
10

11
        // 2. 也可以在這裡進行錯誤日誌記錄
12
        console.error('偵測到未處理錯誤:', err.message);
13

14
        // 3. 繼續拋出錯誤，讓後續的 exception filter 處理
15
        return throwError(() => new InternalServerErrorException('伺服器內部錯誤'));
16
      }),
17
    );
18
  }
19
}

部分套用

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

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

1
@UseInterceptors(TestInterceptor)
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_INTERCEPTOR,
8
      useClass: TestInterceptor,
9
    },
10
  ],
11
})
12
export class AppModule {}

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

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

小結

interceptor 透過 RxJS 包裝了 controller 的執行前後的作業流程，通常用來處理涉及業務邏輯或需要回傳值的情境。

參考資料

Interceptor