Kaip suprojektuoti nuoseklius klaidų atsakymus ir pranešti validacijos klaidas?

Question

IT Interview Practice · Accepted Answer

Geras error response daro du dalykus: naudoja **tinkamą HTTP status code** (mašinai nuskaitomą signalą) ir grąžina **nuoseklų, struktūruotą kūną**, į kurį kūrėjas gali reaguoti. Nenuoseklios klaidų formos yra vienas didžiausių skausmo šaltinių kliento pusėje.

## Naudok standartinį klaidos formatą: RFC 7807 (problem+json)

RFC 7807 apibrėžia standartinį „problem details“ kūną su specialiu media type, todėl kiekviena klaida visoje tavo API atrodo vienodai:

```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, identifikuojantis klaidos kategoriją (dereferencuojamas į dokumentaciją).
- `title` — trumpa, žmogui skaitoma santrauka (stabili kiekvienam `type`).
- `status` — HTTP status, atkartotas patogumui.
- `detail` — konkretus paaiškinimas *šiam* pasireiškimui.
- `instance` — kurioje užklausoje/ištekliuje tai įvyko.

## Validacijos klaidos: praneškite jas visas iš karto

Formos/laukų validacijai grąžink `422` (arba `400`) ir **laukų klaidų masyvą**, kad klientas galėtų paryškinti kiekvieną blogą lauką per vieną kartą — o ne po vieną klaidą:

```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" }
  ]
}
```

## Principai

```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
```

## Kodėl tai svarbu

Klaidų dizainas yra vieta, kur API tyliai pavyksta arba žlunga realiame pasaulyje: laimingas kelias lengvas, bet vartotojai daugumą derinimo laiko praleidžia klaidų kelyje, o nenuosekli ar migloti klaidų sutartis daro integraciją kančia. Interviuotojai naudoja tai patikrinti dviejų dalykų. Pirma, **status code plius struktūruotas kūnas dirbantys kartu** — status yra grubus signalas įrankiams ir retry, kūnas neša veiksmingą detalę — o ne anti-pattern `200 OK` su klaida viduje. Antra, **stabilų, mašinai nuskaitomą klaidos kodą** (per RFC 7807 `type` ar `code` lauką), kad klientai galėtų šakotis pagal `"insufficient_funds"`, o ne lygintų angliškos žinutės eilutę, kuri gali būti perrašyta ar lokalizuota. Visų validacijos klaidų grąžinimas iš karto ir niekada neatskleisti vidinių detalių, tokių kaip stack traces, užbaigia atsakymą, rodantį, kad kūrei API, kurias kitos komandos iš tikrųjų turėjo naudoti.

Naudok standartinį klaidos formatą: RFC 7807 (problem+json)

Validacijos klaidos: praneškite jas visas iš karto

Principai

Kodėl tai svarbu

Susiję klausimai