什么是幂等请求？

Scrapeless Scraping API接受经过身份验证的HTTP请求，以进行结构化的网页数据任务，并通过文档响应状态公开请求结果。

定义和简短回答

幂等请求对服务器状态的影响是相同的，无论该请求是应用一次还是多次。定义关注的是请求的状态转移，而不是相同的响应体、相同的状态代码或副作用的缺失。服务器可以记录每个调用，更新指标，并返回不同的元数据，同时仍然保持相同的资源效果。关键是重复交付不会在第一个成功应用的效果之外产生额外的资源变化。

HTTP通过方法语义将GET、HEAD、OPTIONS、TRACE、PUT和DELETE定义为幂等的。安全方法是幂等的，因为客户端并没有请求状态变更。PUT是幂等的，因为向相同目标发送相同的完整表示会使该目标保持在请求状态中。DELETE是幂等的，因为在第一次成功删除后，目标仍然被移除，即使后续响应报告资源不再存在。POST和PATCH默认不是幂等的，因为重复应用可能会创建或累积变化。

当分布式系统无法判断操作是否完成时，幂等性变得重要。客户端可能发送请求，服务器可能提交更改，而响应可能在客户端读取之前丢失。如果操作具有稳定的身份，服务器可以识别重复提交并返回记录的结果，而不是再次应用业务操作。支付创建、作业提交、Webhook消费、库存预留和消息处理在重复交付可能发生时都需要这种保护。

仅仅方法名称是不够的。实现为GET的端点如果增加计数器则违反方法语义，而POST端点可以通过唯一的操作键和存储结果提供应用级幂等性。API文档应说明身份范围、保留期限、冲突规则和响应行为。客户端不应假定每个服务以相同的方式解析自定义幂等性头。

幂等性在API中的工作原理

1. 定义操作身份。 客户端为一个逻辑操作创建一个稳定的标识符。该标识符在该操作的重复交付中必须保持不变，并且在真正的新操作中必须更改。通过租户或账户进行范围限制，以防止调用者之间的冲突。
2. 将身份绑定到有效负载。 服务器记录相关请求字段的摘要或标准化表示。如果相同的键与不同的输入一起到达，服务器应拒绝冲突，而不是默默返回与不相关操作的结果。
3. 将结果和身份一起提交。 业务变更和幂等性记录需要一个事务边界或等效的一致性设计。在更改之前记录密钥可以抑制从未完成的工作；仅在更改之后记录则会留下重复执行的窗口。
4. 返回稳定结果。 重复交付可以返回保存的资源标识符、状态和响应有效负载。传输状态在某些设计中可能有所不同，但客户端需要一个文档信号，表示相同的逻辑操作被识别而不是再次应用。

真实系统中的幂等请求

HTTP方法和幂等意图

并排视图可以防止相邻概念被视为可互换的。利用比较来确定在改变客户端或服务器行为之前哪个合同是活跃的。

幂等请求诊断和操作设计

重复结果通常是数据模型问题，而不是HTTP库问题。从客户端通过网关、应用程序日志、数据库事务和下游事件跟踪逻辑操作标识符。如果每次交付都接收一个新键，服务器无法将它们连接起来。如果密钥是稳定的，但记录在业务写入后存储并且并发仍然允许两个工作者通过第一次查找。

保留需要慎重的政策。一个永久保存的密钥会产生无限制的存储；一个移除得太快的密钥无法再保护缓慢或延迟的重复交付。正确的时间窗口遵循业务流程、消息交付保证和争议期。存储足够的信息以检测带有不同有效载荷的密钥重用，并保护存储的响应如果它们包含个人或敏感数据。

幂等性并不替代并发控制。两个不同的操作密钥仍然可以在同一库存行或账户余额上竞争。使用数据库约束、条件更新、版本字段或锁定以确保共享状态的不变量。幂等性处理重复意图；并发控制处理竞争意图。

幂等请求实施清单

下面的清单将概念转化为可验证的工程工作。仅应用与活跃协议和产品合同匹配的项目，但保持证据在一起，这样其他工程师可以重建决策。

• 选择接受身份的逻辑操作并记录何时客户端必须创建一个新身份。
• 通过账户、端点或资源作用域密钥，以便不相关的调用者无法冲突。
• 将密钥与有效载荷指纹进行比较，拒绝不匹配的重用。
• 以事务一致的语义存储业务结果和身份。
• 对于已识别的重复交付，返回原始资源标识符和结果。
• 根据现实的交付和业务时间线设置保留窗口。
• 测试同时提交相同密钥并确认只有一个业务效果被提交。

实施后，测试正常行为、边界、格式错误的输入、缺失状态、并发活动和故意拒绝访问的控制环境。记录每种情况的预期状态、主体形状、结束条件和状态转换。生产监控应报告测试期间使用的相同维度，以便能够将事件与已知基准进行比较。

文档应在接口的每一侧命名责任。客户端需要必填字段、稳定标识符、排序规则、限制、终端信号和错误含义。操作员需要内部政策、存储或路由决策、可观察字段和安全的公共响应。模糊合同使团队在错误的层次上修复可见症状。

与幂等请求的常见错误

不要仅从一个字段推断成功、缺失、权限、顺序或完成，而不考虑周围的合同。状态代码、令牌、页面大小和传输头各自回答一个狭窄的问题。响应体、方法、身份、过滤器、协议版本和服务器文档提供其余的含义。

不要以简单性为名删除诊断上下文。省略请求标识符、目标、版本、作用域或边界的简短日志行可能会将小缺陷变成数小时的猜测。同时，可观察性必须删去凭据、会话秘密、签名URL和敏感有效载荷字段。

不要将临时操作性变通方案变成永久合同。修复基础的顺序、权限、路由、节奏、框架或错误映射问题，并添加回归检查。当故障是明确和可控时，系统才会变得可靠，而不是当一次手动执行恰好完成。

结论

幂等请求由收敛的服务器状态定义：一个应用程序和几个相同的应用程序具有相同的预期效果。HTTP方法提供有用的默认值，但生产API仍然需要正确的端点行为、稳定的操作标识符、事务存储、有效载荷冲突检查和独立的并发控制。将幂等性视为业务合同的一部分，而不是客户端的一种便利。