Index
Status
(Nachricht)
Status
Der Typ Status
definiert ein logisches Fehlermodell, das für verschiedene Programmierumgebungen wie REST APIs und RPC APIs geeignet ist. Es wird von gRPC verwendet. Das Fehlermodell sollte folgende Eigenschaften haben:
- Nutzerfreundlich und leicht verständlich
- Flexibel genug, um sich an unerwartete Anforderungen anzupassen
Überblick
Die Meldung Status
enthält die folgenden drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails. Der Fehlercode ist idealerweise ein ENUM-Wert von google.rpc.Code
, kann aber gegebenenfalls weitere Fehlercodes annehmen. Die Fehlermeldung sollte eine an den Entwickler gerichtete Meldung auf Englisch sein, mit der Entwickler den Fehler verstehen und beheben können. Falls eine an den Nutzer gerichtete übersetzte Fehlermeldung benötigt wird, sollte sie zu den Fehlerdetails hinzugefügt oder clientseitig lokalisiert werden. Die optionalen Fehlerdetails können beliebige Informationen zum Fehler enthalten. Das Paket google.rpc
enthält eine Reihe vordefinierter Fehlerdetailtypen, die für normale Fehlerbedingungen verwendet werden können.
Sprachenzuordnung
Die Meldung Status
ist die logische Darstellung des Fehlermodells, aber dies entspricht nicht zwangsläufig dem tatsächlichen Wire-Format. Wenn die Meldung Status
in unterschiedlichen Clientbibliotheken und Wire-Protokollen angezeigt wird, kann sie auch anders zugeordnet werden. Beispielsweise wird sie in Java wahrscheinlich Ausnahmen, aber in C eher Fehlercodes zugeordnet.
Andere Anwendungen
Das Fehlermodell und die Meldung Status
können, mit oder ohne APIs, in mehreren Umgebungen verwendet werden, damit Entwickler in verschiedenen Umgebungen einheitlich arbeiten können.
Beispielanwendungen dieses Fehlermodells:
Partielle Fehler: Wenn ein Dienst Teilfehler an den Client zurückgeben muss, kann er den
Status
in die normale Antwort integrieren, um die partiellen Fehler anzuzeigen.Workflowfehler: Ein typischer Workflow umfasst mehrere Schritte. Jeder Schritt kann eine
Status
-Meldung enthalten, um Fehler zu melden.Batchvorgänge: Wenn ein Client Batchanfragen und Batchantworten nutzt, sollte jeweils eine
Status
-Meldung pro untergeordneter Fehlerantwort direkt in der Batchantwort verwendet werden.Asynchrone Vorgänge: Wenn ein API-Aufruf Ergebnisse asynchroner Vorgänge in die Antwort integriert, sollte der Status dieser Vorgänge direkt mithilfe der
Status
-Meldung dargestellt werden.Protokollierung: Wenn einige API-Fehler in Protokollen gespeichert sind, kann die Meldung
Status
im Anschluss an Entfernungen, die aus Sicherheits-/Vertraulichkeitsgründen erforderlich sind, verwendet werden.
Felder | |
---|---|
code |
Der Statuscode, der idealerweise ein ENUM-Wert von |
message |
Eine an den Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede an den Nutzer gerichtete Fehlermeldung sollte lokalisiert und im Feld |
details[] |
Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die APIs verwenden können. |