引言

幂等：通常是指对于同一用户操作，不管发送了多少次重试请求，只要在幂等追踪窗口内，那么就会有、且仅有一次请求会成功 commit 实际的操作，并且总会返回相同的响应。

在企鹅物流数据统计的汇报 API 中，幂等实现是为了保证在弱网情况下，可以在进行多次重试的同时，依然保证此次汇报行为仅被记为一次操作（而非由于重试而被记为重复的多次汇报）。换句话说，这使得安全地重试变为可能。

参数

• 幂等 Key 格式限制：建议长度 64（最长长度 128）、且仅包括 RegEx [A-Z][a-z][0-9] 范围内的字符
• 幂等追踪窗口大小：6 小时
• 建议使用的重试策略：
  • 退避函数：指数退避 Exponential Backoff
    • 乘数/Multiplier：1.5
    • 随机因数/Randomization Factor（取决于实现）：0.5
  • 最大重试次数：5 次
• 建议使用的超时时间：10 秒

接入指引

1. 生成一个 幂等 Key。幂等 Key 需于整个「此次欲发送请求的所有重试尝试」内均保持一致。例如：ZIO4HoCtw1qOFI8IzweE1KEC2jP12vkdmWdaXdmsDpvMXyT6MSN3oBz32mkWuxCT

2. 在请求中添加 Header，键为 X-Penguin-Idempotency-Key、值为 幂等 Key。

   1. 例如：X-Penguin-Idempotency-Key: ZIO4HoCtw1qOFI8IzweE1KEC2jP12vkdmWdaXdmsDpvMXyT6MSN3oBz32mkWuxCT

3. (可选) 在请求中添加汇报当前请求重试次数 Header，键为 X-Penguin-Idempotency-Retry、值为：

   1. 一个以 ; 分割的 Key-Value 组；对于每个 Key-Value 组：

      1. 以 key=value 格式体现，例如 io=1 cn=2
      2. key 为 io cn 中的一个，为了代表对应 value 值的对应域名后缀 (TLD)
      3. value 为对应 key 的重试次数，从 0 开始计数

   2. 假设一 App 的重试策略为：「先向 io 发送请求并最多发送 5 次请求（最多重试 4 次）、若 5 次请求均失败，则向 cn 发送请求并最多发送 5 次请求（最多重试 4 次）」，那么此 App 需要发送的 X-Penguin-Idempotency-Retry 、对于各个请求来说、即为（排序为最前为最先请求）：

      X-Penguin-Idempotency-Retry: io=0
      X-Penguin-Idempotency-Retry: io=1
      X-Penguin-Idempotency-Retry: io=2
      X-Penguin-Idempotency-Retry: io=3
      X-Penguin-Idempotency-Retry: io=4
      X-Penguin-Idempotency-Retry: io=4; cn=0
      X-Penguin-Idempotency-Retry: io=4; cn=1
      X-Penguin-Idempotency-Retry: io=4; cn=2
      X-Penguin-Idempotency-Retry: io=4; cn=3
      X-Penguin-Idempotency-Retry: io=4; cn=4
      

4. 发送请求。

   1. 若请求发送成功且收到了任何非 5xx 的响应，则跳出重试循环并宣告此提交操作已完成。
   2. 若请求失败，则在退避 (Backoff) 后，重新发送在第 2 步添加过幂等 Key 的请求。注意，需要重用此前生成的 幂等 Key。

注意

1. 仅在收到 5xx 范围内的响应、或在超时时间内并未收到响应时尝试重试。不要在收到 2xx/3xx/4xx 响应时重试。这通常是因为客户端所发送的请求本身就是不合法的，且携带此 幂等 Key 的请求已经至此处理完毕，并在幂等追踪窗口内将总是返回完全一致的响应，因此在收到此类响应后重试是无意义的。