Belajar Axum - Responses & Error Handling

#Pendahuluan

Di episode 5 kita sibuk membaca request. Sekarang giliran sisi satunya: mengembalikan response dan menangani error. Dua topik ini sengaja disatukan karena di Axum keduanya adalah satu mekanisme — trait IntoResponse. Tipe error yang kalian definisikan bisa (dan sebaiknya) mengimplement IntoResponse, sehingga satu sistem menangani sukses dan gagal.

Mengapa episode ini penting? Karena API yang terlihat profesional dinilai dari konsistensi responsenya: klien harus bisa menebak bentuk error tanpa membaca dokumentasi, status code harus akurat secara semantik, dan error internal tidak boleh membocorkan detail internal ke publik. Kita akan membangun pondasi yang dipakai semua episode berikutnya — termasuk error.rs yang sempat disebut di episode 3.

#IntoResponse Lebih Dalam

Trait IntoResponse punya satu method wajib: into_response(self) -> Response. Yang menarik, Axum sudah mengimplementasikannya untuk banyak tipe dasar, dan tuple menggabungkan beberapa nilai menjadi satu response:

use axum::{
    http::{header, StatusCode},
    Json,
};
 
// (StatusCode, &'static str) -> status + body teks
async fn gone() -> (StatusCode, &'static str) {
    (StatusCode::GONE, "resource sudah dihapus")
}
 
// (StatusCode, [header; 2], String) -> status + headers + body
async fn with_headers() -> (StatusCode, [(header::HeaderName, &'static str); 1], String) {
    (
        StatusCode::OK,
        [(header::CACHE_CONTROL, "max-age=60")],
        "dengan header".into(),
    )
}
 
// (StatusCode, Json<T>) -> status + body JSON
async fn created() -> (StatusCode, Json<serde_json::Value>) {
    (StatusCode::CREATED, Json(serde_json::json!({ "ok": true })))
}

Tuple adalah mekanisme paling fleksibel di Axum — hingga beberapa elemen, semua kombinasinya menghasilkan response yang tepat. Aturan yang perlu diingat: hanya boleh satu elemen IntoResponse non-Response per tuple; elemen lain harus StatusCode atau header array.

#Menentukan Status Code yang Benar

Beberapa pasangan yang wajib dihafal untuk API:

Status code adalah bagian dari contract API. Klien menulis logic berdasarkan status, jadi memilih dengan tepat bukan sekadar estetika.

#Redirect

Redirect adalah cara idiomatis mengirim 301/302/303/307/308:

use axum::response::Redirect;
 
async fn old_home() -> Redirect {
    Redirect::to("/beranda")
}
 
async fn moved() -> Redirect {
    Redirect::permanent("/pindah")
}

Redirect::to menghasilkan 303 See Other (untuk hasil POST, body GET bisa diikuti); Redirect::permanent menghasilkan 301 Moved Permanently. Untuk merespon GET lama yang diganti route, permanent adalah pilihan tepat.

#Membangun Tipe Error Aplikasi

Sekarang bagian inti: satu tipe error untuk seluruh aplikasi, dan semuanya menghasilkan JSON konsisten. Ini pola standar untuk REST API Axum:

use axum::{
    http::StatusCode,
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;
 
#[derive(Debug)]
pub enum AppError {
    NotFound,
    BadRequest(String),
    Conflict(String),
    Unauthorized,
    Internal(String),
}
 
impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, message) = match self {
            AppError::NotFound => (StatusCode::NOT_FOUND, "resource tidak ditemukan".into()),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
            AppError::Conflict(msg) => (StatusCode::CONFLICT, msg),
            AppError::Unauthorized => (StatusCode::UNAUTHORIZED, "autentikasi diperlukan".into()),
            AppError::Internal(msg) => {
                tracing::error!("internal error: {msg}");
                (StatusCode::INTERNAL_SERVER_ERROR, "terjadi kesalahan internal".into())
            }
        };
 
        (status, Json(json!({ "error": { "message": message } }))).into_response()
    }
}
 
