使用 REST API 时常见的错误有哪些？

直接回答

使用 REST API 时的常见错误通常源于误解：将 REST 机制视为能保证结果，假设数据始终可用或一致，以及未能区分稳定行为（HTTP 请求的工作方式）与可变条件（提供商策略、延迟、错误和成本）。一种中立的理解方式是：REST 定义了客户端如何发送请求以及服务器如何响应，但它并不能自动确保在任何市场环境下结果都是可用、及时或盈利的。

机制或定义

REST API 是客户端使用 HTTP 方法（如 GET、POST、PUT、DELETE）和结构化消息（通常为 JSON）与服务器通信的一种方式。其关键机制是稳定的：你向特定端点发送请求，包含头部信息（例如身份验证），服务器返回状态码和响应正文（或错误）。

常见误解一：将“技术成功”与“业务成功”混为一谈。一个请求可能返回 200 OK，但其负载内容却无法使用（字段缺失、单位异常或结果不完整）。

常见误解二：在未检查格式的情况下假设字段含义。例如，时间戳可能是不同时区的字符串，数值可能以字符串形式表示，标识符可能具有特定作用域。

常见误解三：在示例中忽略假设前提。如果你包含计算，必须明确输入和单位约定（例如，金额是基础货币还是报价货币单位，是否应用了四舍五入）。若无明确假设，即使逻辑正确也可能导致错误预期。

证据或示例

一种常见失败模式是“在测试中正常，但在生产中失效”。这通常是因为测试条件掩盖了可变性。可变条件的示例包括网络延迟、间歇性故障以及服务商端的限流。

另一个常见错误是依赖单一响应类型。REST API 通常为不同结果返回不同状态码。如果客户端假设所有响应都符合成功模式，当收到错误体时程序可能崩溃。

一个实用的中立检查方法是将“请求结果”映射到“响应结果”。例如：

• 检查你的代码是否能处理非 2xx 状态码。
• 验证解析规则是否与文档中定义的响应模式一致。
• 确认你是否能处理空列表、缺失字段和分页。

如果你正在构建自动化工作流，还应谨慎处理幂等性。在超时后重发请求，若端点未设计为安全重试，则可能导致重复操作。

限制与风险

至少存在一种实质性限制或失败模式：重试、速率限制、超时和格式错误的请求。这些不仅仅是客户端的 bug，而是真实 HTTP 系统中的预期行为。

需注意的中立“警示信号”包括：

• 对非 2xx 响应没有明确的错误处理策略。
• 对限流或临时中断没有退避或重试策略。
• 解析假设未通过真实响应样本验证。
• 计算忽略了四舍五入规则或单位约定。

仍存在重要不确定性：结果会因成本、执行行为以及 API 使用环境中的司法管辖区或合规要求而异。此外，历史关系（例如以往响应时间模式）并不能保证未来结果。

验证或下一个问题

要独立验证特定 REST API 的事实，请采用文档优先的方法并测试可观察的响应。检查：

• 身份验证方法和所需头部。
• 请求/响应模式，包括错误格式。
• 分页、速率限制、超时和幂等性预期。

一个好的后续问题是：“我的客户端目前处理了哪些具体端点和响应码——特别是错误、空结果和重试？”如果该检查清单不完整，误解的可能性将高于正确预期。