我该如何处理错误？

在与uapiPro API进行集成时，构建一套稳定、可靠的错误处理机制是保障您的应用程序健壮运行的基石。本指南将为您详细阐述uapiPro的错误处理哲学，并提供覆盖多种主流编程语言的最佳实践代码，帮助您优雅地处理API调用中的所有可能情况。

核心原则

我们的API设计遵循两大核心原则：

1. HTTP 状态码

uapiPro严格遵守 IETF RFC 7231 规范，使用HTTP状态码作为API请求结果的首要且唯一的判断依据。

• 成功 (2xx系列): 当您收到 200 OK 或 201 Created 等 2xx 状态码时，代表您的请求已被服务器成功处理。
• 失败 (4xx 或 5xx系列): 当您收到 4xx (客户端错误) 或 5xx (服务器端错误) 状态码时，代表请求失败。

2. 响应体 (Response Body)

响应体的结构完全取决于HTTP状态码所代表的请求结果。

当请求成功时，响应体将直接包含您所请求的核心业务数据。为了保持数据载荷的纯净与高效，成功的响应体中不会包含 code 等状态字段。

当请求失败时，响应体将包含一个标准化的错误对象，以帮助您定位问题。

标准错误模型

所有非 2xx 的响应都将返回一个遵循以下结构的JSON对象：

• code (string): 机器可读的错误代码。您的程序可以基于这个字段来执行特定的错误处理逻辑。例如 INVALID_ARGUMENT, NOT_FOUND。
• message (string): 人类可读的错误描述。主要用于开发调试、记录日志或在界面上向用户展示提示。
• details (object): 可选字段。一个包含额外错误详情的对象，其具体结构取决于发生的错误类型。

最佳实践：统一处理流程

我们建议您在代码中实现以下标准处理流程：

1. 发起API请求。
2. 检查网络层错误：确保请求本身没有因为网络问题（如DNS解析失败、连接超时）而失败。
3. 判断HTTP状态码：
   • 如果状态码为 200 OK，则进入成功处理逻辑。
   • 如果状态码为 4xx 或 5xx，则进入失败处理逻辑。
4. 解析响应体：
   • 在成功逻辑中，将响应体解析为您为该接口定义的数据模型。
   • 在失败逻辑中，将响应体解析为上文定义的标准错误模型。
5. 执行业务逻辑：基于解析出的数据或错误信息，继续执行您的应用程序逻辑。

代码示例

以下，我们将以调用 /misc/weather 接口为例，演示在不同语言中如何实现上述最佳实践。我们将分别演示查询“北京”（一个会成功的请求）和“火星”（一个会返回410 Gone错误的请求）的情况。