pub type AppResult<T> = Result<T, AppError>;

Beberapa keputusan penting di sini:

1. Satu bentuk JSON error — { "error": { "message": ... } } — untuk semua kasus. Klien tinggal parse satu skema.
2. Error internal tidak membocorkan detail — pesan asli hanya ke log (tracing::error!), response publiknya generik. Ini langkah pertama dari kebiasaan security di episode 18.
3. AppResult<T> — alias untuk mengurangi boilerplate Result<T, AppError> di tiap handler.

#Handler yang Mengembalikan Result

Dengan AppError, handler bisa mengembalikan Result dan Axum otomatis memanggil IntoResponse untuk kedua cabang:

use axum::{extract::Path, Json};
use serde_json::{json, Value};
 
async fn get_user(Path(id): Path<u32>) -> AppResult<Json<Value>> {
    if id == 0 {
        return Err(AppError::BadRequest("id harus lebih besar dari 0".into()));
    }
    if id > 100 {
        return Err(AppError::NotFound);
    }
    Ok(Json(json!({ "id": id, "name": "Arman" })))
}

Perhatikan pola return Err(...) di tengah handler — jauh lebih bersih daripada match raksasa di akhir. Compiler tetap menjamin kedua cabang mengimplement IntoResponse.

#Integrasi dengan Error Extractor

Ingat di episode 5 kita bilang rejection extractor bisa dikustomisasi? Caranya dengan impl From<Rejection> for AppError. Misalnya kita ingin Json yang gagal parse menghasilkan pesan khusus, bukan 400 polos:

use axum::extract::rejection::JsonRejection;
 
impl From<JsonRejection> for AppError {
    fn from(rejection: JsonRejection) -> Self {
        match rejection.status() {
            axum::http::StatusCode::UNSUPPORTED_MEDIA_TYPE => {
                AppError::BadRequest("Content-Type harus application/json".into())
            }
            _ => AppError::BadRequest(format!("body JSON tidak valid: {}", rejection.body_text())),
        }
    }
}

Setelah impl From ini ada, handler dengan Result<Json<T>, AppError> akan otomatis memetakan error parsing JSON ke format error aplikasi. Ini kunci agar seluruh jalur error — logic handler maupun rejection extractor — keluar dalam satu bentuk.

#Problem Details (RFC 9457)

Format { "error": { "message" } } di atas sudah cukup untuk kebanyakan API. Jika kalian ingin mengikuti standar industri, RFC 9457 (Problem Details for HTTP APIs) mendefinisikan skema error yang lebih kaya:

{
  "type": "https://example.com/probs/validation",
  "title": "Validasi gagal",
  "status": 400,
  "detail": "Field email harus format email yang valid",
  "instance": "/api/users"
}

Implementasinya tinggal memperkaya struktur json! di AppError::into_response — tambahkan field type, title, detail, instance. Axum tidak mewajibkan format apa pun, tetapi mengikuti standar ini memudahkan klien dan tooling (misal integrasi dengan error aggregator).

#Penutup

Pada episode 6 ini kalian telah membangun fondasi responses & error handling:

• IntoResponse via tuple: status + headers + body dalam berbagai kombinasi.
• Status code yang tepat secara semantik untuk tiap situasi.
• Redirect untuk perpindahan route.
• Tipe AppError dengan IntoResponse → satu format JSON error untuk semua kasus.
• From<JsonRejection> untuk menyatukan rejection extractor ke format yang sama.
• Opsi ekstensi menuju RFC 9457 Problem Details.

Di episode 7 selanjutnya kita bahas State & App State: membagikan database pool, config, dan nilai bersama antar handler dengan with_state, Arc, dan typed state access — kunci dari aplikasi yang "berisi data" sungguhan. Sampai jumpa di episode 7!