Der Status
definiert ein logisches Fehlermodell, das für verschiedene Programmierumgebungen geeignet ist, einschließlich REST-APIs und RPC-APIs. Es wird von gRPC verwendet. Das Fehlermodell ist wie folgt konzipiert:
- Für die meisten Benutzer einfach zu verwenden und zu verstehen
- Flexibel genug, um unerwartete Anforderungen zu erfüllen
Überblick
Die Status
enthält drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails. Der Fehlercode sollte ein Enum-Wert von google.rpc.Code
sein, kann aber bei Bedarf weitere Fehlercodes akzeptieren. Bei der Fehlermeldung sollte es sich um eine entwicklerorientierte englische Nachricht handeln, die den Entwicklern hilft, den Fehler zu verstehen und zu beheben . Wenn eine lokalisierte, für den Benutzer sichtbare Fehlermeldung erforderlich ist, fügen Sie die lokalisierte Nachricht in die Fehlerdetails ein oder lokalisieren Sie sie im Client. Die optionalen Fehlerdetails können beliebige Informationen zum Fehler enthalten. Im Paket google.rpc
gibt es einen vordefinierten Satz von Fehlerdetailtypen, die für häufige Fehlerbedingungen verwendet werden können.
Sprachzuordnung
Die Status
ist die logische Darstellung des Fehlermodells, entspricht jedoch nicht unbedingt dem tatsächlichen Leitungsformat. Wenn die Status
in verschiedenen Client-Bibliotheken und verschiedenen Übertragungsprotokollen verfügbar gemacht wird, kann sie unterschiedlich zugeordnet werden. Beispielsweise wird es wahrscheinlich einigen Ausnahmen in Java zugeordnet, wahrscheinlicher jedoch einigen Fehlercodes in C.
Andere Verwendungszwecke
Das Fehlermodell und die Status
können in verschiedenen Umgebungen verwendet werden, entweder mit oder ohne APIs, um eine konsistente Entwicklererfahrung in verschiedenen Umgebungen bereitzustellen.
Beispiele für die Verwendung dieses Fehlermodells sind:
Teilfehler. Wenn ein Dienst Teilfehler an den Client zurückgeben muss, kann er den
Status
in die normale Antwort einbetten, um die Teilfehler anzuzeigen.Workflow-Fehler. Ein typischer Arbeitsablauf besteht aus mehreren Schritten. Für jeden Schritt kann eine
Status
zur Fehlerberichterstattung vorhanden sein.Batch-Operationen. Wenn ein Client eine Batch-Anfrage und eine Batch-Antwort verwendet, sollte die
Status
direkt in der Batch-Antwort verwendet werden, eine für jede Fehler-Unterantwort.Asynchrone Operationen. Wenn ein API-Aufruf asynchrone Vorgangsergebnisse in seine Antwort einbettet, sollte der Status dieser Vorgänge direkt mithilfe der
Status
dargestellt werden.Protokollierung. Wenn einige API-Fehler in Protokollen gespeichert werden, kann der
Status
direkt nach der aus Sicherheits-/Datenschutzgründen erforderlichen Entfernung verwendet werden.
JSON-Darstellung | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
Felder | |
---|---|
code | Der Statuscode, der ein Enumerationswert von |
message | Eine entwicklerseitige Fehlermeldung, die auf Englisch sein sollte. Jede benutzerseitige Fehlermeldung sollte lokalisiert und im Feld |
details[] | Eine Liste von Nachrichten, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die von APIs verwendet werden können. Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld |