Best practice

Az érett exception kezelés nem arról szól, hogy minél több kivételt dobunk. Hanem arról, hogy a hibákat úgy tervezzük meg, hogy a hívó, az üzemeltetés és a későbbi karbantartó is értse, mi történt és mit lehet vele kezdeni.

1. Definíció

Mik az exception best practice-ek?

Az exception best practice-ek olyan tervezési irányelvek, amelyek segítenek a hibák létrehozását, továbbadását, fordítását, dokumentálását és megfigyelését karbantartható módon megvalósítani.

Segítenek olyan kérdések megválaszolásában, mint például:

• egyáltalán exception legyen ez?
• melyik típus reprezentálja helyesen?
• kinek kell kezelnie?
• milyen kontextust kell hozzácsatolni?
• itt kell logolni vagy magasabb szinten?
• rollbacket, retry-t vagy riasztást kell kiváltania?

Miért fontos ez senior szinten?

Junior szinten a beszélgetés gyakran megáll a szintaxisnál.

Senior szinten inkább ezek kerülnek elő:

• a hiba szemantikája
• az API-szerződés
• az architekturális határfelületek
• az operatív tisztaság
• a hosszú távú karbantarthatóság

Egy rossz exception stratégia néha jobban megnehezíti a rendszer támogatását, mint maga az üzleti logika.

Mi a cél?

A cél nem az, hogy eltüntessük az exceptionöket.

A cél az, hogy a hibák:

• ott legyenek explicitek, ahol kell
• értelmesek legyenek a hívónak
• könnyen diagnosztizálhatók legyenek
• konzisztensen jelenjenek meg a rétegek között
• biztonságosan kezeljék a cleanupot és az állapotintegritást

2. Alapfogalmak

2.1 Exception csak kivételes helyzetre

2.1.1 Kulcsszavak és tervezési szerződések, amelyeket itt explicit módon ki kell mondani

A best practice beszélgetések sokkal tisztábbak, ha a fő tervezési szavakat pontosan kimondod:

• custom exception — valódi domain- vagy boundary-jelentéssel bíró egyedi kivételtípus.
• exception translation — alacsony szintű technikai hiba magasabb szintű absztrakcióvá alakítása.
• cause preservation — az eredeti kivétel megőrzése wrap vagy translation közben.
• log-and-rethrow — gyakran zajos anti-pattern, hacsak nem adsz hozzá új operatív jelentést.
• validation result — jobb modellezés, ha a hibák várhatók és gyakoriak.
• rollback — a hiba szemantikája miatt kiváltott tranzakciós visszagörgetés.
• retry — helyreállítási stratégia, amely a kivételtípus jelentésétől függ.

Ezek a fogalmak már architekturális jelentést hordoznak, nem pusztán szintaxist. Azt fejezik ki, kinek kell reagálnia, mi szivároghat át a réteghatáron, és mennyire marad diagnosztizálható a rendszer.

Nem minden negatív kimenetet kell exceptionként modellezni.

Sok esetben jobb megoldás lehet:

• validációs eredmény
• optional érték
• result objektum
• státuszválasz

Ha egy állapot gyakori és elvárt, akkor exceptionnel modellezni zajos és félrevezető lehet.

2.2 Pontos exception típusok előnyben

A specifikus típusok jelentést kommunikálnak.

Példák:

• IllegalArgumentException hibás inputra
• IllegalStateException hibás állapotra
• egyedi domain exception domain-specifikus hibára

Az általános típusok, mint az Exception vagy a RuntimeException, ne legyenek alapértelmezett választások, ha van pontosabb típus.

2.3 Cause megőrzése fordításkor

A fordítás sokszor helyes döntés.

Az eredeti cause-t azonban általában meg kell őrizni.

throw new OrderSubmissionException("Payment provider failed", exception);

Ez egyszerre ad:

• domain szintű tisztaságot
• technikai gyökérok visszakövethetőséget

2.4 Ne logolj minden rétegben

Az ismételt log-and-rethrow duplikációt okoz.

Jó szabály:

ott logolj, ahol a hiba operatív szempontból valóban jelentőséggel bír, ne minden átmeneti rétegben.

Ez csökkenti a zajt és javítja a riasztások minőségét.

2.5 Egyedi exceptionök gondos tervezése

Az egyedi exceptionök akkor hasznosak, ha domain szemantikát vagy architekturális jelentést hordoznak.

