Toidicode.com

Toidicode.com

BASIC TO ADVANCE

Bài 11: Middleware trong NestJS

Tiếp tục với series, ở bài trước TaskFlow API đã có định dạng lỗi chung, nhưng khi chạy ứng dụng chúng ta vẫn chưa biết request nào vừa gọi đến và mất bao lâu. Bài này mình sẽ giới thiệu với mọi người về middleware trong NestJS và viết một middleware ghi log mọi request gửi đến API.

1. Middleware là gì?

Middleware là một hàm được gọi trước route handler, có quyền truy cập request, response và hàm next() để chuyển request sang bước tiếp theo.

Mặc định NestJS chạy trên Express nên middleware của NestJS chính là middleware của Express. Một middleware có thể:

  • Chạy code bất kỳ, VD ghi log, đo thời gian.
  • Thay đổi request, response, VD thêm header.
  • Kết thúc luôn request (trả response hoặc ném exception).
  • Gọi next() để chuyển sang middleware tiếp theo hoặc route handler. Nếu không kết thúc request mà cũng quên gọi next() thì request sẽ bị treo.

Middleware chạy đầu tiên, trước cả pipe mà chúng ta đã học ở Bài 9 (thứ tự đầy đủ mình sẽ nói ở Bài 13).

2. Tạo middleware dạng class.

Middleware dạng class là class có @Injectable() và cài đặt interface NestMiddleware. Các bạn tạo nó bằng Nest CLI:

nest g middleware common/middleware/logger --no-spec --flat --format
# CREATE src/common/middleware/logger.middleware.ts (206 bytes)

Mình sửa lại để in ra method, đường dẫn, status code và thời gian xử lý của mỗi request:

- src/common/middleware/logger.middleware.ts

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

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
    use(req: Request, res: Response, next: NextFunction): void {
        const start = Date.now();
        // Sự kiện 'finish' chạy khi response đã gửi xong
        res.on('finish', () => {
            const duration = Date.now() - start;
            console.log(
                `${req.method} ${req.originalUrl} ${res.statusCode} - ${duration}ms`,
            );
        });
        next();
    }
}

Trong đó:

  • use(req, res, next): method bắt buộc của NestMiddleware, nhận Request, Response của Express và hàm next.
  • Lúc middleware chạy thì chưa có status code, nên mình ghi log trong sự kiện finish của response.
  • req.originalUrl: đường dẫn đầy đủ, giống filter ở Bài 10. req.url trong middleware có thể bị Express cắt bớt, VD khi áp dụng cho 'projects' ở phần 3 thì /api/v1/projects/2 chỉ còn /2.

Middleware dạng class hỗ trợ dependency injection như provider: các bạn inject service qua constructor, miễn service đó dùng được trong module đăng ký middleware.

3. Áp dụng middleware với MiddlewareConsumer.

Middleware không khai báo trong @Module(). Module muốn dùng middleware phải cài đặt interface NestModule và đăng ký trong method configure() thông qua MiddlewareConsumer:

- src/app.module.ts

import { MiddlewareConsumer, Module, NestModule } from '@nestjs/common';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';
import { LoggerMiddleware } from './common/middleware/logger.middleware.js';
import { ProjectsModule } from './projects/projects.module.js';
import { TasksModule } from './tasks/tasks.module.js';

@Module({
    imports: [ProjectsModule, TasksModule],
    controllers: [AppController],
    providers: [AppService],
})
export class AppModule implements NestModule {
    configure(consumer: MiddlewareConsumer): void {
        consumer.apply(LoggerMiddleware).forRoutes('projects');
    }
}

apply() nhận middleware, forRoutes() chọn route áp dụng. Đường dẫn ghi không có global prefix và version, NestJS tự thêm /api/v1 (Bài 5). Với Express, chuỗi 'projects' khớp cả các đường dẫn con như /projects/99:

curl http://localhost:3000/api/v1
curl http://localhost:3000/api/v1/projects
curl http://localhost:3000/api/v1/projects/99

# Terminal chạy ứng dụng (GET /api/v1 không có log):
# GET /api/v1/projects 200 - 5ms
# GET /api/v1/projects/99 404 - 3ms

Ngoài chuỗi, forRoutes() còn nhận:

  • Object RouteInfo để giới hạn method: forRoutes({ path: 'projects', method: RequestMethod.POST }) (RequestMethod import từ @nestjs/common).
  • Một hoặc nhiều controller: forRoutes(ProjectsController), áp dụng cho mọi route của controller.
  • Wildcard: '*splat' khớp mọi route (splat chỉ là tên, đặt tên khác cũng được). Ghi '*' như phiên bản cũ thì NestJS vẫn tự chuyển nhưng in cảnh báo Unsupported route path.

4. Loại trừ route với exclude().

