Membangun REST API Express.js & Node.js yang Rapi: Validasi, Error Handler, & Graceful Shutdown
Membuat satu endpoint Express.js memang hanya butuh sepuluh baris kode. Namun ketika jumlah endpoint tumbuh melewati dua puluh rute, menaruh seluruh logika dan blok try/catch berulang di satu berkas index.js segera membuat proyek sulit di-debug dan rawan mengembalikan pesan galat yang tidak konsisten ke klien.
Setelah memahami fondasi pengamanan pada panduan keamanan Node.js, langkah berikutnya untuk menyiapkan layanan API produksi adalah merapikan tiga hal mendasar: pemisahan struktur lapisan, penanganan error terpusat, dan graceful shutdown agar proses tidak memutus transaksi aktif saat server di-restart.
1. Struktur Direktori Modular yang Cukup Sederhana
Anda tidak perlu arsitektur berlapis-lapis yang rumit sejak hari pertama. Pemisahan empat tanggung jawab berikut sudah sangat cukup untuk skala proyek kecil hingga menengah:
src/
├── app.js # Registrasi middleware global, routes, dan error handler
├── server.js # Startup HTTP server & graceful shutdown
├── errors/
│ └── AppError.js # Kelas error operasional dengan HTTP status code
├── middlewares/
│ ├── validate.js # Wrapper validasi payload (mis. Zod)
│ └── errorHandler.js # Middleware penangkap error 4 parameter
├── routes/
│ └── product.routes.js # Pemetaan endpoint URL
└── controllers/
└── product.controller.js
Memisahkan app.js dari server.js (tempat app.listen() dipanggil) membawa keuntungan besar: Anda dapat menguji endpoint memakai Supertest tanpa harus membuka port jaringan sungguhan.
2. Kelas AppError dan Centralized Error Middleware
Bedakan antara error operasional yang diperkirakan (data tidak ditemukan 404, input tidak valid 422, tidak berwenang 403) dengan bug tak terduga (500). Buat satu kelas pembantu sederhana:
// src/errors/AppError.js
export class AppError extends Error {
constructor(message, statusCode = 500, details = null) {
super(message);
this.statusCode = statusCode;
this.details = details;
this.isOperational = true;
}
}
Lalu tangkap semua error di satu tempat paling akhir dalam app.js menggunakan middleware Express khusus 4 parameter (err, req, res, next):
// src/middlewares/errorHandler.js
export function errorHandler(err, req, res, next) {
const statusCode = err.isOperational ? err.statusCode : 500;
if (!err.isOperational) {
console.error('[UNHANDLED ERROR]', {
method: req.method,
path: req.originalUrl,
message: err.message,
stack: err.stack,
});
}
const response = {
success: false,
message: err.isOperational
? err.message
: 'Terjadi kesalahan internal pada server.',
};
if (err.details) {
response.errors = err.details;
}
res.status(statusCode).json(response);
}
Dengan pola ini, detail stack trace hanya tercatat di log server—tidak pernah bocor ke respons JSON pengguna produksi—dan format error di seluruh endpoint selalu seragam.
3. Middleware Validasi dan Controller Tanpa Duplikasi try/catch
Pada Express 5, promise yang ditolak (rejected promise) dari fungsi async otomatis diteruskan ke errorHandler. Jika Anda masih memakai Express 4, cukup bungkus handler dengan helper kecil asyncHandler:
// src/middlewares/validate.js
import { AppError } from '../errors/AppError.js';
export const validateBody = (schema) => (req, res, next) => {
const parsed = schema.safeParse(req.body);
if (!parsed.success) {
return next(new AppError('Data masukan tidak valid.', 422, parsed.error.flatten().fieldErrors));
}
req.body = parsed.data;
return next();
};
// src/controllers/product.controller.js
import { AppError } from '../errors/AppError.js';
import { findProductById } from '../services/product.service.js';
export async function getProductDetail(req, res) {
const product = await findProductById(req.params.id);
if (!product) {
throw new AppError('Produk tidak ditemukan.', 404);
}
res.json({ success: true, data: product });
}
4. Menerapkan Graceful Shutdown Saat Deploy
Ketika Docker, PM2, atau systemd me-restart server saat deployment baru, sistem operasi mengirim sinyal SIGTERM. Tanpa penanganan graceful shutdown, proses Node.js berhenti seketika sehingga permintaan HTTP yang sedang menulis ke database terputus di tengah jalan.
// src/server.js
import { app } from './app.js';
const PORT = Number(process.env.PORT) || 3000;
const server = app.listen(PORT, () => {
console.log(`API berjalan pada port ${PORT}`);
});
function shutdown(signal) {
console.log(`Menerima sinyal ${signal}, menutup server dengan aman...`);
// Berhenti menerima koneksi baru, selesaikan request yang masih berjalan
server.close(async () => {
try {
// Tutup koneksi database / Redis pool di sini jika ada
console.log('Seluruh koneksi berhasil ditutup.');
process.exit(0);
} catch (err) {
console.error('Gagal menutup resource:', err);
process.exit(1);
}
});
// Paksa keluar jika ada koneksi macet lebih dari 10 detik
setTimeout(() => {
console.error('Timeout graceful shutdown, menghentikan proses.');
process.exit(1);
}, 10_000).unref();
}
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
Checklist Kode Status HTTP yang Konsisten
| Status Code | Arti | Kapan Dipakai |
|---|---|---|
200 / 201 |
OK / Created | 200 untuk GET/PUT sukses, 201 setelah berhasil membuat resource baru via POST. |
401 vs 403 |
Unauthorized vs Forbidden | 401 bila belum login/token kedaluwarsa; 403 bila sudah login tapi tidak punya izin akses. |
404 / 422 |
Not Found / Unprocessable | 404 jika ID resource tidak ada; 422 jika format/aturan validasi body gagal. |
Diskusi & Komentar
0Sampaikan pertanyaan teknis, masukan, atau feedback Anda seputar artikel ini.
Belum Ada Komentar
Jadilah pembaca pertama yang memulai diskusi menarik atau bertanya seputar materi artikel ini!