Guidelines for Handling Errors in the Baseline Tool
This document describes the guidelines to be followed when handling errors in the Baseline Tool.
Guidelines - Backend
1. Struct WithCode serves as a communication medium
WithCode is a separate error type (struct) and is used within the baseline backend to pass information to the end
user in the event of an error. Attention is paid to the wording and structure of the existing errors and their error
codes and texts. These can be found in the file errorMessages.go in the package customerror. package.
The type WithCode allows to link several error messages together and thus to create very flexible and detailed error
messages. It is also possible to define and pass parameters.
In general, there are three different types of errors in the Baseline Tool: Context errors, technical errors and generic Errors
Context errors
Context errors are used to tell the user the context of the operation being performed. An example of context error
is "The projects could not be loaded". The context error is very important so that the user can easily understand the
relationship between the error message and the operation. In a concatenation of WithCode-errors, the first error
should always be a context error. Which context error belongs to a request handler method is defined in the
corresponding method itself.
Technical errors
Technical errors serve to communicate the cause of an error to the user in a simple, plausible and understandable form.
It should be noted that a technical error can consist of several technical errors. An example of a technical error is
"The connection to the Nexus cannot be established. Please contact your administrators to have them check the Nexus and the project configuration."
. As you can see, the technical errors serve to solve problems and help the user to understand them and, if necessary,
to fix them.
Generic errors
Generic errors are used to replace complex problems or unhandled errors with a user-friendly generic error message.
2. Collection of error codes and translation texts in a central location
All error codes and translation texts are collected in a central location - the file errorMessages.go. The error texts
are grouped here by language (currently only German).
3. Error handling in request handlers via central error handling method
Each endpoint is assigned its own context error (see above), which is returned as a top-level error when an error occurs.
For error handling in the request handlers there is in the file requestErrorHandler.go in the package customerror
the method HandleErrorAndShouldAbort, which handles the error handling for all request handler methods.
The method checks whether the current request should be aborted by the error that has occurred, and writes the error into the request context.
The default status code written into the request context is 500 - internal server error. In the However, the correct status code for known errors can and should be defined in the request handlers. For example, the correct status code for the error case when requesting a project, if the project cannot be found, is 404 - Status not found. The definition of these status codes takes place in the form of a map in the individual methods of the request handler and is passed as a parameter to the method for error handling of requests.
4. Own, concrete errors outside the request handler
In order to make errors recognisable in various places and to be able to react to a concrete error, it is possible to define your own errors outside of a request handler. This is usually for atomic errors that occur in the own code (i.e. no errors when calling another method).
Example: Based on the name, the appropriate collector for collecting artefacts is to be created and returned. If no matching collector can be found for the name, an error should be returned. Here a specially defined error is used, which means that no collector with the corresponding name exists. This is an atomic error, which is technically returned if no corresponding collector exists for the name passed as a parameter. In the request handler, a separate status code can then be defined for this error using the error code.
For non-atomic errors or errors that do not need to be separately identifiable, fmt.errorf(...) can still be used. can
still be used.
Guidelines - Frontend
1. Persistent error messages
Error messages should not be closed automatically after they are displayed.
2. Toasts with CustomSnackbar
Successful or erroneous operations that are displayed as a toast notification to the user must use the exported
functions showSuccess and showError of the CustomSnackbar. The CustomSnackbar ensures the formatting and
accessibility of the notifications.