Fehlerarchitektur, Problem Details und Exception Mapping

Fehlerarten trennen

Ein fachlicher Konflikt ist kein technischer Systemfehler. Wenn ein Kunde kein Limit hat, ist das etwas anderes als ein Datenbank-Timeout. Diese Trennung muss sich in Code, API-Vertrag, Logging und Monitoring zeigen.

Problem Details

REST-APIs sollten stabile Fehlercodes und maschinenlesbare Details liefern. SOAP-Systeme brauchen entsprechende Fault-Strukturen. Wichtig ist, dass interne Klassennamen nicht nach außen leaken.

Beispielcode

package at.aydinsude.enterprise.api;

import java.net.URI;
import java.util.Map;

// Pattern: Error Contract - technische Darstellung ist stabil, Domain bleibt unabhängig.
public record ProblemDetails(
        URI type,
        String title,
        int status,
        String detail,
        String instance,
        Map<String, Object> extensions) {

    public static ProblemDetails businessConflict(String code, String detail, String traceId) {
        return new ProblemDetails(
                URI.create("https://errors.example.com/enterprise/" + code),
                "Business conflict",
                409,
                detail,
                traceId,
                Map.of("code", code, "retryable", false));
    }
}

Praxisübertragung auf das V4-Beispielprojekt

Typische Fehlerbilder

• Framework-Feature wird eingesetzt, ohne fachliche Grenze zu verstehen.
• Technische Wiederholung wird nicht idempotent gemacht.
• Observability wird erst nach Produktionsproblem ergänzt.
• Tests prüfen nur Happy Path und keine Wiederanläufe.