JSON-RPC 幂等性：重试时防止重复写入

为什么超时的 JSON-RPC 写入不是失败的写入

重试 JSON-RPC 写入的核心风险来自一个错误假设：超时、连接重置或 5xx 响应意味着节点没有应用你的请求。实际上，请求可能已被接受、签名并广播，只是在返回途中丢失了响应。客户端看到错误，链上却看到一笔交易。盲目重试就会产生第二次应用：两笔转账、两次铸造、两个订单。

这是重复支付和重复成交订单背后的经典生产环境 bug。它并非某个提供商特有，而是任何基于不可靠网络的请求/响应协议都会有的特性。RPC 超时错误：原因与修复指南涵盖了传输层；本文涵盖正确性层面，这才是阻止重复写入的关键。

实用规则：对于读方法，可以自由重试。对于状态变更方法，在通过读取链上状态证明并非如此之前，将每个模糊结果都视为“可能已应用”。这一条纪律就能防止大多数重复写入事故。

• 超时或连接重置 = 结果未知，而非失败。
• 节点可能已应用调用，只是丢失了响应。
• 对写入进行简单重试可能导致效果被重复应用。
• 解决方法是读取链上状态，而不是重新发送。

JSON-RPC 2.0 对 id 字段的实际保证

JSON-RPC 2.0 规范将 id 定义为请求标识符，用于将响应与其请求关联。它是由客户端选择的值，规范并未说明服务器会用它来去重工作。在重试时复用同一个 id 并不能阻止第二次应用；它只是帮助你匹配响应与所发起的调用。

规范还定义了通知：没有 id 的请求，服务器不返回响应。通知是即发即忘的，对重试安全性来说更糟，因为你甚至无法关联结果。对于状态变更调用，始终发送 id，并始终期望能得到可推理的响应。

由于 JSON-RPC 没有幂等键概念，HTTP 的 Idempotency-Key 头约定不属于基础协议。一些 HTTP 前端的 RPC 网关可能支持它，但不能假设一定支持。权威参考是 JSON-RPC 2.0 规范；HTTP 幂等性约定在 IETF 关于 Idempotency-Key 头的草案中有描述。

• id 用于关联响应；它不会在服务端去重。
• 通知（无 id）不返回响应，对写入不安全。
• JSON-RPC 2.0 没有原生幂等键。
• HTTP Idempotency-Key 是独立约定，RPC 节点不保证支持。

安全分类：读方法与状态变更方法

并非所有 JSON-RPC 方法都有相同的重试风险。读方法天然幂等：在相同区块上下文中，调用 eth_call、eth_getBalance 或 getAccountInfo 两次会返回相同结果，且不改变任何状态。状态变更方法则不是幂等的：eth_sendRawTransaction、sendTransaction 以及交易所订单端点每次成功都会应用一次效果。

在编写任何重试逻辑之前，请使用这个决策表。推理列才是关键：它告诉你为什么某个方法安全或不安全，这样你就能自己分类新方法，而不是死记列表。

如有疑问，将方法归类为状态变更。不必要的检查成本只是几次额外读取；错误重试的成本则是重复的财务影响。

• eth_call、eth_getBalance、eth_getTransactionReceipt、getAccountInfo：幂等，可安全重试。
• eth_sendRawTransaction、sendTransaction、交易所订单提交：非幂等，绝不盲目重试。
• eth_getTransactionCount：幂等读取，但其值决定 nonce 正确性。
• 批量请求：安全性混合；部分失败迫使你按子请求逐一推理。

你已拥有的链原生幂等原语

你不需要自定义幂等键来让写入可安全重试；链本身提供了原语。在 EVM 链上，账户 nonce 使相同 nonce 的替换交易成为幂等的取消或替换，而不是第二次应用。交易哈希是确定性身份，因此客户端可以按哈希轮询 eth_getTransactionReceipt，而不是盲目重发。并发下的 EVM nonce 管理指南深入介绍了 nonce 竞争。

在 Solana 上，通过交易签名去重，并使用持久 nonce 或新的 blockhash 检查来控制重新签名的交易能否上链。Solana RPC 超时与重试指南介绍了导致这一必要性的超时行为。

交易所和 Hyperliquid 风格的 API 暴露了 client-order-id（cloid）模式：你提供一个唯一的客户端 ID，交易场所会拒绝或忽略重复项。这是交易 API 中最接近真正幂等键的东西，因此当交易场所支持时，你应始终设置它。

• EVM：相同 nonce 替换是取消或替换，不是第二次应用。
• EVM：交易哈希是确定性的；按哈希轮询收据。
• Solana：按签名去重；持久 nonce 或 blockhash 控制上链。
• 交易所：client-order-id / cloid 是交易场所级别的去重键。