Nem hasznosak, ha csak átnevezik a generikus problémát anélkül, hogy többletértéket adnának.

Egy jó egyedi exception általában válaszol ezekre:

• mi hibázott ezen az absztrakciós szinten?
• kinek kell reagálnia?
• milyen kontextus tartozik ide?

2.6 Exception translation

Az exception translation azt jelenti, hogy az alacsonyabb szintű technikai exceptiont egy magasabb szintű, a boundary-hoz jobban illeszkedő exceptionné alakítjuk.

Ez gyakori például:

• repository és service réteg között
• service és web boundary között
• integrációs adaptereknél

Így az alacsony szintű implementációs részletek nem szivárognak fölöslegesen felfelé.

2.7 Dokumentálás és konzisztencia

Ha ugyanazt a hibakategóriát más és más módon reprezentálják különböző modulokban, a rendszer nehezen tanulhatóvá és nehezen debugolhatóvá válik.

A konzisztencia fontos a következőkben:

• névadás
• típusválasztás
• üzenetstílus
• logolási hely
• retry szemantika

3. Gyakorlati használat

Egyedi exception domain jelentésre

Tegyük fel, hogy egy rendelés beküldése azért bukik el, mert a fizetési gateway nem elérhető.

Technikailag az IOException pontos lehet.

De service boundary-n jobb lehet például:

• OrderSubmissionException
• ExternalDependencyException
• valamilyen strukturált result objektum

A helyes absztrakció rétegtől függ.

Validáció versus exception

Ha egy űrlap várhatóan több felhasználói hibát is tartalmazhat, akkor általában jobb validációs eredményeket visszaadni, mint sorban exceptionöket dobni.

Az exception jobb, ha:

• a folyamat valóban rendellenes
• a további feldolgozás nem folytatható biztonságosan
• a hiba boundary szerződés része

Egyszer fordíts, ne sokszor

Gyakori antipattern az ismételt fordítás anélkül, hogy új jelentést adnánk hozzá.

Például:

• repository dob SQLException-t
• service becsomagolja ServiceException-be
• facade becsomagolja FacadeException-be
• controller becsomagolja ControllerException-be

Ha egyik réteg sem ad új absztrakciós értelmet, ez pusztán zaj.

A hibaüzenet segítsen a diagnosztikában

A jó hibaüzenet kellően konkrét a hibakereséshez.

Rossz:

• Something failed
• Unexpected error

Jobb:

• Failed to load configuration for tenant acme
• Order 42 could not be submitted because payment authorization timed out

Az üzenet adjon jelet, ne drámát.

Rollback és retry szempontok

Az exception design gyakran viselkedést is meghatároz.

Példák:

• rollbacket váltson ki ez a kivétel?
• biztonságos rá a retry?
• megmutatható a felhasználónak?
• riasztást kell belőle csinálni?

Itt válik a best practice architektúrává.

4. Kód példák

1. példa — Egyedi domain exception

public class OrderSubmissionException extends RuntimeException {
    public OrderSubmissionException(String message, Throwable cause) {
        super(message, cause);
    }
}

Ez akkor jó, ha valódi domain vagy service-szintű fogalmat reprezentál.

2. példa — Fordítás cause-zal

try {
    paymentGateway.submit(order);
} catch (IOException exception) {
    throw new OrderSubmissionException("Payment provider failed for order " + order.id(), exception);
}

Domain kontextust ad úgy, hogy a technikai ok is megmarad.

3. példa — Validációs eredmény exception helyett

public record ValidationResult(boolean valid, List<String> errors) {
}

Elvárt felhasználói hibáknál ez jobb lehet, mint az exception-alapú vezérlés.

4. példa — Duplikált logolás kerülése

try {
    service.process(orderId);
} catch (OrderSubmissionException exception) {
    logger.error("Order processing failed for {}", orderId, exception);
    throw exception;
}

Ez csak akkor jó, ha ez a boundary operatív szempontból valóban a helyes logolási pont.

5. példa — Rossz egyedi exception

public class MyCustomRuntimeException extends RuntimeException {
}

Ez önmagában nem ad szemantikai többletet, és általában nem érdemes létrehozni.

5. Trade-offok

A best practice mindig egyensúlyról szól.

Túl kevés struktúra káoszt okoz.

Túl sok struktúra ceremóniává válik.

6. Gyakori hibák

1. Egyedi exception létrehozása valódi jelentés nélkül

