Typ Status
definiuje model błędów logicznych odpowiedni dla różnych środowisk programistycznych, w tym interfejsów API REST i interfejsów API RPC. Jest używany przez gRPC . Model błędu ma postać:
- Prosty w obsłudze i zrozumiały dla większości użytkowników
- Wystarczająco elastyczny, aby sprostać nieoczekiwanym potrzebom
Przegląd
Komunikat Status
zawiera trzy elementy danych: kod błędu, komunikat o błędzie i szczegóły błędu. Kod błędu powinien być wartością wyliczeniową google.rpc.Code
, ale w razie potrzeby może akceptować dodatkowe kody błędów. Komunikat o błędzie powinien być skierowany do programistów w języku angielskim, co pomoże programistom zrozumieć i rozwiązać błąd. Jeśli potrzebny jest zlokalizowany komunikat o błędzie skierowany do użytkownika, umieść zlokalizowany komunikat w szczegółach błędu lub zlokalizuj go w kliencie. Opcjonalne szczegóły błędu mogą zawierać dowolne informacje o błędzie. W pakiecie google.rpc
znajduje się predefiniowany zestaw typów szczegółów błędów, których można używać w przypadku typowych błędów.
Mapowanie języka
Komunikat Status
jest logiczną reprezentacją modelu błędu, ale niekoniecznie jest to rzeczywisty format przewodu. Gdy komunikat Status
jest udostępniany w różnych bibliotekach klienckich i różnych protokołach sieciowych, można go różnie mapować. Na przykład prawdopodobnie zostanie zamapowany na pewne wyjątki w Javie, ale bardziej prawdopodobne jest, że zostanie zamapowany na niektóre kody błędów w C.
Inne zastosowania
Modelu błędów i komunikatu Status
można używać w różnych środowiskach, z interfejsami API lub bez, aby zapewnić spójne środowisko programistyczne w różnych środowiskach.
Przykładowe zastosowania tego modelu błędu obejmują:
Częściowe błędy. Jeśli usługa musi zwrócić klientowi częściowe błędy, może osadzić
Status
w normalnej odpowiedzi, aby wskazać częściowe błędy.Błędy przepływu pracy. Typowy przepływ pracy składa się z wielu etapów. Każdy krok może zawierać komunikat
Status
umożliwiający raportowanie błędów.Operacje wsadowe. Jeśli klient korzysta z żądania wsadowego i odpowiedzi wsadowej, komunikat
Status
powinien zostać użyty bezpośrednio w odpowiedzi wsadowej, po jednym dla każdej pododpowiedzi na błąd.Operacje asynchroniczne. Jeśli wywołanie API osadza w odpowiedzi wyniki operacji asynchronicznej, status tych operacji powinien być reprezentowany bezpośrednio za pomocą komunikatu
Status
.Logowanie. Jeśli w logach zapisane są jakieś błędy API, komunikat
Status
może zostać użyty bezpośrednio po usunięciu danych ze względów bezpieczeństwa/prywatności.
Reprezentacja JSON | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
Pola | |
---|---|
code | Kod stanu, który powinien być wartością wyliczeniową |
message | Komunikat o błędzie skierowany do programisty, który powinien być w języku angielskim. Każdy komunikat o błędzie wyświetlany użytkownikowi powinien zostać zlokalizowany i przesłany w polu |
details[] | Lista komunikatów zawierających szczegóły błędu. Istnieje wspólny zestaw typów komunikatów, z których mogą korzystać interfejsy API. Obiekt zawierający pola dowolnego typu. Dodatkowe pole |