Mình muốn ghi log mọi route, trừ route chào mừng GET /api/v1 (thường dùng để kiểm tra server còn chạy). Các bạn dùng exclude() trước forRoutes(), nó nhận chuỗi hoặc RouteInfo:

- src/app.module.ts (đoạn trích, thêm RequestMethod vào import từ @nestjs/common)

configure(consumer: MiddlewareConsumer): void {
    consumer
        .apply(LoggerMiddleware)
        .exclude({ path: '/', method: RequestMethod.GET, version: '1' })
        .forRoutes('*splat');
}

Chú ý: TaskFlow API dùng versioning URI, mình thử với NestJS 12.5.0 thì exclude() chỉ có tác dụng khi ghi rõ version: '1'. Thiếu nó thì route vẫn bị ghi log, dù forRoutes() không cần ghi version.

curl http://localhost:3000/api/v1
curl http://localhost:3000/api/v1/projects
curl http://localhost:3000/api/v1/abc

# Terminal chạy ứng dụng:
# GET /api/v1/projects 200 - 5ms
# GET /api/v1/abc 404 - 2ms

Route không tồn tại (dưới /api/v1) cũng được ghi log, rất tiện khi tìm lỗi client gọi sai đường dẫn.

5. Functional middleware và global middleware.

Middleware không cần dependency có thể viết dạng hàm, gọi là functional middleware. VD: Gắn header X-Request-Id ngẫu nhiên vào mọi response để client báo lỗi kèm mã này (tạo file bằng nest g middleware common/middleware/request-id --no-spec --flat --format rồi thay nội dung):

- src/common/middleware/request-id.middleware.ts

import { randomUUID } from 'node:crypto';
import type { NextFunction, Request, Response } from 'express';

export function requestId(
    req: Request,
    res: Response,
    next: NextFunction,
): void {
    res.setHeader('X-Request-Id', randomUUID());
    next();
}

Hàm này dùng được với consumer.apply(requestId), apply() cũng nhận nhiều middleware chạy lần lượt: apply(requestId, LoggerMiddleware). Muốn áp dụng cho cả ứng dụng, các bạn đăng ký global middleware bằng app.use():

- src/main.ts (đoạn trích, ngay sau useGlobalFilters())

import { requestId } from './common/middleware/request-id.middleware.js';

// ...
    app.use(requestId);
curl -i http://localhost:3000/api/v1/projects/1
# HTTP/1.1 200 OK
# X-Powered-By: Express
# X-Request-Id: 1f500e04-fdff-43ad-88a3-d07079efa9f5
# ...

Hiện dòng log của LoggerMiddleware chưa in mã này nên chưa đối chiếu được với lỗi client báo về, ở Bài 26 (structured logging) mình sẽ đưa request id vào từng dòng log.

Middleware đăng ký bằng app.use() nằm ngoài mọi module nên không inject được dependency, vì vậy chỉ dùng functional middleware ở đây.

Lưu ý: Exception ném ra trong middleware chỉ được filter toàn cục xử lý, filter gắn bằng @UseFilters() trên controller không bắt được vì lúc đó chưa xác định route handler. AllExceptionsFilter của TaskFlow API là toàn cục nên lỗi từ middleware vẫn có định dạng chung.

6. So sánh với middleware trong Express.

Nếu đã học Express framework, các bạn sẽ thấy:

  • Giống nhau: cùng chữ ký (req, res, next), app.use() giống hệt Express. Các package middleware của Express như cors, helmet dùng thẳng được: consumer.apply(cors(), helmet()).
  • NestJS có thêm middleware dạng class với DI, và chọn route bằng forRoutes()/exclude() trong module thay vì gắn tay vào từng router.
  • Express xử lý lỗi bằng middleware 4 tham số (err, req, res, next), còn NestJS dùng exception filter. Việc kiểm tra quyền truy cập hay chuẩn hoá response thì NestJS có guard, interceptor riêng.

7. Lời kết.

Như vậy mình đã giới thiệu với mọi người về middleware trong NestJS: middleware dạng class và dạng hàm, áp dụng bằng MiddlewareConsumer với forRoutes(), exclude(), global middleware và so sánh với Express. Middleware không biết route handler nào sẽ chạy sau next(), nên bài sau mình sẽ giới thiệu về guard trong NestJS, công cụ phù hợp hơn để kiểm tra quyền truy cập, và viết một guard API key tạm cho TaskFlow API.

Đăng ký nhận tin.

Chúng tôi chỉ gửi tối đa 2 lần trên 1 tháng. Tuyên bố không spam mail!

Vũ Thanh Tài

About author
The best way to learn is to share
Xem tất cả bài đăng

0 Comments

Bài viết chưa có ai bình luận, hãy là người đầu tiên đi bạn!

Bình luận

Captcha