本章简单介绍Google API 的错误模型以及开发人员如何正确生成和处理错误的一般指导。
Google API 使用了简单的协议无关的错误模型,这允许我们在不同 API,不同协议(例如 gRPC 或HTTP),不同的错误上下文(如同步、批量处理、工作流错误)中提供相同的使用体验。
错误模型
错误模型由google.rpc.Status 定义。如下所示:
package google.rpc; message Status { // 容易被客户端处理的简单错误码,实际的错误码定义在`google.rpc.Code` int32 code = 1; // 易于开发者阅读的错误信息,它应该解释错误并且提供可行的解决方法 string message = 2; // 附加的错误信息,客户端能够通过它处理错误,例如重试的等待时间或者帮助页面链接 repeated google.protobuf.Any details = 3; }
因为大部分Google API 使用面向资源的设计,所以错误处理通过在大量资源上使用一小组标准错误也遵循了相同的设计原则。例如,服务端使用一个标准的google.rpc.Code.NOT_FOUND错误码加上特定的资源名来表示“未找到”错误,而不是定义不同种类的“未找到”错误。更少的错误状态减少了文档的复杂性,在客户端的库中提供更好的习惯性映射,在不限制可包含信息的情况下减少了客户端逻辑的复杂性。
错误码
Google API必须(must)使用google.rpc.Code中定义的标准错误码。单独的 API应该(should)避免定义附加错误码,因为开发者非常不喜欢为大量错误码编写处理逻辑。作为参考,每个 API 处理平均 3 个错误码意味着大部分程序逻辑在进行错误处理,这并不是好的开发体验。
错误消息
错误消息应该帮助用户轻松并快速地理解并解决API 错误。通常情况请参考如下规则:
不要假设用户非常了解你的 API。用户可能是客户端开发者、运维人员、IT 人员或者 app 的普通用户。不要假设用户了解服务实现的细节或熟悉错误上下文(例如日志分析)。如果可能的话,应构建错误消息,以便技术用户(但不一定是 API 的开发人员)可以对错误进行响应并更正。保持错误信息的简短。如果需要的话,提