Tiếp tục với series, ProjectsModule ở bài trước vẫn chưa nhận được request nào. Bài này mình sẽ giới thiệu với mọi người về controller và route trong NestJS, và viết ProjectsController đầu tiên với dữ liệu mẫu lưu trong bộ nhớ.
1. Controller là gì?
Controller là class gắn decorator
@Controller(), có nhiệm vụ nhận request và trả response về cho client.
Mỗi method trong controller gắn một decorator HTTP method (@Get(), @Post()...) là một route handler. Từ các decorator này, NestJS biết request nào thì gọi method nào.
Các bạn tạo controller bằng Nest CLI:
nest g controller projects
# CREATE src/projects/projects.controller.spec.ts (509 bytes)
# CREATE src/projects/projects.controller.ts (105 bytes)
# UPDATE src/projects/projects.module.ts (185 bytes)
npm run format
CLI tạo controller trong thư mục src/projects và tự thêm nó vào mảng controllers của ProjectsModule. Controller chỉ hoạt động khi được khai báo trong một module như vậy.
Chuỗi 'projects' trong @Controller('projects') là tiền tố đường dẫn (path prefix): mọi route của controller sẽ bắt đầu bằng /projects, không phải lặp lại ở từng method.
2. Global prefix và versioning.
Mọi route của TaskFlow API sẽ nằm dưới /api/v1, cấu hình một lần trong main.ts:
app.setGlobalPrefix('api'): thêm tiền tố/apicho mọi route.app.enableVersioning(): bật versioning, cho phép nhiều phiên bản của một route cùng tồn tại.VersioningType.URIđặt phiên bản vào URL sau global prefix (/v1),defaultVersion: '1'áp cho route không tự khai báo phiên bản.
- src/main.ts
import { VersioningType } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module.js';
async function bootstrap() {
const app = await NestFactory.create(AppModule, {
routeConflictPolicy: { duplicate: 'error' },
routeResolutionStrategy: 'specificity',
});
app.setGlobalPrefix('api');
app.enableVersioning({
type: VersioningType.URI,
defaultVersion: '1',
});
await app.listen(process.env.PORT ?? 3000);
}
await bootstrap();
Hai option truyền vào NestFactory.create() mình sẽ giải thích ở phần 5. Lúc này route GET / của AppController chuyển thành GET /api/v1, còn http://localhost:3000 trả về 404:
curl http://localhost:3000/api/v1
# Xin chào TaskFlow API!
Khi cần đổi cấu trúc response mà vẫn giữ client cũ, các bạn thêm route phiên bản mới bằng @Version('2') trên method, phiên bản 1 vẫn chạy song song. Ngoài URI còn có versioning qua header hay Accept, xem thêm tại đây.
3. Route và HTTP method.
Mỗi HTTP method có một decorator: @Get(), @Post(), @Put(), @Patch(), @Delete(), @Options(), @Head(), @QueryMethod() (QUERY), @All() (mọi method). Đường dẫn đầy đủ của route = global prefix + version + tiền tố của controller + chuỗi truyền vào decorator.
VD: ProjectsController với các route xem danh sách, xem một project, tạo và xoá project:
- src/projects/projects.controller.ts
import {
Controller,
Delete,
Get,
Header,
HttpCode,
Param,
Post,
Redirect,
} from '@nestjs/common';
interface Project {
id: number;
name: string;
description: string;
ownerId: number;
}
@Controller('projects')
export class ProjectsController {
// Dữ liệu mẫu trong bộ nhớ, mất khi khởi động lại ứng dụng
private readonly projects: Project[] = [
{
id: 1,
name: 'Website toidicode.com',
description: 'Viết lại giao diện',
ownerId: 1,
},
{
id: 2,
name: 'TaskFlow API',
description: 'Học NestJS',
ownerId: 1,
},
];
private nextId = 3;
@Get()
findAll(): Project[] {
return this.projects;
}
@Get('latest')
@Redirect('/api/v1/projects', 302)
findLatest() {
const latest = this.projects.at(-1);
if (latest) {
return { url: `/api/v1/projects/${latest.id}` };
}
}
@Get(':id')
findOne(@Param('id') id: string): Project | undefined {
return this.projects.find((project) => project.id === Number(id));
}
@Post()
@Header('Cache-Control', 'no-store')
create(): Project {
const id = this.nextId++;
const project: Project = {
id,
name: `Project ${id}`,
description: '',
ownerId: 1,
};
this.projects.push(project);
return project;
}
@Delete(':id')
@HttpCode(204)
remove(@Param('id') id: string): void {
const index = this.projects.findIndex(
(project) => project.id === Number(id),
);
if (index !== -1) {
this.projects.splice(index, 1);
}
}
}
Trong đó:
@Get()trênfindAll()tạo routeGET /api/v1/projects.':id'là route param: phần động của URL, khớp với/projects/1,/projects/2...@Param('id')lấy giá trị đó ra, luôn là chuỗi nên mình dùngNumber(id)để so sánh. Các decorator lấy dữ liệu request mình sẽ nói kỹ ở Bài 7.- Handler trả về object hay mảng thì NestJS tự chuyển thành JSON, trả về chuỗi hay số thì gửi nguyên giá trị.
create()tạm thời tạo project với tên cố định, đọc dữ liệu từ body request là nội dung của Bài 7. Dữ liệu nằm trong bộ nhớ, khởi động lại là trở về hai project mẫu.
Chạy npm run start và gọi thử:
curl http://localhost:3000/api/v1/projects
# [{"id":1,"name":"Website toidicode.com","description":"Viết lại giao diện","ownerId":1},{"id":2,"name":"TaskFlow API","description":"Học NestJS","ownerId":1}]
curl http://localhost:3000/api/v1/projects/2
# {"id":2,"name":"TaskFlow API","description":"Học NestJS","ownerId":1}
Lưu ý: Với id không tồn tại (VD /projects/9), findOne() trả về undefined và client nhận status 200 với body rỗng. Trả về lỗi 404 đúng chuẩn mình sẽ làm ở Bài 10.
4. Status code, header và redirect.
Mặc định response có status 200, riêng POST là 201. Muốn đổi thì gắn @HttpCode() lên handler như remove(), muốn thêm header thì dùng @Header(name, value) như create():
curl -i -X POST http://localhost:3000/api/v1/projects
# HTTP/1.1 201 Created
# ...
# Cache-Control: no-store
# ...
# {"id":3,"name":"Project 3","description":"","ownerId":1}
curl -i -X DELETE http://localhost:3000/api/v1/projects/3
# HTTP/1.1 204 No Content
# ...
Để chuyển hướng (redirect), các bạn dùng @Redirect(url, statusCode), statusCode mặc định là 302. Nếu handler trả về object { url } thì giá trị đó ghi đè tham số của decorator, nhờ vậy findLatest() chuyển hướng tới project mới nhất (không còn project nào thì về danh sách):
curl -i http://localhost:3000/api/v1/projects/latest
# HTTP/1.1 302 Found
# ...
# Location: /api/v1/projects/2
# ...
5. Thứ tự route và routeConflictPolicy.
Với Express (adapter mặc định), route khai báo trước được so khớp trước. Nếu đặt @Get(':id') lên trên @Get('latest') thì :id khớp luôn chữ latest: request /projects/latest rơi vào findOne() mà ứng dụng không hề cảnh báo. Vì vậy nên khai báo route tĩnh trước route có param.
NestJS 12 thêm hai option cho NestFactory.create() để xử lý vấn đề này:
routeConflictPolicy: kiểm tra xung đột route khi khởi động, nhận'off'(mặc định),'warn'hoặc'error'cho từng loại.duplicatelà hai route trùng hẳn method, path (và host, version);shadowlà hai route cùng có thể khớp một request, như/projects/latestvà/projects/:id.routeResolutionStrategy: 'specificity': đăng ký route cụ thể trước (đoạn tĩnh trước param, param trước wildcard), không phụ thuộc thứ tự khai báo. Mặc định là'declaration'.
Với thứ tự sai ở trên, chưa bật 'specificity' và có shadow: 'warn', log khởi động báo:
WARN [NestApplication] Route GET /api/v1/projects/latest (ProjectsController#findLatest) is shadowed by GET /api/v1/projects/:id (ProjectsController#findOne). The first-registered route will match all matching requests on order-sensitive adapters.
shadow báo cho mọi cặp route chồng nhau, kể cả khi thứ tự đã đúng, nên mình chỉ bật nó khi cần kiểm tra. TaskFlow API dùng 'specificity' và duplicate: 'error' như trong main.ts ở phần 2.
VD: Thử thêm một method findById() cũng gắn @Get(':id') vào ProjectsController, ứng dụng dừng ngay khi khởi động:
RouteConflictException [Error]: Conflicting HTTP routes detected:
- Duplicate route: GET /api/v1/projects/:id is registered by both ProjectsController#findOne and ProjectsController#findById.
...
Thử xong các bạn xoá method findById() đi nhé.
6. Lời kết.
Như vậy mình đã giới thiệu với mọi người về controller và route trong NestJS: các decorator HTTP method, route param, status code, header, redirect, global prefix, versioning và routeConflictPolicy mới ở NestJS 12. Bài sau mình sẽ giới thiệu về provider và dependency injection, chuyển dữ liệu mẫu từ controller sang ProjectsService.
Đă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