Nếu bạn đang làm API với Node.js thì xin chúc mừng, bạn đang viết nên “xương sống” của những ứng dụng mà người ta tin tưởng để lưu trữ dữ liệu, điều hành công việc, thậm chí là… cả cuộc đời họ nữa.
Chắc hẳn ai cũng từng rơi vào tình huống: deadline dí sát, vá lỗi tạm thời, endpoint rối như mớ bòng bong và rồi sau đó là… hậu quả đau đầu.
Nhưng tin vui là:
Bạn không cần phép thuật gì hết. Chỉ cần một checklist đơn giản – và thực tế.
Dưới đây là checklist mà bạn nên ghi nhớ, và dùng đi dùng lại mỗi khi viết API bằng Node.js:
1. Tổ chức dự án gọn gàng như chuyên gia
Thư mục lộn xộn = mã lộn xộn. Hãy tạo cấu trúc dễ mở rộng ngay từ đầu:
-
controllers/ — nơi xử lý logic nghiệp vụ
-
routes/ — định nghĩa các endpoint
-
services/ — thao tác dữ liệu hoặc gọi API bên ngoài
-
middlewares/ — xử lý xác thực, kiểm tra, validate...
-
models/ — định nghĩa schema cho database
-
utils/ — chứa các hàm tiện ích
Mẹo nhỏ: Cấu trúc càng "nhàm chán" càng tốt — vì dễ đoán và dễ tìm.
2. Validate mọi dữ liệu gửi vào
Đừng bao giờ tin tưởng dữ liệu client gửi lên. Ngay cả khi bạn đang tự test cũng vậy.
Dùng thư viện như Joi, Zod hoặc express-validator để validate:
-
Headers
-
Query params
-
Body
Ví dụ với Joi:
const Joi = require('joi'); const userSchema = Joi.object({ email: Joi.string().email().required(), password: Joi.string().min(8).required(),
});
3. Xử lý lỗi như người có tâm
-
Đừng để ứng dụng crash chỉ vì thiếu try/catch.
-
Dùng middleware để xử lý lỗi tập trung
-
Không để lộ stack trace hoặc thông tin nhạy cảm
-
Phân biệt rõ lỗi client (4xx) và lỗi server (5xx)
Ví dụ:
app.use((err, req, res, next) => { console.error(err); // Ghi log res.status(err.status || 500).json({ message: err.isOperational ? err.message : 'Có lỗi xảy ra, vui lòng thử lại.', });
});
4. Bảo mật API như két sắt ngân hàng
Bảo mật không phải chuyện “có thì tốt”, mà là “bắt buộc phải có”.
-
Helmet.js: Thiết lập HTTP headers an toàn
-
Rate limiting: Chống spam (dùng express-rate-limit)
-
CORS: Cấu hình nghiêm ngặt domain được phép truy cập
-
Authentication: Dùng JWT hoặc OAuth2 – đừng tự chế token
-
Sanitize dữ liệu: Tránh SQL injection, XSS (vd: xss-clean)
const helmet = require('helmet');
app.use(helmet());
5. Dùng biến môi trường (đúng cách)
Hardcode key/API secret trong mã nguồn là “tự rước họa”.
-
Dùng dotenv hoặc thư viện như convict để quản lý cấu hình
-
Đừng bao giờ push file .env lên GitHub
-
API key, DB password,... tất cả phải nằm ngoài source code
Mẹo vui: File .env như bàn chải đánh răng – không chia sẻ và nên thay thường xuyên 😁
6. Phiên bản hóa API
Lúc đầu nghe rườm rà, nhưng sau này bạn sẽ biết ơn chính mình.
-
Đặt prefix rõ ràng: /api/v1/users
-
Lên kế hoạch hỗ trợ backward compatibility
-
Khi cần "khai tử", hãy cảnh báo trước (ví dụ: gửi header hoặc thông báo)
7. Viết test (nghiêm túc đó!)
Bạn không cần test 100%, nhưng test một chút cũng giúp ích rất nhiều.
-
Unit test cho các logic riêng biệt
-
Integration test cho các endpoint (Jest + Supertest là combo xịn)
Lợi ích phụ: test cũng là tài liệu sống cho dev mới
8. Log như thám tử
console.logkhông đủ khi đưa app lên production đâu.
-
Dùng logger chuyên nghiệp như Winston hoặc Pino
-
Ghi lại các sự kiện quan trọng: login, lỗi DB, request thất bại
-
Đừng log thông tin nhạy cảm của user!
const winston = require('winston'); const logger = winston.createLogger({ transports: [new winston.transports.Console()],
});
9. Cập nhật dependencies thường xuyên
Package cũ = cửa hậu cho hacker.
-
Chạy npm audit định kỳ
-
Dùng công cụ như Dependabot hoặc Snyk để kiểm tra tự động
-
Cập nhật Node.js theo bản LTS để được hỗ trợ lâu dài
10. Viết tài liệu API
Code bạn có thể “xịn”, nhưng không có doc thì không ai xài được.
-
Dùng Swagger hoặc Postman Collection
-
Ghi rõ cách gọi API, xác thực, ví dụ và mã lỗi
Nhớ cập nhật khi API thay đổi – đừng để 6 tháng sau mới viết
11. Lời kết
Viết API sạch (Clean) và bảo mật (Secure) không chỉ là "theo best practice vì trên mạng nói vậy". Mà là tôn trọng người sẽ đọc và dùng API của bạn, và bảo vệ dữ liệu người dùng một cách tử tế. Vì API an toàn, sạch sẽ – giờ không còn là lựa chọn nữa. Mà là tiêu chuẩn.