构建至多一次客户端：持久化、发送、记录、检查

至多一次客户端遵循四个步骤。首先，根据业务意图生成确定性操作 ID（例如账户、接收方、金额和业务参考的哈希），而不是每次尝试都生成随机 UUID。其次，在发送任何内容之前，将该操作 ID 与已签名负载一起持久化。第三，成功后将生成的链上交易哈希与操作 ID 关联记录。第四，重试时，先检查已持久化的哈希是否已经上链，然后再重新广播。

持久化步骤使该模式能在进程崩溃后存活。如果你只在内存中保存状态，重启会丢失哈希，你又回到猜测状态。一个小型持久存储（数据库行、文件，甚至键值存储）就足够了。

检查步骤是一次读取：在 EVM 上按哈希调用 eth_getTransactionReceipt，在 Solana 上调用 getSignatureStatuses，或在交易所查询订单状态。如果收据存在，写入已经应用；不要重发。如果不存在且 nonce 仍未使用，你可以安全地重新广播相同的已签名负载。

• 确定性操作 ID 源自业务意图，而非每次尝试随机生成。
• 发送前持久化 ID + 已签名负载。
• 成功时记录链上交易哈希。
• 重试时先检查哈希；仅在未上链时重新广播。

可运行的 Node.js 示例：先检查后重发避免重复写入

下面的示例发送一次，记录哈希，模拟超时，然后演示先检查后重发。它使用占位 RPC URL；将其指向测试网端点，例如以太坊网络页面或来自 RPC 端点指南（RPC Assistant）的任何端点。关键行为是重试路径在重发前读取收据。

这是刻意保持最小化的示例。在生产环境中，你会将内存存储替换为持久存储并添加 nonce 管理，但控制流是相同的。

// check-then-resend.js — Node 18+, no external deps beyond ethers
import { JsonRpcProvider, Wallet, parseEther } from 'ethers';

const RPC_URL = process.env.RPC_URL; // e.g. a testnet endpoint
const provider = new JsonRpcProvider(RPC_URL);
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

// In-memory stand-in for a durable store.
const store = new Map();

async function sendOnce(opId, to, amountEth) {
  // 1. If we already recorded a hash, check whether it landed.
  const prior = store.get(opId);
  if (prior?.hash) {
    const receipt = await provider.getTransactionReceipt(prior.hash);
    if (receipt) {
      console.log('Already applied, not re-sending:', prior.hash);
      return receipt;
    }
    console.log('Prior hash not mined yet, re-broadcasting same payload');
    return provider.broadcastTransaction(prior.raw);
  }

  // 2. Build and sign once, persist BEFORE sending.
  const nonce = await provider.getTransactionCount(wallet.address, 'pending');
  const tx = await wallet.populateTransaction({ to, value: parseEther(amountEth), nonce });
  const raw = await wallet.signTransaction(tx);
  store.set(opId, { raw, hash: null });

  // 3. Send. A timeout here does NOT mean failure.
  try {
    const sent = await provider.broadcastTransaction(raw);
    store.set(opId, { raw, hash: sent.hash });
    console.log('Sent:', sent.hash);
    return sent;
  } catch (err) {
    console.log('Ambiguous outcome (timeout/reset):', err.message);
    // 4. Do NOT blindly re-send. Check chain state first.
    const hash = (await import('ethers')).keccak256(raw);
    const receipt = await provider.getTransactionReceipt(hash);
    if (receipt) {
      store.set(opId, { raw, hash });
      console.log('Found on chain despite error:', hash);
      return receipt;
    }
    console.log('Not found; safe to retry with same payload');
    return provider.broadcastTransaction(raw);
  }
}

await sendOnce('op-2026-09-13-001', '0x000000000000000000000000000000000000dEaD', '0.001');

可复现的测试网测试：简单重试 vs 受保护重试

你可以在测试网上亲自验证这一风险。对同一个有资金的测试账户运行两个变体，并比较结果余额和交易计数。这是你执行的测量，而不是我们断言的基准；请在下表中记录你自己的数字。

变体 A（简单）：发送一笔转账，通过短延迟后中止请求来强制客户端超时，然后立即用新的 nonce 重新发送同一逻辑转账。变体 B（受保护）：发送同一笔转账，强制同样的超时，然后在决定是否重发之前，按原始哈希检查 eth_getTransactionReceipt。

比较接收方余额变化和发送方交易计数。变体 A 可能显示两次应用；变体 B 应显示一次。每个变体运行多次并记录方差，因为时序决定第一笔交易是否在中止前上链。

