mcpField
C
crontap-retries-and-idempotency

crontap-retries-and-idempotency

github.com/crontap云与 DevOps1937 次安装6 周前更新
代码仓库

关于 crontap-retries-and-idempotency

此技能介绍如何先确保接收端具备幂等性，再安全配置 Crontap 重试；内容涵盖故障检查、策略更新和结果验证。

主要功能

  1. 01根据计划历史分类故障
  2. 02设计持久化幂等键
  3. 03更新计划的重试策略
  4. 04测试重试并验证结果

适用场景

  1. 01重试瞬时故障而不产生重复副作用
  2. 02诊断定时任务的重复故障
  3. 03在非生产目标中检查重试行为

MCP 相关

通过 Crontap MCP 查看计划历史并更新计划的重试策略。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/crontap/skills --skill crontap-retries-and-idempotency

安装后在 Claude Code 中输入/crontap-retries-and-idempotency确认已加载。

详细介绍

重试与幂等性

只有当端点能够安全地多次接收同一逻辑任务时，重试才能提高送达率。在扩大重试策略前，先确保接收方具备幂等性。

前提条件

使用所需工具前，先确认这些工具是否可用。如果缺少任何工具，请停止操作，并且只向用户提供以下两种选择：

  1. 连接 Crontap MCP：https://mcp.crontap.com/mcp。所有 Crontap 套餐均支持 MCP 访问。
  2. 为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra。

在用户选择前，不要擅自选择路径或继续操作。

  • 确定计划任务以及它可能产生的每种副作用。
  • 判断哪些失败对于此端点而言是暂时性的。
  • 选择稳定的去重键和保留时长。

工作流

  1. 检查近期历史记录，对失败进行分类。
  2. 为端点添加幂等性，并测试重复请求。
  3. 使用 MCP 仅更新计划任务的重试策略。
  4. 验证一次受控的暂时性失败及其最终成功。
  5. 重新检查历史记录，确认尝试次数、延迟和最终结果。

MCP 示例

更改策略前先检查失败：

{
  "tool": "get_schedule_history",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "limit": 50
  }
}

重试常见的暂时性故障类别：

{
  "tool": "update_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>",
    "retryPolicy": {
      "enabled": true,
      "maxRetries": 3,
      "baseDelayMs": 60000,
      "retryOn": ["5xx", "429", "network", "timeout"]
    }
  }
}

允许的基础延迟为 30000、60000、300000 和 900000 毫秒。最大重试次数为 5。仅当此特定端点使用已知的暂时性 4xx 响应时，才包含 4xx。

端点幂等性模式

使用唯一数据库约束或原子插入，并以逻辑任务标识作为键：

key = job-name + ":" + scheduled-period
insert key before side effects
if key already exists, return the recorded result
perform side effects once
store completion outcome

对于资金转移、电子邮件发送、资源配置或外部写入，应将相同的键传递给支持幂等性的下游系统。不要依赖内存中的集合，因为重启和多个实例都会失去这种保护。

REST 回退方案

MCP 部分更新仍是首选方式，且不只限于 Ultra。公共 REST PUT 会完整替换资源，因此绝不要只发送 retryPolicy。

使用 Ultra 凭据时，先 GET 当前完整计划任务。构建完整的替换内容，至少包含 url、verb、interval 和 timezone。保留所有其他配置字段，包括 headers、body、集成项和计划任务选项。保留凭据和密钥，不要记录它们。仅更改 retryPolicy，然后将完整替换内容 PUT 到 https://api.crontap.com/v1/schedule/<schedule-id>。

验证

  • 连续发送两次相同的逻辑请求，并确认只产生一项持久化副作用。
  • 在非生产目标环境中触发一次安全的暂时性失败。
  • 确认历史记录显示符合策略预期的重试和最终结果。
  • 确认告警在最终失败后触发，而不是在成功恢复时触发。

安全性与套餐限制

  • 自定义重试策略设置需要 Pro、Ultra 或旧版 Pro。Starter 仍可使用标准自动重试行为。
  • 重试身份验证和验证失败通常只会增加负载，不会提高成功率。
  • 幂等性保留时长绝不能短于最大重试窗口。
  • 如果配置返回 RETRY_POLICY_NOT_CONFIGURABLE，请提供结构化的四选项阶梯方案以及所需的最小可行选项。

故障排查

  • 只有一条历史记录却出现重复工作，通常是应用逻辑或其他调用方导致的，而非 Crontap 重试。
  • 多次尝试间出现重复工作，说明接收方的去重事务不完整或作用范围过窄。
  • 反复出现 429 响应时，需要协调速率限制，而不是增加尝试次数。
  • 部分 REST 替换可能会清除计划任务设置。如果并发更改后要重试，请先重新获取数据。

参考资料

评论

支持 Markdown