Waafir
本页面为机器翻译,尚待人工审核,可能存在错误。

使用幂等键安全重试

本方案展示如何在网络故障或含糊不清的错误之后安全地重试启动导入调用。POST /api/v1/monitoring/loan/imports 上的 Idempotency-Key 标头会使第二次调用返回与第一次相同的导入 ID,并附带一个新生成的上传 URL——不会创建重复的导入。

何时使用

只要您无法确定上一次启动导入调用是否已经生效,就应使用。两种典型情况:

  • 您的 HTTP 客户端在响应到达之前就抛出了超时。请求可能已经到达 Waafir 并启动了一个导入;您无从得知。
  • 您从一个非幂等的接口收到了 5xx 错误,并希望在不冒重复工作风险的情况下重试。

平台范围内的约定是:每个会更改数据的端点都接受 Idempotency-Key——这里的启动导入端点、导出端点,以及其他地方的审计变更端点。每个逻辑操作使用一个新的键;同一操作的多次重试复用同一个键。一种常见的模式是:针对每个“每日导入批次”意图生成一次 UUID v4,并将其保存在作业状态中,直到调用成功。

契约

  • 标头为 Idempotency-Key: <your-string>。最多 255 个字符。
  • 请求正文也接受 idempotencyKey 字段;两者同时存在时,以标头为准。优先使用标头——这是平台范围内的标准位置。
  • 使用相同 (orgId, idempotencyKey) 的重复调用会返回:
    • 相同的 importId,
    • 响应中的 reused: true,
    • 一个新生成的上传 URL(原 URL 会过期;新 URL 才是可以安全使用的)。
  • 使用相同的键但请求正文不同的重复调用会被拒绝;该键与原始请求结构绑定。

方案

# curl — start an import with an idempotency key, then retry safely
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Generate a fresh key per logical batch intent; keep it stable across retries.
IDEMPOTENCY_KEY="loan-import-2026-05-22-$(uuidgen)"

start_import() {
  curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
    -H "Authorization: Bearer ${PAT}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)"
}

# First call. If the network bombs out we have no idea whether the
# request landed — but the same key on the next attempt guarantees no
# duplicate import.
RESULT=$(start_import || true)

if [ -z "${RESULT}" ] || ! echo "${RESULT}" | jq -e .importId > /dev/null; then
  echo "first call ambiguous; retrying with the same idempotency key…"
  RESULT=$(start_import)
fi

echo "${RESULT}" | jq '{importId, reused, uploadUrl}'
# On a retry, reused == true; the importId matches the first call's; the
# uploadUrl is fresh.
// TypeScript — retry start-import safely with an Idempotency-Key
import { randomUUID } from "node:crypto";
import { statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-2026-05-22.ndjson";
const idempotencyKey = `loan-import-2026-05-22-${randomUUID()}`;

async function startImport() {
    return fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${PAT}`,
            "Content-Type": "application/json",
            "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({
            kind: "loan",
            filename: NDJSON_FILE,
            sizeBytes: statSync(NDJSON_FILE).size,
        }),
    });
}

// Retry up to 3 times on transient failures; the same key makes this safe.
let lastError: unknown;
let result: { importId: string; reused: boolean; uploadUrl: string } | null = null;
for (let attempt = 1; attempt <= 3; attempt++) {
    try {
        const res = await startImport();
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
        result = (await res.json()) as typeof result;
        break;
    } catch (err) {
        lastError = err;
        console.warn(`attempt ${attempt} failed; retrying with same idempotency key`, err);
        await new Promise((r) => setTimeout(r, 1_000 * attempt));
    }
}

if (!result) throw lastError;
console.log({ importId: result.importId, reused: result.reused, uploadUrl: result.uploadUrl });
# python — retry start-import safely with an Idempotency-Key
import os
import uuid
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-2026-05-22.ndjson")

idempotency_key = f"loan-import-2026-05-22-{uuid.uuid4()}"

def start_import():
    return requests.post(
        f"{BASE_URL}/api/v1/monitoring/loan/imports",
        headers={
            "Authorization": f"Bearer {PAT}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "kind": "loan",
            "filename": NDJSON_FILE.name,
            "sizeBytes": NDJSON_FILE.stat().st_size,
        },
        timeout=30,
    )

# Retry up to 3 times on transient errors. The same key makes a second
# successful call a guaranteed replay of the first.
last_exc = None
result = None
for attempt in range(1, 4):
    try:
        response = start_import()
        response.raise_for_status()
        result = response.json()
        break
    except requests.RequestException as exc:
        last_exc = exc
        print(f"attempt {attempt} failed; retrying with same idempotency key: {exc}")
        time.sleep(attempt)

if result is None:
    raise RuntimeError("all retries exhausted") from last_exc

print({
    "importId": result["importId"],
    "reused": result["reused"],
    "uploadUrl": result["uploadUrl"],
})

验证要点

首次调用成功时,reused 为 false。之后使用同一个键的任何调用中,reused 都为 true,并且 importId 与首次调用的相同。uploadUrl 在每次调用时都会重新生成,因此在旧 URL 过期后重试是安全的——请始终使用最近一次响应中的 URL。

如果您使用相同的键但不同的请求正文进行重试,API 会返回一个错误,表明该键已绑定到一个与之冲突的请求结构;请为新的意图更换一个键。