幂等性边界：请求体重试时的语义差异检测与处理策略

引言：幂等性的非显而易见边界

幂等性（Idempotency）是分布式系统设计的基石概念。简单来说，一个幂等接口意味着调用方无法观察到这个请求被执行了一次还是多次。这个定义看似清晰，但在工程实践中会遇到一个微妙但关键的问题：当第二次请求使用了相同的幂等 key，却携带了不同的请求体时，系统应该如何应对？

这就是 "Idempotency Is Easy Until the Second Request Is Different" 所揭示的核心矛盾。

幂等 key 的基本工作模式

在深入讨论分歧 payload 场景之前，有必要回顾标准的幂等 key 机制：

1. 客户端生成唯一标识作为幂等 key，随请求一起发送（通常放在 Idempotency-Key header 中）
2. 服务端存储 key 与对应的处理结果
3. 后续相同 key 的请求直接返回已存储的结果，跳过实际业务逻辑

# 简化的服务端伪代码
async def handle_request(idempotency_key, payload):
    existing = await idempotency_store.get(idempotency_key)
    if existing:
        return existing  # 直接返回缓存结果
    
    result = await process(payload)
    await idempotency_store.save(idempotency_key, result)
    return result

这个模式能有效防止因网络超时导致的重复执行问题。

问题的本质：key 一致 ≠ 意图一致

真正棘手的情况是：客户端使用了相同的幂等 key，却发送了内容不同的请求体。

考虑一个支付场景：

// 第一次请求
POST /payments
Idempotency-Key: uuid-abc123
{"amount": 100, "currency": "CNY", "recipient": "alice"}

// 第二次请求（使用相同 key）
POST /payments
Idempotency-Key: uuid-abc123
{"amount": 200, "currency": "CNY", "recipient": "alice"}

第二次请求并非 "重试"—— 它是一个金额翻倍的支付操作。如果系统仅依赖 key 匹配就返回缓存结果，将导致严重的业务逻辑错误。

Luca Palmieri 在其关于幂等性的深度分析中明确指出：

"two different requests, same idempotency key = the first request is processed, the second one is rejected."

这意味着语义验证（semantic validation）是幂等实现中不可或缺的环节。

三种检测与处理策略

策略一：Payload Fingerprint（负载指纹）

在存储结果时，同时存储请求体的哈希值（fingerprint）。后续请求到来时，不仅验证 key 是否匹配，还要验证 payload 的指纹是否一致。

import hashlib
import json

def compute_fingerprint(payload: dict) -> str:
    canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
    return hashlib.sha256(canonical.encode()).hexdigest()

async def handle_request(idempotency_key, payload):
    fingerprint = compute_fingerprint(payload)
    
    existing = await idempotency_store.get(idempotency_key)
    
    if existing:
        if existing['fingerprint'] == fingerprint:
            return existing['result']  # 真正的重试
        else:
            return Response(409, body="Conflict: payload mismatch")  # 语义冲突
    
    result = await process(payload)
    await idempotency_store.save(idempotency_key, {
        'fingerprint': fingerprint,
        'result': result
    })
    return result

优点：实现简单，验证可靠 缺点：需要额外的存储空间；任何 payload 变化都会导致冲突

策略二：语义关键字段验证

不是对整个 payload 做指纹比对，而是只验证业务上关键的字段组合。这在某些场景下更灵活 —— 比如允许注释字段的变更，但不允许金额变化。

# 定义哪些字段影响幂等语义
CRITICAL_FIELDS = ['amount', 'currency', 'recipient']

def extract_semantic_identity(payload: dict) -> tuple:
    key_parts = tuple(payload.get(f) for f in CRITICAL_FIELDS)
    return key_parts

async def handle_request(idempotency_key, payload):
    semantic_id = extract_semantic_identity(payload)
    
    existing = await idempotency_store.get(idempotency_key)
    
    if existing:
        if existing['semantic_id'] == semantic_id:
            return existing['result']
        else:
            # 关键业务字段变更，需要人工介入或拒绝
            await alert_ops(f"Idempotency conflict for {idempotency_key}")
            return Response(409, body="Conflict: critical fields changed")

这种方式更适合领域模型复杂的业务系统，但需要业务方明确定义 "关键字段" 集合。

策略三：时间窗口与置信度判断

如果系统无法获取完整的 payload 历史，可以采用基于时间的启发式方法：同一个 key 在短时间内（比如 30 秒）出现 payload 变更，更可能是客户端 bug 或恶意请求；在较长时间后（比如 24 小时后）出现变更，则可能是用户的合法新操作。

async def handle_request(idempotency_key, payload, now=None):
    now = now or datetime.utcnow()
    
    existing = await idempotency_store.get(idempotency_key)
    
    if existing:
        time_diff = now - existing['created_at']
        
        if existing['payload'] == payload:
            return existing['result']
        elif time_diff < timedelta(minutes=1):
            # 短时间内 payload 变更，视为异常
            return Response(400, body="Suspicious retry with different payload")
        else:
            # 长时间后的 payload 变更，允许作为新操作处理
            # 但需要生成新的幂等 key（或清除旧记录）
            await idempotency_store.delete(idempotency_key)
            # 继续处理新请求...

并发场景下的事务隔离

即使正确检测了 payload 差异，并发请求仍会带来额外的复杂性。考虑这个场景：

1. 请求 A 到达，开始处理
2. 请求 B 到达（相同 key，不同 payload）
3. 请求 A 完成，存储结果

根据具体的事务隔离级别，PostgreSQL 对此有不同行为：

• READ COMMITTED（默认）：第二个 UPDATE 操作会等待第一个事务完成，这是最自然的处理方式
• REPEATABLE READ 或 SERIALIZABLE：第二个事务可能直接失败并报错 could not serialize access due to concurrent update

这意味着幂等实现不能盲目使用更严格的隔离级别，否则会导致不必要的失败。

-- 正确的并发处理：在 READ COMMITTED 级别下
INSERT INTO idempotency (key, status, payload_fingerprint, result)
VALUES ($1, 'processing', $2, NULL)
ON CONFLICT (key) DO NOTHING;

-- 检查是否插入成功，决定是处理还是等待

总结与工程建议

处理幂等 key 相同但 payload 不同的场景，需要在三个维度做出决策：

在设计幂等系统时，建议提前明确以下问题：

1. 哪些字段的变化意味着 "不同的意图"？
2. 冲突发生时的默认行为是什么（拒绝 vs 允许）？
3. 是否需要审计日志记录所有冲突事件？

参考资料：

• Luca Palmieri, "An In-Depth Introduction To Idempotency", Zero To Production In Rust — https://www.lpalmieri.com/posts/idempotency/
• Stripe API Documentation, "Idempotency" — https://stripe.com/docs/idempotency

web