Tiếp tục với series, ở bài trước chúng ta đã dùng hai pipe có sẵn để kiểm tra dữ liệu, nhưng id trên URL vẫn được chuyển bằng Number() trong controller, gọi /projects/abc vẫn nhận 200 với body rỗng. Bài này mình sẽ giới thiệu với mọi người về pipe trong NestJS: các pipe có sẵn, cách tự viết pipe và phạm vi áp dụng của pipe.
1. Pipe là gì?
Pipe là một class có
@Injectable()và cài đặt interfacePipeTransform, chạy ngay trước route handler để xử lý từng tham số của handler.
Pipe có hai công dụng:
- Transformation (chuyển đổi): đổi dữ liệu sang dạng mong muốn, VD từ chuỗi
"2"sang số2. - Validation (kiểm tra): dữ liệu hợp lệ thì cho qua, không hợp lệ thì ném exception.
Khi pipe ném exception, route handler không được gọi và client nhận lỗi (mặc định 400 Bad Request). Ngoài ValidationPipe và StandardSchemaValidationPipe đã dùng ở Bài 8, @nestjs/common còn có sẵn các pipe Parse* và DefaultValuePipe.
2. ParseIntPipe.
ParseIntPipe chuyển tham số sang số nguyên, không chuyển được thì trả lỗi. Các bạn gắn pipe làm tham số thứ hai của @Param() (hay @Query(), @Body()):
@Param('id', ParseIntPipe) id: number
Các bạn để ý: TaskFlow API đã bật transform: true cho ValidationPipe toàn cục ở Bài 8, nên chỉ cần khai báo @Param('id') id: number là id đã thành số. Nhưng với /projects/abc, id nhận NaN và handler vẫn chạy bình thường. Pipe toàn cục chạy trước pipe gắn trên tham số, nên khi thêm ParseIntPipe, nó nhận NaN và trả lỗi 400.
- src/projects/projects.controller.ts (đoạn trích, thêm ParseIntPipe vào import từ @nestjs/common)
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number): Project | undefined {
return this.projectsService.findOne(id);
}
Các bạn sửa tương tự cho update() và remove(). Giờ /projects/abc hay /projects/1.5 đều nhận lỗi:
curl http://localhost:3000/api/v1/projects/abc
# {"message":"Validation failed (numeric string is expected)","error":"Bad Request","statusCode":400}
Ở trên mình truyền class ParseIntPipe, NestJS sẽ tự tạo instance (và inject dependency nếu có). Muốn tuỳ chỉnh thì truyền instance kèm option, VD đổi status code khi lỗi:
@Param(
'id',
new ParseIntPipe({
errorHttpStatusCode: HttpStatus.NOT_ACCEPTABLE,
}),
)
id: number,
// {"message":"Validation failed (numeric string is expected)","error":"Not Acceptable","statusCode":406}
Lưu ý: Do transform: true chạy trước, các Parse* pipe nhận giá trị đã được chuyển kiểu. VD @Query('done', ParseBoolPipe) done: boolean với ?done=yes sẽ nhận false chứ không báo lỗi, vì ValidationPipe đã đổi "yes" thành false.
3. ParseUUIDPipe, DefaultValuePipe và các pipe khác.
ParseUUIDPipe kiểm tra tham số có phải UUID hay không (không chuyển kiểu, kết quả vẫn là chuỗi). Mặc định nó chấp nhận mọi version, option version giới hạn một version cụ thể. VD (minh hoạ, id của TaskFlow API là số): Thêm vào ProjectsController (và ParseUUIDPipe vào import) rồi xoá đi. Route riêng uuid/:uuid để không đè lên :id:
@Get('uuid/:uuid')
findByUuid(
@Param('uuid', new ParseUUIDPipe({ version: '4' })) uuid: string,
) {
return { uuid };
}
// GET /api/v1/projects/uuid/abc -> {"message":"Validation failed (uuid v 4 is expected)","error":"Bad Request","statusCode":400}
Parse* pipe báo lỗi khi tham số không có giá trị. Với query không bắt buộc, các bạn đặt DefaultValuePipe lên trước để gán giá trị mặc định. VD: Thêm ?limit cho GET /projects (minh hoạ, thêm DefaultValuePipe và ParseIntPipe vào import):
@Get()
findAll(
@Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number,
@Query('search', { schema: z.string().trim().max(50).optional() })
search?: string,
): Project[] {
return this.projectsService.findAll(search).slice(0, limit);
}
curl "http://localhost:3000/api/v1/projects?limit=1"
# [{"id":1,"name":"Website toidicode.com","description":"Viết lại giao diện","ownerId":1}]
Không gửi limit thì nhận 10 và trả về cả hai project. DefaultValuePipe cũng thay NaN bằng giá trị mặc định, nên với transform: true thì ?limit=abc cũng nhận 10 thay vì lỗi. Thử xong các bạn bỏ limit đi nhé (phân trang ở Bài 18).
Các pipe còn lại dùng theo cùng cách: ParseFloatPipe (số thực), ParseBoolPipe ("true"/"false"), ParseEnumPipe (giá trị thuộc một enum), ParseArrayPipe (chuỗi "1,2,3" thành mảng), ParseDatePipe (chuỗi ngày thành Date). ParseFilePipe dùng cho upload file ở Bài 22.
4. Tự viết pipe.
ParseIntPipe vẫn cho qua 0 và -1, trong khi id của TaskFlow API luôn là số nguyên dương. Mình sẽ tự viết ParseIdPipe:
nest g pipe common/pipes/parse-id --no-spec --flat --format
# CREATE src/common/pipes/parse-id.pipe.ts (231 bytes)
- src/common/pipes/parse-id.pipe.ts
import {
ArgumentMetadata,
BadRequestException,
Injectable,
PipeTransform,
} from '@nestjs/common';
@Injectable()
export class ParseIdPipe implements PipeTransform<unknown, number> {
transform(value: unknown, metadata: ArgumentMetadata): number {
const id = Number(value);
if (!Number.isInteger(id) || id < 1) {
throw new BadRequestException(
`${metadata.data} phải là số nguyên dương`,
);
}
return id;
}
}
Trong đó:
PipeTransform<T, R>: interface mọi pipe phải cài đặt,Tlà kiểu dữ liệu vào,Rlà kiểu trả về củatransform().value: giá trị của tham số đang xử lý. Ở đây nó có thể đã là số (hoặcNaN) dotransform: true, nên mình khai báounknownvà luôn gọiNumber().metadata: thông tin về tham số, gồmtype('body','query','param'hoặc'custom'),metatype(kiểu khai báo, VDNumber),data(key truyền vào decorator, ở đây là'id') vàschema.- Giá trị
transform()trả về sẽ thay cho giá trị cũ, handler nhận giá trị này.
Sau đó các bạn thay ParseIntPipe bằng ParseIdPipe ở cả ba route có :id (xoá ParseIntPipe khỏi import):
- src/projects/projects.controller.ts (đoạn trích)
import { ParseIdPipe } from '../common/pipes/parse-id.pipe.js';
// ...
@Get(':id')
findOne(@Param('id', ParseIdPipe) id: number): Project | undefined {
return this.projectsService.findOne(id);
}
@Patch(':id')
update(
@Param('id', ParseIdPipe) id: number,
@Body() updateProjectDto: UpdateProjectDto,
): Project | undefined {
return this.projectsService.update(id, updateProjectDto);
}
@Delete(':id')
@HttpCode(204)
remove(@Param('id', ParseIdPipe) id: number): void {
this.projectsService.remove(id);
}
curl http://localhost:3000/api/v1/projects/0
# {"message":"id phải là số nguyên dương","error":"Bad Request","statusCode":400}
curl http://localhost:3000/api/v1/projects/2
# {"id":2,"name":"TaskFlow API","description":"Học NestJS","ownerId":1}
5. Phạm vi áp dụng pipe.
Pipe gắn được ở bốn cấp:
- Tham số:
@Param('id', ParseIdPipe)như trên, chỉ chạy cho tham số đó. - Method:
@UsePipes(ParseIdPipe)đặt trên route handler, chạy cho mọi tham số của handler. - Controller:
@UsePipes(...)đặt trên class, chạy cho mọi tham số của mọi handler trong controller. - Toàn cục:
app.useGlobalPipes(...)trongmain.tsnhư Bài 8.
Thứ tự chạy là toàn cục, controller, method rồi mới đến tham số. Pipe cấp method và controller nhận tất cả tham số nên chỉ hợp với pipe tổng quát như ValidationPipe. VD đặt @UsePipes(ParseIdPipe) lên update() thì body cũng bị đưa qua ParseIdPipe:
curl -X PATCH http://localhost:3000/api/v1/projects/2 \
-H 'Content-Type: application/json' \
-d '{"name":"A"}'
# {"message":"undefined phải là số nguyên dương","error":"Bad Request","statusCode":400}
Pipe đăng ký bằng useGlobalPipes() nằm ngoài mọi module nên không inject được dependency. Nếu pipe toàn cục cần DI, các bạn đăng ký nó như một provider với token APP_PIPE (đoạn trích của app.module.ts):
import { ValidationPipe } from '@nestjs/common';
import { APP_PIPE } from '@nestjs/core';
// ...
providers: [AppService, { provide: APP_PIPE, useClass: ValidationPipe }],
TaskFlow API vẫn giữ useGlobalPipes() trong main.ts vì hai pipe hiện tại không cần DI.
6. Lời kết.
Như vậy mình đã giới thiệu với mọi người về pipe trong NestJS: các pipe có sẵn, cách tự viết pipe với PipeTransform và bốn cấp áp dụng pipe. Hiện tại /projects/99 vẫn trả về 200 với body rỗng, bài sau mình sẽ giới thiệu về exception filter và xử lý lỗi trong NestJS để trả về 404 cùng một định dạng lỗi thống nhất cho cả 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!





0 Comments