Fehlerbehandlung

Muster zur Fehlerbehandlung

Konsistente, robuste Muster zur Fehlerbehandlung für Produktionsanwendungen.

Wann zu aktivieren

• Entwerfen von Fehlertypen oder Ausnahmehierarchien für ein neues Modul oder einen neuen Dienst
• Hinzufügen von Wiederholungslogik oder Trennschaltern für unzuverlässige externe Abhängigkeiten
• Überprüfen von API-Endpunkten auf fehlende Fehlerbehandlung
• Implementieren von benutzerseitigen Fehlermeldungen und Feedback
• Debuggen von kaskadierenden Fehlern oder stillem Fehlerschlucken

Kernprinzipien

1. Fail Fast und laut — Fehler an der Grenzfläche, an der sie auftreten, sichtbar machen; sie nicht vergraben
2. Typisierte Fehler über Textmeldungen — Fehler sind erstklassige Werte mit Struktur
3. Benutzermeldungen ≠ Entwicklermeldungen — Benutzern freundlichen Text anzeigen, vollständigen Kontext serverseitig protokollieren
4. Fehler niemals stillschlucken — jeder catch-Block muss entweder bearbeiten, erneut werfen oder protokollieren
5. Fehler sind Teil Ihres API-Vertrags — jeden Fehlercode dokumentieren, den ein Client erhalten kann

TypeScript / JavaScript

Typisierte Fehlerklassen

// Definieren Sie eine Fehlerhierarchie für Ihre Domäne
export class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
    public readonly details?: unknown,
  ) {
    super(message)
    this.name = this.constructor.name
    // Die korrekte Prototyp-Kette in transpiliertem ES5-JavaScript beibehalten.
    // Erforderlich, damit `instanceof`-Überprüfungen (z. B. `error instanceof NotFoundError`)
    // korrekt funktionieren, wenn die eingebaute Error-Klasse erweitert wird.
    Object.setPrototypeOf(this, new.target.prototype)
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
  }
}

export class ValidationError extends AppError {
  constructor(message: string, details: { field: string; message: string }[]) {
    super(message, 'VALIDATION_ERROR', 422, details)
  }
}

export class UnauthorizedError extends AppError {
  constructor(reason = 'Authentication required') {
    super(reason, 'UNAUTHORIZED', 401)
  }
}

export class RateLimitError extends AppError {
  constructor(public readonly retryAfterMs: number) {
    super('Rate limit exceeded', 'RATE_LIMITED', 429)
  }
}

Result Pattern (No-Throw-Stil)

Für Operationen, bei denen Fehler erwartet und häufig sind (Parsen, externe Aufrufe):

type Result<T, E = AppError> =
  | { ok: true; value: T }
  | { ok: false; error: E }

function ok<T>(value: T): Result<T> {
  return { ok: true, value }
}

function err<E>(error: E): Result<never, E> {
  return { ok: false, error }
}

// Verwendung
async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const user = await db.users.findUnique({ where: { id } })
    if (!user) return err(new NotFoundError('User', id))
    return ok(user)
  } catch (e) {
    return err(new AppError('Database error', 'DB_ERROR'))
  }
}

const result = await fetchUser('abc-123')
if (!result.ok) {
  // TypeScript weiß hier result.error
  logger.error('Fehler beim Abrufen des Benutzers', { error: result.error })
  return
}
// TypeScript weiß hier result.value
console.log(result.value.email)

API-Fehlerhandler (Next.js / Express)

import { NextRequest, NextResponse } from 'next/server'

function handleApiError(error: unknown): NextResponse {
  // Bekannter Anwendungsfehler
  if (error instanceof AppError) {
    return NextResponse.json(
      {
        error: {
          code: error.code,
          message: error.message,
          ...(error.details ? { details: error.details } : {}),
        },
      },
      { status: error.statusCode },
    )
  }

  // Zod-Validierungsfehler
  if (error instanceof z.ZodError) {
    return NextResponse.json(
      {
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Die Anfragevalidierung ist fehlgeschlagen',
          details: error.issues.map(i => ({
            field: i.path.join('.'),
            message: i.message,
          })),
        },
      },
      { status: 422 },
    )
  }

  // Unerwarteter Fehler — Details protokollieren, generische Meldung zurückgeben
  console.error('Unerwarteter Fehler:', error)
  return NextResponse.json(
    { error: { code: 'INTERNAL_ERROR', message: 'Ein unerwarteter Fehler ist aufgetreten' } },
    { status: 500 },
  )
}

export async function POST(req: NextRequest) {
  try {
    // ... Handler-Logik
  } catch (error) {
    return handleApiError(error)
  }
}

React Error Boundary

import { Component, ErrorInfo, ReactNode } from 'react'

interface Props {
  fallback: ReactNode
  onError?: (error: Error, info: ErrorInfo) => void
  children: ReactNode
}

interface State {
  hasError: boolean
  error: Error | null
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null }

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error }
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    this.props.onError?.(error, info)
    console.error('Unbehandelter React-Fehler:', error, info)
  }

  render() {
    if (this.state.hasError) return this.props.fallback
    return this.props.children
  }
}

// Verwendung
<ErrorBoundary fallback={<p>Etwas ist schiefgelaufen. Bitte aktualisieren Sie die Seite.</p>}>
  <MyComponent />
