使用API时的订单重复：原因与防护

为什么一次操作后会出现重复

面板所有者可能只点击一次按钮，却看到多个相同的订单：订阅者、浏览量、反应或其他服务。通常问题不在于点击本身，而在于客户端、API、数据库和供应商之间的链路。

从服务器的角度来看，“一次请求”并不总是只有一次。客户端可能没有收到响应，重新发送，而第一次操作已经成功保存。有时订单在面板数据库中只创建一次，却向供应商发送了两次。这是不同的场景，修复方式也不同。

超时并不意味着订单未创建

最常见的原因是客户端等待响应的时间有限。服务器接受请求，创建订单，但在设定的超时时间之后才响应。客户端认为操作失败并重新发送。

结果第一个订单已经在数据库中，而第二个请求又创建了一个。这种情况在外部API响应缓慢、队列过载或服务之间连接不稳定时尤为常见。

超时只说明没有收到响应，而不说明请求未被处理。

客户端自动重试

HTTP请求库、后台任务和集成服务经常会自动重试请求。触发原因可能是连接错误、服务器响应代码、网络中断或响应时间过长。

重试本身是有用的：它减少了临时故障时丢失订单的数量。这种方法的缺点在于，如果没有防止重复处理的保护，它会把任何网络不稳定都变成重复订单。

• 重试可能在网站或机器人代码中触发；
• 队列可能重新启动任务；
• 代理或集成模块可能重试请求；
• 操作员可能在出错后手动重新提交订单。

重复请求在第一次响应之前到达

有时两个相同的请求确实几乎同时到达API。例如，用户两次提交表单，前端没有锁定按钮，或者后台任务在第一个完成之前重新启动。

如果处理程序先检查订单是否存在，然后创建它，两个并行操作可能同时通过检查。每个都会看到订单尚不存在，每个都会添加一条新记录。

这种情况称为竞态条件。代码中的简单预检查不能完全防止它。没有数据库级别限制的检查的缺点在于，它在并行负载下会失效。

订单已写入，但API响应丢失

请求经过多个阶段：服务器接收数据、创建记录、将任务放入队列、发送响应。故障可能发生在其中任何环节之间。例如，数据库已确认订单创建，但在向客户端传输响应之前连接中断。

客户端不知道订单是否被接受，并重复操作。没有单独验证机制的API会将请求视为新的。在日志中，这通常看起来像是服务“自己”创建了两个订单，尽管它收到了两次传入请求。

用于创建订单的幂等键

创建操作需要唯一的幂等键。客户端在首次发送之前生成它，并随订单参数一起传递。因超时或错误而重试时使用相同的键。

API将键与处理结果一起保存。如果收到带有已知键的请求，服务器不会创建新订单，而是返回第一次调用的结果：订单标识符、其状态或之前生成的错误。

一个键应对应一个业务操作，而不是一个HTTP连接。

该方法的缺点在于，键需要存储、按规则清理并在API端验证。如果每次重试都生成新键，保护将不会生效。如果对不同订单使用同一个键，部分新操作将被错误地拒绝。

唯一性应由数据库控制

幂等性最好辅以数据库中的唯一性约束。为此选择能唯一描述订单的组合：客户端内部标识符、幂等键、服务类型和其他必要字段。

即使两个处理程序同时到达创建阶段，数据库也应拒绝第二条记录。冲突后，API返回现有订单，而不是没有说明的错误。

严格唯一约束的缺点在于，不能仅基于链接或用户名来构建。客户端可能有意在同一频道多次订购同一服务。过于宽泛的约束会阻止正常的重复购买。

队列可能多次投递任务

任务队列通常按照“至少投递一次”的原则工作。如果工作进程处理了任务但未能确认其完成，队列可能将同一任务重新投递给另一个工作进程。

对队列来说，这是不丢失任务的正常方式。对于没有幂等性的订单创建来说，这是重复的来源。任务标识符或单独的操作键必须传递到最终处理程序，包括向供应商发送订单的模块。

禁用重复投递的缺点在于，工作进程崩溃时部分订单可能丢失。更安全的做法是接受可能的重复，并使处理程序对其具有韧性。

重复出现在面板与供应商之间

内部订单可能只创建一次，但向外部API发送了两次请求。原因相同：面板没有收到供应商的响应，决定重新发送。如果供应商已经接受了第一个请求，其侧将出现两个相同的申请。

需要将内部订单与外部订单单独关联：发送标识符、幂等键或保存的供应商响应。不能认为进入自己面板的入口保护会自动保护出站调用。

与第三方API核对的缺点在于，并非每个供应商都支持按外部键搜索。那时不得不记录发送尝试并单独处理不确定状态。

Webhook不应创建新订单

Webhook通知变更：订单已接受、已启动、已完成、已取消或需要检查。当Webhook处理程序将通知视为重新创建订单的命令时，就会出错。

同一个Webhook可能重复到达。如果发送方没有收到确认，会重复投递，而且通知有时会乱序到达。处理程序应通过外部标识符找到现有订单并更新状态。

仅按接收时间处理Webhook的缺点在于，迟到的通知可能用过期状态覆盖当前状态。需要事件标识符、状态版本或清晰的转换规则。

哪些记录有助于找到重复来源

调查时仅看到两个订单号是不够的。需要每个处理阶段的数据：请求时间、幂等键、客户端标识符、订单参数、后台任务编号、外部API响应和重试发送尝试。

• 按操作键而非仅按链接匹配重复；
• 检查传入API日志中是否有相同请求；
• 查看任务是否在队列中重复；
• 将内部订单创建与向供应商发送分开；
• 收到响应后立即保存申请的外部标识符。

日志过短的缺点在于，问题来源在来得及分析之前就消失了。过度记录的缺点在于，记录中可能包含令牌、个人数据和其他敏感字段，因此需要对其进行掩码处理。

如何处理不确定的请求结果

超时后不能立即用新数据重新创建订单。首先API应通过幂等键或客户端标识符检查操作。如果找到订单，返回其当前状态。如果处理仍在进行，客户端收到等待状态。

1. 在首次请求之前创建操作键。
2. 每次重试时发送相同的键。
3. 在同一个受保护的数据库操作中保存键和订单。
4. 将操作标识符传递到队列和外部API。
5. 重复请求时返回之前创建的订单。

这种场景需要改进API和客户端集成。其缺点在于调试更复杂、订单状态更多，但请求的重复投递不再自动意味着重复购买。