Loại Status
xác định mô hình lỗi logic phù hợp với các môi trường lập trình khác nhau, bao gồm API REST và API RPC. Nó được sử dụng bởi gRPC . Mô hình lỗi được thiết kế như sau:
- Đơn giản để sử dụng và hiểu cho hầu hết người dùng
- Đủ linh hoạt để đáp ứng nhu cầu bất ngờ
Tổng quan
Thông báo Status
chứa ba phần dữ liệu: mã lỗi, thông báo lỗi và chi tiết lỗi. Mã lỗi phải là giá trị enum của google.rpc.Code
nhưng có thể chấp nhận các mã lỗi bổ sung nếu cần. Thông báo lỗi phải là thông báo bằng tiếng Anh dành cho nhà phát triển để giúp nhà phát triển hiểu và giải quyết lỗi. Nếu cần một thông báo lỗi được bản địa hóa dành cho người dùng, hãy đặt thông báo đã bản địa hóa đó vào chi tiết lỗi hoặc bản địa hóa nó trong ứng dụng khách. Chi tiết lỗi tùy chọn có thể chứa thông tin tùy ý về lỗi. Có một tập hợp các loại chi tiết lỗi được xác định trước trong gói google.rpc
có thể được sử dụng cho các tình trạng lỗi phổ biến.
Ánh xạ ngôn ngữ
Thông báo Status
là sự trình bày logic của mô hình lỗi, nhưng nó không nhất thiết phải là định dạng dây thực tế. Khi thông báo Status
được hiển thị trong các thư viện máy khách khác nhau và các giao thức dây khác nhau, nó có thể được ánh xạ khác nhau. Ví dụ: nó có thể sẽ được ánh xạ tới một số ngoại lệ trong Java, nhưng nhiều khả năng nó sẽ được ánh xạ tới một số mã lỗi trong C.
Công dụng khác
Mô hình lỗi và thông báo Status
có thể được sử dụng trong nhiều môi trường khác nhau, có hoặc không có API, để mang lại trải nghiệm nhất quán cho nhà phát triển trên các môi trường khác nhau.
Ví dụ sử dụng mô hình lỗi này bao gồm:
Lỗi một phần. Nếu một dịch vụ cần trả lại lỗi một phần cho máy khách, dịch vụ đó có thể nhúng
Status
vào phản hồi thông thường để chỉ ra lỗi một phần.Lỗi quy trình làm việc. Một quy trình công việc điển hình có nhiều bước. Mỗi bước có thể có thông báo
Status
để báo cáo lỗi.Hoạt động hàng loạt. Nếu khách hàng sử dụng yêu cầu hàng loạt và phản hồi hàng loạt thì thông báo
Status
phải được sử dụng trực tiếp bên trong phản hồi hàng loạt, một thông báo cho mỗi phản hồi phụ lỗi.Hoạt động không đồng bộ. Nếu lệnh gọi API nhúng hoạt động không đồng bộ dẫn đến phản hồi của nó thì trạng thái của các hoạt động đó sẽ được thể hiện trực tiếp bằng thông báo
Status
.Ghi nhật ký. Nếu một số lỗi API được lưu trữ trong nhật ký, thông báo
Status
có thể được sử dụng trực tiếp sau bất kỳ thao tác xóa nào cần thiết vì lý do bảo mật/quyền riêng tư.
Biểu diễn JSON | |
---|---|
{ "code": number, "message": string, "details": [ { "@type": string, field1: ..., ... } ] } |
Lĩnh vực | |
---|---|
code | Mã trạng thái phải là giá trị enum của |
message | Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi mà người dùng gặp phải phải được bản địa hóa và gửi trong trường |
details[] | Danh sách các thông báo chứa chi tiết lỗi. Có một nhóm loại thông báo chung để API sử dụng. Một đối tượng chứa các trường thuộc loại tùy ý. Trường bổ sung |