Kiến trúc NestJS: Hướng dẫn tổ chức mã nguồn chuẩn Senior

NestJS đã trở thành framework backend hàng đầu cho hệ sinh thái Node.js nhờ cấu trúc module chặt chẽ và khả năng tương thích tuyệt vời với TypeScript. Tuy nhiên, nếu không có quy chuẩn thiết kế từ đầu, dự án rất dễ rơi vào tình trạng “mỳ spaghetti”.

Trong bài viết này, mình sẽ chia sẻ cách tổ chức cấu trúc thư mục NestJS giúp dự án dễ bảo trì và mở rộng.

1. Cấu trúc thư mục đề xuất

Dưới đây là sơ đồ cấu trúc thư mục chuẩn cho một dự án NestJS ở quy mô vừa và lớn:

src/
├── common/             # Các thành phần dùng chung (guards, interceptors, filters)
│   ├── decorators/
│   ├── dto/
│   ├── filters/
│   └── interceptors/
├── config/             # Cấu hình môi trường (env)
├── database/           # Quản lý migration và seed dữ liệu
├── modules/            # Các Business Module riêng biệt
│   ├── users/
│   │   ├── dto/
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── users.module.ts
│   └── auth/
├── app.module.ts
└── main.ts

2. Nguyên tắc Module khép kín (Encapsulated Modules)

Mỗi module trong thư mục modules/ nên tự chịu trách nhiệm về một domain cụ thể.

Không import chéo dịch vụ một cách tùy tiện: Nếu AuthService cần dùng UsersService, hãy đảm bảo UsersModule đã exports: [UsersService] và AuthModule đã imports: [UsersModule].
Tránh Module tuần hoàn (Circular Dependency): Nếu xảy ra vòng lặp import giữa hai module, hãy dùng forwardRef() của NestJS hoặc tốt hơn là tách logic dùng chung ra một module thứ ba.

3. Quản lý Config an toàn bằng ConfigService

Không bao giờ sử dụng trực tiếp process.env.DB_HOST trong code. Hãy đóng gói cấu hình thông qua @nestjs/config và kiểm thử kiểu dữ liệu bằng thư viện validation như joi hoặc zod.

Chúc các bạn xây dựng những hệ thống NestJS vững chắc!