Az egyedi exceptionnek valódi szemantikai kategóriát kell képviselnie, nem csak átnevezett generikus hibát.

2. Gyökérok elrejtése

Ha fordításkor nem őrzöd meg a cause-t, a hibakeresés jelentősen nehezebb lesz.

3. Ugyanannak a hibának a logolása minden rétegben

Ez riasztási fáradtságot és zajos logokat okoz.

4. Exception használata normál validációs folyamatra

Az elvárt input hibákat sokszor jobb result-alapúan kezelni.

5. Alacsony szintű részletek kiszivárogtatása magas szintű API-kon keresztül

Egy service API-nak nem mindig kell nyers persistence vagy transport exceptionöket láttatnia.

6. Inkonzisztens exception stratégia modulonként

Ha minden csapat más névadási és kezelési szabályokat használ, a kódbázis nehezen átláthatóvá válik.

7. Mélymerülés

Az exception design API design

Minden eldobott típus mesél valamit a felelősségről.

Ki okozta a hibát?

Ki tud reagálni rá?

Kinek kell látnia a technikai részleteket?

Ezek API tervezési kérdések.

Best practice és frameworkök

A frameworkök gyakran saját exception translation réteget adnak.

Példák:

• a Spring sok persistence exceptiont egységes data-access hierarchiára fordít
• a web frameworkök HTTP válaszokra képezik a kivételeket
• a messaging frameworkök eldöntik, legyen-e retry vagy dead-letter kezelés

A best practice-ek ismerete segít együtt dolgozni a frameworkkel ahelyett, hogy ellene mennél.

Security és privacy

A hibaüzenet legyen hasznos, de ne szivárogtasson titkokat.

A jó exception kezelés egyensúlyt tart a következők között:

• diagnosztizálhatóság
• felhasználói biztonság
• operatív tisztaság

Ez különösen fontos autentikációs, fizetési és multi-tenant rendszerekben.

Senior interjú nézőpont

Egy senior válasz gyakran nem csak kódmintát, hanem hibapolitikát is elmagyaráz.

Például:

• az elvárt validációs hibák strukturált eredményekké válnak
• az infrastruktúra-hibák boundary exceptionné fordulnak
• a programozói hibák unchecked exceptionök maradnak
• a logolás ott történik, ahol az esemény operatívan jelentőssé válik

Ez már rendszertervezési szemléletet tükröz.

Hosszú távú karbantarthatóság

A best practice-ek nagy csapatban még fontosabbak.

A konzisztens exception stratégia csökkenti:

• a betanulási időt
• a support bizonytalanságot
• a rejtett csatolást
• a duplikált hibakeresési munkát

Ez valódi karbantarthatósági szorzó.

8. Interjúkérdések

Mikor érdemes egyedi exceptiont létrehozni?

Akkor, amikor valódi domain vagy architekturális jelentést ad, segíti a hívó helyes reakcióját, vagy tisztább boundary kommunikációt eredményez.

Miért hasznos az exception translation?

Mert megakadályozza, hogy az alacsony szintű implementációs részletek átszivárogjanak a magasabb szintű API-kon, és tisztább hibaszemantikát ad a rétegenként.

Miért kell kerülni a duplikált logolást?

Mert az ismételt log-and-rethrow zajt okoz, rontja a jel minőségét, és nehezebbé teszi az incidensek elemzését.

Mikor jobb a validációs eredmény, mint az exception?

Amikor a hiba elvárt, gyakori és a normál felhasználói interakció része, nem pedig valóban kivételes programfolyamat.

Mitől jó egy exception üzenet?

Attól, hogy hasznos diagnosztikai kontextust ad anélkül, hogy homályos, félrevezető vagy érzékeny adatot szivárogtató lenne.

9. Szószedet

10. Cheatsheet

• Exceptiont valóban kivételes helyzetre használj.
• Az általános típusok helyett pontos típusokat preferálj.
• Egyedi exceptiont csak akkor hozz létre, ha jelentést ad.
• Fordításkor őrizd meg a cause-t.
• Ugyanazt a hibát ne logold minden rétegben.
• Elvárt user hibákra gyakran jobb a validációs eredmény.
• Az alacsony szintű részleteket ne szivárogtasd ki magas szintű API-kon.
• Az üzenet segítse a diagnózist, de ne szivárogtasson titkot.
• Az exception stratégiát igazítsd rollback, retry és alerting döntésekhez.
• Interjún az exception designt kösd össze az API-tervezéssel és az operációval.