Bagaimana anda mereka bentuk response ralat yang konsisten dan melaporkan ralat pengesahan?

Question

IT Interview Practice · Accepted Answer

Response ralat yang baik melakukan dua perkara: ia menggunakan **HTTP status code yang betul** (isyarat boleh dibaca mesin), dan ia memulangkan **body berstruktur dan konsisten** yang boleh ditindaki pembangun. Bentuk ralat yang tidak konsisten ialah salah satu sumber terbesar kesengsaraan pihak client.

## Guna format ralat standard: RFC 7807 (problem+json)

RFC 7807 mentakrifkan body "problem details" standard dengan media type khusus, jadi setiap ralat merentas API anda kelihatan sama:

```http
HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "No user exists with id 999",
  "instance": "/users/999"
}
```

- `type` — URI yang mengenal pasti kategori ralat (boleh dinyahrujuk ke dokumentasi).
- `title` — ringkasan pendek, boleh dibaca manusia (stabil bagi setiap `type`).
- `status` — HTTP status, dicermin untuk kemudahan.
- `detail` — penjelasan khusus untuk kejadian *ini*.
- `instance` — request/sumber mana ia berlaku.

## Ralat pengesahan: laporkan semua sekali gus

Untuk pengesahan borang/medan, pulangkan `422` (atau `400`) dan satu **tatasusunan ralat medan** supaya client boleh menyerlahkan setiap medan yang buruk dalam satu laluan — bukan satu ralat pada satu masa:

```http
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "errors": [
    { "field": "email", "code": "invalid_format", "message": "must be a valid email" },
    { "field": "age",   "code": "out_of_range",   "message": "must be >= 18" }
  ]
}
```

## Prinsip

```text
✓ Same body shape for every error (one code path on the client)
✓ A stable machine-readable code (type/code) — clients branch on this, not on prose
✓ Human-readable message for developers/logs
✗ Never leak stack traces, SQL, or internal paths to clients
```

## Mengapa ia penting

Reka bentuk ralat ialah tempat API senyap-senyap berjaya atau gagal di dunia sebenar: laluan gembira mudah, tetapi pengguna menghabiskan kebanyakan masa nyahpepijat mereka di laluan ralat, dan kontrak ralat yang tidak konsisten atau kabur menjadikan integrasi menyeksakan. Penemu duga menggunakan ini untuk menyemak dua perkara. Pertama, **status code serta body berstruktur bekerjasama** — status ialah isyarat kasar untuk tooling dan retry, body membawa butiran yang boleh ditindaki — dan bukannya anti-pattern `200 OK` dengan ralat di dalamnya. Kedua, satu **kod ralat yang stabil dan boleh dibaca mesin** (melalui `type` RFC 7807 atau medan `code`) supaya client boleh bercabang pada `"insufficient_funds"` dan bukannya memadan-rentetan mesej bahasa Inggeris yang mungkin ditulis semula atau disetempatkan. Memulangkan semua ralat pengesahan sekali gus, dan tidak pernah membocorkan butiran dalaman seperti stack trace, melengkapkan jawapan yang menunjukkan anda telah membina API yang pasukan lain benar-benar terpaksa gunakan.

Guna format ralat standard: RFC 7807 (problem+json)

Ralat pengesahan: laporkan semua sekali gus

Prinsip

Mengapa ia penting

Soalan berkaitan