Node.js Diterbitkan: • Diperbarui: • 4 menit baca • 11 views

Membangun REST API Express.js & Node.js yang Rapi: Validasi, Error Handler, & Graceful Shutdown

Juan Mths
Juan Mths
Chief Technology Officer & Administrator
Ilustrasi 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

0

Sampaikan pertanyaan teknis, masukan, atau feedback Anda seputar artikel ini.

Tulis Komentar
* Tautan dalam komentar otomatis diamankan dengan atribut rel="nofollow ugc". Maks 2.000 karakter
Komentar langsung terbit setelah lolos filter spam.

Belum Ada Komentar

Jadilah pembaca pertama yang memulai diskusi menarik atau bertanya seputar materi artikel ini!