Status

Status类型定义了适合不同编程环境的逻辑错误模型，包括REST API和RPC API。它由gRPC使用。误差模型设计为：

  • 大多数用户易于使用和理解
  • 足够灵活，满足意想不到的需求

概述

Status消息包含三部分数据：错误代码、错误消息和错误详细信息。错误代码应该是google.rpc.Code的枚举值，但如果需要，它可以接受其他错误代码。错误消息应该是面向开发人员的英文消息，帮助开发人员理解和解决错误。如果需要本地化的面向用户的错误消息，请将本地化消息放入错误详细信息中或在客户端中进行本地化。可选的错误详细信息可以包含有关错误的任意信息。 google.rpc包中有一组预定义的错误详细信息类型，可用于常见错误情况。

语言映射

Status消息是错误模型的逻辑表示，但不一定是实际的传输格式。当Status消息暴露在不同的客户端库和不同的有线协议中时，它可以进行不同的映射。例如，它可能会映射到 Java 中的某些异常，但更可能映射到 C 中的某些错误代码。

其他用途

错误模型和Status消息可用于各种环境（无论有或没有 API），以在不同环境中提供一致的开发人员体验。

该误差模型的使用示例包括：

  • 部分错误。如果服务需要向客户端返回部分错误，它可以在正常响应中嵌入Status来指示部分错误。

  • 工作流程错误。典型的工作流程有多个步骤。每个步骤可能有一个用于错误报告的Status消息。

  • 批量操作。如果客户端使用批量请求和批量响应，则应直接在批量响应内使用Status消息，每个错误子响应对应一个状态消息。

  • 异步操作。如果 API 调用在其响应中嵌入异步操作结果，则应使用Status消息直接表示这些操作的状态。

  • 记录。如果某些 API 错误存储在日志中，则出于安全/隐私原因而需要进行任何剥离后，可以直接使用消息Status 。

JSON 表示
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
领域
code

number

状态代码，应该是google.rpc.Code的枚举值。

message

string

面向开发人员的错误消息，应为英文。任何面向用户的错误消息都应本地化并在google.rpc.Status.details字段中发送，或由客户端本地化。

details[]

object

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。

包含任意类型字段的对象。附加字段"@type"包含标识类型的 URI。示例： { "id": 1234, "@type": "types.example.com/standard/id" } 。