</ErrorBoundary>

Python

Benutzerdefinierte Ausnahmehierarchie

class AppError(Exception):
    """Basis-Anwendungsfehler."""
    def __init__(self, message: str, code: str, status_code: int = 500):
        super().__init__(message)
        self.code = code
        self.status_code = status_code

class NotFoundError(AppError):
    def __init__(self, resource: str, id: str):
        super().__init__(f"{resource} nicht gefunden: {id}", "NOT_FOUND", 404)

class ValidationError(AppError):
    def __init__(self, message: str, details: list[dict] | None = None):
        super().__init__(message, "VALIDATION_ERROR", 422)
        self.details = details or []

FastAPI Globaler Ausnahmehandler

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": {"code": exc.code, "message": str(exc)}},
    )

@app.exception_handler(Exception)
async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
    # Vollständige Details protokollieren, generische Meldung zurückgeben
    logger.exception("Unerwarteter Fehler", exc_info=exc)
    return JSONResponse(
        status_code=500,
        content={"error": {"code": "INTERNAL_ERROR", "message": "Ein unerwarteter Fehler ist aufgetreten"}},
    )

Go

Sentinel-Fehler und Fehlerumhüllung (Error Wrapping)

package domain

import "errors"

// Sentinel-Fehler zur Typprüfung
var (
    ErrNotFound    = errors.New("not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrConflict     = errors.New("conflict")
)

// Fehler mit Kontext umhüllen — den ursprünglichen Fehler niemals verlieren
func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {
    user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id)
    if errors.Is(err, sql.ErrNoRows) {
        return nil, fmt.Errorf("Benutzer %s: %w", id, ErrNotFound)
    }
    if err != nil {
        return nil, fmt.Errorf("Abfrage des Benutzers %s: %w", id, err)
    }
    return user, nil
}

// Auf Handler-Ebene entpacken, um die Antwort zu bestimmen
func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
    user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id"))
    if err != nil {
        switch {
        case errors.Is(err, domain.ErrNotFound):
            writeError(w, http.StatusNotFound, "not_found", err.Error())
        case errors.Is(err, domain.ErrUnauthorized):
            writeError(w, http.StatusForbidden, "forbidden", "Zugriff verweigert")
        default:
            slog.Error("unerwarteter Fehler", "err", err)
            writeError(w, http.StatusInternalServerError, "internal_error", "Ein unerwarteter Fehler ist aufgetreten")
        }
        return
    }
    writeJSON(w, http.StatusOK, user)
}

Wiederholung mit exponentiellem Backoff

interface RetryOptions {
  maxAttempts?: number
  baseDelayMs?: number
  maxDelayMs?: number
  retryIf?: (error: unknown) => boolean
}

async function withRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions = {},
): Promise<T> {
  const {
    maxAttempts = 3,
    baseDelayMs = 500,
    maxDelayMs = 10_000,
    retryIf = () => true,
  } = options

  let lastError: unknown

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn()
    } catch (error) {
      lastError = error
      if (attempt === maxAttempts || !retryIf(error)) throw error

      const jitter = Math.random() * baseDelayMs
      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs)
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }

  throw lastError
}

// Verwendung: vorübergehende Netzwerkfehler wiederholen, keine 4xx-Fehler
const data = await withRetry(() => fetch('/api/data').then(r => r.json()), {
  maxAttempts: 3,
  retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),
})

Benutzerseitige Fehlermeldungen

Fehlercodes in menschenlesbare Meldungen übersetzen. Technische Details aus dem für Benutzer sichtbaren Text heraushalten.

const USER_ERROR_MESSAGES: Record<string, string> = {
  NOT_FOUND: 'Das angeforderte Element konnte nicht gefunden werden.',
  UNAUTHORIZED: 'Bitte melden Sie sich an, um fortzufahren.',
  FORBIDDEN: 'Sie haben keine Berechtigung, dies zu tun.',
  VALIDATION_ERROR: 'Bitte überprüfen Sie Ihre Eingabe und versuchen Sie es erneut.',
  RATE_LIMITED: 'Zu viele Anfragen. Bitte warten Sie einen Moment und versuchen Sie es erneut.',
  INTERNAL_ERROR: 'Bei uns ist etwas schiefgelaufen. Bitte versuchen Sie es später erneut.',
}

export function getUserMessage(code: string): string {
  return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR
}

Checkliste zur Fehlerbehandlung

Vor dem Zusammenführen von Code, der die Fehlerbehandlung betrifft:

• Jeder catch-Block behandelt, wirft erneut oder protokolliert — kein stilles Schlucken
• API-Fehler folgen dem standardisierten Format { error: { code, message } }
• Benutzerseitige Meldungen enthalten keine Stack-Traces oder internen Details
• Der vollständige Fehlerkontext wird serverseitig protokolliert
• Benutzerdefinierte Fehlerklassen erweitern eine Basisklasse AppError mit einem code-Feld
• Asynchrone Funktionen geben Fehler an Aufrufer weiter — kein Fire-and-Forget ohne Fallback
• Wiederholungslogik wiederholt nur wiederholbare Fehler (keine 4xx-Client-Fehler)
• React-Komponenten sind bei Renderfehlern in ErrorBoundary eingeschlossen