[元件] Middleware

2026/4/30 發布

段落

class middleware
部分套用
全域套用
限制路由
小結
參考資料

功能同 Express 的 middleware，可以存取請求物件、回應物件，並透過 next 繼續運行流程。

本篇主要介紹 class middleware（functional middleware 同 Express 就不多介紹）。

class middleware

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

CLI 產生的初始架構中 req 與 res 是 any，要自行替換成專案目前使用的底層 HTTP 框架（Express 或 Fastify）的型別：

1
import { Injectable, NestMiddleware } from '@nestjs/common';
2
import { Request, Response, NextFunction } from 'express';
3

4
@Injectable()
5
export class TestLoggerMiddleware implements NestMiddleware {
6
  use(req: Request, res: Response, next: NextFunction) {
7
    const method = req.method;
8
    const resource = req.originalUrl;
9

10
    console.log(`這是 ${method} ${resource} 觸發的 TestLoggerMiddleware`);
11

12
    next();
13
  }
14
}

部分套用

middleware 需要在 module 元件中設定好哪些路由的請求會觸發。

在 forRoutes 填入要匹配的路由：

1
@Module({
2
  imports: [TestModule],
3
  controllers: [AppController, TestController],
4
  providers: [AppService],
5
})
6
export class AppModule implements NestModule {
7
  configure(consumer: MiddlewareConsumer) {
8
    consumer.apply(TestLoggerMiddleware).forRoutes('/test');
9
  }
10
}

資訊

根據 middleware 的功能來決定要在哪個 module 底下套用即可。全域性質的功能通常都統整在根模組。

也可以直接指定某個 controller 下面的所有路由：

1
consumer.apply(TestLoggerMiddleware).forRoutes(TestController);

可以傳入多個 middleware，會依照順序執行：

1
consumer.apply(TestLoggerMiddleware, SayHelloMiddleware).forRoutes('/test');

全域套用

forRoutes 傳入 '*' 匹配全部的路由，讓所有請求都執行：

1
consumer.apply(TestLoggerMiddleware).forRoutes('*');

或是在啟動程序中透過 app.use 傳入 middleware，但這個做法僅限 functional middleware：

1
async function bootstrap() {
2
  const app = await NestFactory.create(AppModule);
3
  app.use(TestLoggerMiddleware);
4
  await app.listen(process.env.PORT ?? 3000);
5
}

限制路由

forRoutes 可以設定更嚴格的匹配規則，例如請求必須是 GET 方法才執行：

1
consumer.apply(TestLoggerMiddleware).forRoutes(
2
  {
3
    path: '/test',
4
    method: RequestMethod.GET,
5
  },
6
  {
7
    path: '/qq',
8
    method: RequestMethod.GET,
9
  },
10
);

也可以串上 exclude 排除特定路由：

1
consumer
2
  .apply(TestLoggerMiddleware)
3
  .exclude({
4
    path: '/qq',
5
    method: RequestMethod.GET,
6
  })
7
  .forRoutes('/test');

小結

middleware 僅能存取基本的請求、回應物件，適合處理與業務邏輯無關的底層需求：

日誌記錄 (Logging)：記錄所有進入伺服器的 HTTP 請求基本資訊
請求預處理：例如解析 Cookie、處理特定的 Header 或執行 body-parser
跨域處理 (CORS)：設定請求來源許可

參考資料

Middleware