//Cloudogu EcoSystem Docs

Richtlinien für die Behandlung von Fehlern im Baseline Tool

Dieses Dokument beschreibt die Richtlinien, die bei der Fehlerbehandlung im Baseline-Tool beachtet werden sollen.

Richtlinien – Backend

1. Struct WithCode dient als Kommunikationsmedium

WithCode ist ein eigener Fehlertyp (struct) und wird innerhalb vom Baseline-Backend verwendet, um im Fehlerfall Informationen bis zu dem Endanwender zu kommunizieren. Dabei ist auf die Formulierung und Struktur der vorhandenen Fehler und ihren Fehlercodes und -texten zu achten. Diese sind in der Datei errorMessages.go im Paket customerror zu finden.

Der Typ WithCode erlaubt es, mehrere Fehlermeldungen miteinander zu verknüpfen und damit sehr flexible und detaillierte Fehlermeldungen zu erstellen. Ebenso ist es möglich, Parameter zu definieren und zu übergeben.

Generell gibt es drei verschiedene Arten von Fehlern im Baseline Tool: Kontextfehler, technische Fehler und generische Fehler

Kontextfehler

Kontextfehler werden verwendet, um den Benutzer den Kontext der ausgeführten Operation mitzuteilen. Ein Beispiel für einen Kontextfehler ist "Die Projekte konnten nicht geladen werden.". Der Kontextfehler ist sehr wichtig, damit der Nutzer die Beziehung zwischen Fehlermeldung und Operation leicht verstehen kann. In einer Verkettung von WithCode -Fehlern sollte der erste Fehler immer ein Kontextfehler sein. Welcher Kontextfehler zu einer Request-Handler-Methode gehört wird in der entsprechenden Methode selbst definiert.

Technische Fehler

Technische Fehler dienen dazu, die Ursache eines Fehlers in einer einfachen, plausiblen und verständlichen Form dem Nutzer mitzuteilen. Dabei ist zu betrachten, dass ein technischer Fehler aus mehreren technischen Fehlern bestehen kann. Ein Beispiel für einen technischen Fehler ist "Die Verbindung zum Nexus kann nicht hergestellt werden. Bitte wenden Sie sich an ihre Administratoren, damit diese den Nexus und die Projektkonfiguration überprüfen." . Wie man sehen kann dienen die technischen Fehler der Problemlösung und helfen dem Benutzer diese zu verstehen und ggf. auch zu beheben.

Generische Fehler

Generische Fehler dienen dazu, komplexe Probleme oder unbehandelte Fehler durch eine nutzerfreundliche, generische Fehlermeldung zu ersetzen.

2. Sammlung von Fehlercodes und Übersetzungstexten an zentraler Stelle

Alle Fehlercodes und Übersetzungstexte werden an einer zentralen Stelle gesammelt – der Datei errorMessages.go. Die Fehlertexte sind hier nach Sprache (aktuell nur deutsch) gruppiert.

3. Fehlerbehandlung in Request-Handlern über zentrale Fehlerbehandlungsmethode

Jeder Endpunkt bekommt einen eigenen Kontextfehler (s. o.) zugewiesen, welcher beim Auftreten eines Fehlers als Top-Level-Fehler zurückgegeben wird.

Für die Fehlerbehandlung in den Request-Handlern gibt es in der Datei requestErrorHandler.go im Paket customerror die Methode HandleErrorAndShouldAbort, die für alle Requests-Handler-Methoden die Fehlerbehandlung übernimmt.

Die Methode prüft, ob durch den aufgetretenen Fehler der aktuelle Request abgebrochen werden soll, und schreibt den Fehler, in den Request-Context.

Der Default-Status-Code, der in den Request-Kontext geschrieben wird, ist 500 - interner Server-Fehler. In den Request-Handlern kann und soll jedoch für bekannte Fehler der korrekte Status-Code definiert werden. So ist z. B. der korrekte Status-Code für den Fehlerfall bei der Abfrage eines Projekts, wenn das Projekt nicht gefunden werden kann, 404-Status nicht gefunden. Die Definition dieser Status-Codes erfolgt in Form einer Map in den einzelnen Methoden des Request-Handlers und wird der Methode für die Fehlerbehandlung von Requests als Parameter übergeben.

4. Eigene, konkrete Fehler außerhalb des Request-Handlers

Um an verschiedenen Stellen Fehler wiedererkennbar zu machen und auf einen konkreten Fehler reagieren zu können, ist es möglich auch außerhalb eines Request-Handlers eigene Fehler zu definieren. Dies ist in Regel für atomare Fehler, die im eigenen Code (also keine Fehler beim Aufruf einer anderen Methode) auftreten, sinnvoll.

Beispiel: Anhand des Namens soll der passende Collector zum Sammeln von Artefakten erzeugt und zurückgeliefert werden. Wenn zu dem Namen kein passender Collector gefunden werden kann, soll ein Fehler zurückgeliefert werden. Hier wird ein eigens definierter Fehler, der besagt, dass kein Collector mit entsprechenden Namen existiert, verwendet. Es handelt sich hierbei um einen atomaren Fehler, der technisch dann zurückgeliefert wird, wenn für den als Parameter übergebenen Namen kein entsprechender Collector existiert. Im Request-Handler kann für diesen Fehler dann anhand des Fehler-Codes ein separater Status-Code definiert werden.

Für nicht atomare Fehler oder Fehler die nicht gesondert erkennbar sein müssen, kann weiterhin fmt.errorf(...) verwendet werden.

Richtlinien – Frontend

1. Persistente Fehlermeldungen

Fehlermeldungen sollen nach ihrer Anzeige nicht automatisch geschlossen werden.

2. Toasts mit CustomSnackbar

Erfolgreiche oder fehlerhafte Operationen, die als Toast Benachrichtigung für den Benutzer angezeigt werden, müssen die exportierten Funktionen showSuccess und showError der CustomSnackbar benutzen. Die CustomSnackbar stellt die Formatierung und Barrierefreiheit der Benachrichtigungen sicher.