Michael Johnson如果 Durable Object 调用因网络故障而失败，开发者过去通常需要自行判断是否再次发送。从 2026 年 11 月 5 日起，Cloudflare 运行时会处理其中一部分重试：它会自动重试特定失败的 fetch() 和通过 stub 发起的 RPC。对于应用代码来说，现在更准确的问题是：某个方法是否可以安全地执行第二次？
答案取决于连接在哪个环节中断。运行时会自动重试部分调用，同时默认保留防止重复执行的保护。在无法确定请求是否送达时，它会使用相同的请求 ID；如果对象已经收到第一次尝试，就会拒绝重试。显式标记为 retryable() 的方法则行为不同：即使第一次尝试已经到达对象，也可能再次运行。因此，只有当操作及其副作用都能安全重复时，才适合添加该标记。
运行时具体会重试什么
根据 Cloudflare 11 月 5 日发布的公告，重试适用于 Worker 或其他 Durable Object 对 Durable Object 发起的 fetch() 和 RPC 调用。对于通过 stub 发起的调用，默认会先尝试一次，之后最多重试四次；调用开始 10 秒后，不会再启动新的尝试。
重试条件是错误带有 .retryable 标记。例如，对象正在重启或迁移，导致请求未能到达。连接中断、无法确定对象是否已收到请求时，运行时也可能再次尝试。如果对象已经收到请求，则会拒绝使用相同 ID 的重试。运行时不会重试由 Durable Object 代码抛出的错误、带有 .overloaded 标记的错误，以及类似 500 的 HTTP 响应：这些是处理程序的响应，而不是传输错误。
为什么请求重传不等于操作重做
重新传输请求本身并不意味着方法会执行第二次。当结果无法确定时，运行时会使用相同的 ID 发送请求；如果对象已经接受了第一次尝试，就会拒绝重试。默认情况下，这可以防止一次网络故障导致方法重复执行，例如重复扣款或重复创建记录。
通过 cloudflare:durable-objects 中的 retryable() 标记方法后，即使第一次尝试可能已经开始，对象也可以重新执行该方法。Cloudflare 举了两个例子：将商品数量设为指定值是幂等的；将数量增加一则不是。重复前者会设定同一个值，重复后者则会再增加一个单位。
检查时不仅要看存储的最终状态，也要检查方法产生的所有效果。如果重试会再次创建付款、发送消息或触发外部操作，那么 Durable Object 内部状态相同，也不代表重试安全。只有在重试不会改变结果含义、也不会重复副作用时，才适合添加该标记。
显式幂等性适用于哪些场景
设定一个值、写入状态快照，或将字段更新为已知值，通常在重复执行时会得到相同结果。对于这类方法，retryable() 可以让调用在连接于处理开始后中断时，仍有机会成功完成。
“增加”“再创建一个”“扣款”和“发送”这类操作通常需要其他保护措施。在允许重新执行之前，先确认业务操作能识别重复请求，或其设计本身不会因重试产生第二次效果。函数名称无法保证这一点：请检查方法内的所有状态变更和外部操作。
retryable() 的作用范围很窄：当无法确定第一次调用是否送达时，它允许方法再次执行。它不会改变运行时会响应的错误类型，也不会增加尝试次数。该标记作用于函数；如果方法被重写或封装，新版本不会自动继承标记，除非也显式添加。
现有项目需要检查什么
最可能需要审查的是 Durable Objects 调用周围自定义的重试循环。现在每次这样的尝试都可能包含运行时重试，因此总调用次数可能超过应用本身设定的次数。Cloudflare 建议减少自定义重试次数，或者在由自己的代码管理重试时，为 stub 设置 maxRetries: 0。
可以在调用 get() 或 getByName() 时，为特定 stub 设置限制。参数 maxRetries 可设为 0 到 10 次，即首次尝试之外的重试次数；timeoutMs 指定不再启动新尝试的时间间隔，范围为 500 到 60,000 毫秒。这些设置仅应用于通过该 stub 发起的调用。使用 retryable() 和 retry 对象需要 Wrangler 4.158.0 或更高版本。
审查时，可以针对每次调用提出三个问题：它是否可能多次改变状态？它是否会重复外部副作用？应用是否有自己的重试策略？之后再决定该 stub 是使用默认值还是自定义限制。对于幂等方法，可以单独评估是否显式添加标记；对于其他方法，则保留防护，并检查当第一次尝试结果未知时如何处理错误。
影响：责任转移到方法边界
自动重试减少了应用代码中的部分网络处理逻辑，但是否允许再次执行仍取决于具体操作。运行时可以安全地重传请求，并在无法判断调用是否已经执行时停止。开发者则可以明确确认某个方法不会重复状态变更或副作用，从而允许它重新执行。
因此，应将此次更新视为传输层与处理程序之间契约的变化。先检查自定义重试循环和副作用是否可重复，再为需要的 stub 配置限制。这样既能利用内置机制应对短暂故障，也能控制那些重复执行代价高昂的操作。