• 结果表列：变体 | 接收方变化 | 发送方交易计数 | 是否观察到重复（Y/N） | 备注。
• 每个变体至少运行 5 次；时序会改变结果。
• 每次运行使用新的测试账户，避免 nonce 残留。
• 在结果旁记录 RPC 端点和客户端版本。

带幂等键的 HTTP 包装器以及没有时该怎么办

一些 HTTP 前端 API 支持 Idempotency-Key 头，服务器存储该键并在重复时返回原始响应。如果你的端点文档说明支持，就使用它：为每个业务操作生成确定性键，在每次尝试时发送，让服务器去重。这是有文档记录的平台行为，不是 JSON-RPC 的保证。

当端点不支持时，你必须使用上述链原生原语在客户端实现去重。没有捷径：如果服务器和链都不提供去重键，唯一安全的解决方法是读取状态并做出决定。API 服务和 RPC 定价页面描述了服务范围；请查看具体端点文档以确认是否支持幂等头。

一个有用的模式是薄包装器，它始终将你的操作 ID 作为元数据附加并记录，即使服务器忽略它。这为你提供了事后对账重复项的审计线索。

• 仅在端点文档说明支持时使用 Idempotency-Key。
• 没有服务器支持时，通过 nonce/哈希/签名在客户端去重。
• 即使服务器忽略，也记录你的操作 ID。
• 通过读取链上状态来对账模糊结果。

与请求对冲和批量请求的交互

请求对冲将同一调用发送到多个端点并取第一个响应。它对读取安全，对写入危险：对冲写入可能导致同一笔交易通过两条路径广播，虽然 nonce 通常能防止 EVM 上的重复应用，但仍可能产生令人困惑的错误和浪费的手续费。RPC 请求对冲与尾部延迟指南明确警告仅对冲读方法；将其视为硬性规则。

批量请求使问题复杂化。一个批次是包含多个 JSON-RPC 调用的单个 HTTP 请求，部分失败意味着某些子请求可能已应用，而其他没有。你不能假设批次是原子的。重试时，使用每个子请求自己的 id 和自己的链原生身份逐一推理。

安全模式是完全将写入排除在批次之外，或者仅批量读取，并一次一个地发出写入，并显式处理先检查后重发。

• 绝不对状态变更调用进行对冲。
• 批次不是原子的；可能部分应用。
• 重试时按子请求推理，而不是按批次。
• 优先使用带显式去重的单次写入，而非批量写入。

局限性：被拒绝 vs 已应用但响应丢失

存在一个客户端无法独自跨越的根本边界。当写入返回错误时，你无法从客户端判断节点是拒绝了它（例如资金不足、nonce 错误或回滚），还是应用了它但丢失了响应。这两种情况需要相反的操作：前者重发，后者不重发。

唯一可靠的解决方法是读取链上状态：检查交易哈希、账户 nonce 和收据。如果 nonce 已推进且收据存在，则已应用。如果 nonce 未变且经过合理等待后没有收据，则很可能没有应用。注意这里的“很可能”确实在起作用；存在一个窗口，交易在内存池中但尚未挖出，在此期间结果确实未知。

针对这个窗口进行明确设计。持久化已签名负载，以便你可以原样重新广播，并轮询而不是重新签名。在未知窗口期间用新 nonce 重新签名，正是将模糊结果变成重复项的原因。

• 客户端无法单独区分被拒绝和已应用但响应丢失。
• 通过读取 nonce、哈希和收据来解决。
• 内存池窗口确实未知；轮询，不要重新签名。
• 持久化已签名负载以实现安全重新广播。

排查重复写入及后续步骤

如果你已经看到重复项，首先检查你的重试路径是否用新 nonce 重新签名。这是最常见的原因。其次，确认你的客户端是否在发送返回之前持久化交易哈希；如果它只在成功时记录，超时会丢失哈希并迫使你猜测。最后，检查是否有任何写入被对冲或批量处理，这两者都会扩大故障面。

后续步骤：将至多一次模式接入你的客户端库，添加持久操作存储，并添加一个对账任务，扫描没有记录哈希的操作 ID，并通过读取链上状态来解决它们。然后对照 OnFinality Learn 中心审查你的读取路径，获取相关超时和 nonce 指导，并对照 RPC 端点指南（RPC Assistant）确认你的端点行为。

目标不是消除重试；重试是必要的。目标是让每次重试都安全，确保它要么重新广播相同的负载，要么先检查链上状态。这就是将脆弱的集成转变为至多一次集成的关键。

• 检查重试时是否用新 nonce 重新签名。
• 验证哈希在发送返回之前已持久化。
• 从对冲和批量路径中移除写入。
• 添加对账任务，通过读取链上状态来解决未知结果。