跳到主要内容

重试与幂等

正确的重试策略避免数据脏污和雪崩，幂等设计确保重复请求不产生副作用。

HTTP 方法幂等性​

方法幂等安全重试说明
GET是是只读操作，任意重试
PUT是是整体覆盖，结果一致
DELETE是是重复删除返回 404
PATCH否视情况增量更新可能叠加
POST否不安全可能创建重复资源
非幂等 POST

MimirQ 中创建数据集、上传文档等 POST 操作默认非幂等。网络超时后盲目重试可能导致重复资源。

幂等键（Idempotency-Key）​

对于需要安全重试的 POST 请求，如果 API 支持幂等键：

curl -X POST "$BASE_URL/api/v1/datasets/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "my-dataset"}'
信息

幂等键支持以 Redoc 中各接口的具体说明为准。并非所有 POST 接口都支持幂等键。

指数退避策略​

当收到 429（限流）或 503（服务不可用）时，使用指数退避重试：

import time
import random

def retry_with_backoff(func, max_retries=5, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return func()
        except RetryableError:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            delay = min(delay, 60)  # 最大 60 秒
            time.sleep(delay)

退避参数建议​

参数推荐值说明
基础延迟1 秒首次重试等待
退避倍数2x每次翻倍
抖动0-1 秒随机避免多客户端同步重试
最大延迟60 秒退避上限
最大重试次数3-5 次超过后放弃并报错

重试决策矩阵​

状态码重试?策略
401刷新 Token 后重试一次Token 刷新失败则放弃
409获取最新资源后决定可能需要业务层合并
429是使用 Retry-After Header 或指数退避
500仅幂等操作非幂等操作记录 request_id 并人工处理
502/503是指数退避

UI 防重复提交​

前端应在以下场景防止重复操作：

  • 提交按钮 — loading 状态下禁用点击
  • 表单重复提交 — 请求进行中屏蔽二次提交
  • 页面刷新 — POST 完成后重定向（PRG 模式），避免浏览器刷新重提

相关链接​