AI Agent / 知识点

MCP 开发速查手册

手册条目

为长任务设置超时、重试和幂等保护,避免产生重复副作用。

控制超时与重复执行

用于调用耗时不确定或可能产生副作用的 MCP 工具:用单次超时限制等待时间,用有限重试处理瞬时故障,再用幂等键保证同一业务请求最多生效一次。

基本策略

一次可靠调用应同时设置单次超时、总截止时间、最大重试次数和幂等键。超时只表示调用方停止等待,不代表下游一定停止执行;因此只要操作会写数据库、扣款、发消息或创建资源,就必须先建立幂等保护,再允许重试。

超时重试与幂等控制流程

可运行示例

下面用 Python 标准库模拟“首次超时、第二次成功、重复请求命中幂等结果”。内存字典只用于演示,生产环境应替换为带唯一约束的数据库或 Redis 原子写入。

python
import asyncio

attempts: dict[str, int] = {}
result_cache: dict[str, dict[str, object]] = {}

async def remote_operation(key: str) -> dict[str, object]:
    attempts[key] = attempts.get(key, 0) + 1
    # 首次调用故意超过 0.1 秒,第二次快速成功。
    await asyncio.sleep(0.2 if attempts[key] == 1 else 0.02)
    return {"status": "paid", "attempt": attempts[key]}

async def execute_once(idempotency_key: str) -> dict[str, object]:
    if idempotency_key in result_cache:
        print(f"cache hit: {idempotency_key}")
        return result_cache[idempotency_key]

    for retry_no in range(1, 4):
        try:
            result = await asyncio.wait_for(
                remote_operation(idempotency_key),
                timeout=0.1,
            )
            # 真实系统应在同一事务中提交副作用与幂等结果。
            result_cache[idempotency_key] = result
            print(f"success on attempt {retry_no}")
            return result
        except TimeoutError:
            print(f"timeout on attempt {retry_no}")
            if retry_no == 3:
                raise
            await asyncio.sleep(0.05 * (2 ** (retry_no - 1)))

    raise RuntimeError("unreachable")

async def main() -> None:
    first = await execute_once("pay-order-1001")
    second = await execute_once("pay-order-1001")
    print(f"same_result={first == second}")
    print(f"stored_attempt={second['attempt']}")

asyncio.run(main())

预期输出

text
timeout on attempt 1
success on attempt 2
cache hit: pay-order-1001
same_result=True
stored_attempt=2

读取方法:第一行表示单次超时生效;第二行表示有限重试成功;cache hit 与 same_result=True 说明重复调用没有再次执行副作用。

常用参数

  • timeout:单次尝试的最长等待时间,应小于上层请求总截止时间。
  • max_attempts:包含首次调用在内的总尝试次数,常见为 2~4 次。
  • backoff:退避间隔,建议指数增长并加入随机抖动,避免大量请求同时重试。
  • idempotency_key:由业务唯一键生成,作用域必须包含租户、工具和操作类型,避免不同业务误命中。

风险与边界

触发条件:对已经到达下游的写操作直接重试。可能后果:重复扣款、重复建单、重复发信或重复写库。安全替代方案:下游接受幂等键,并用唯一约束或原子状态机保存“处理中、成功、失败”及最终结果。

触发条件:对参数错误、鉴权失败或永久性业务拒绝持续重试。可能后果:放大流量并延长失败时间。安全替代方案:只重试明确的瞬时错误,例如连接中断、限流或部分服务端错误,并同时设置最大次数和总截止时间。

排障清单

  • 日志同时记录 request_id、幂等键、尝试序号、单次耗时和最终状态。
  • 确认超时发生后,下游任务是否仍在运行;必要时提供可查询任务状态或显式取消接口。
  • 检查幂等记录是否与业务副作用同事务提交,避免“业务已成功但结果未保存”。
  • 重试量突然升高时先查下游延迟和限流,不要仅扩大超时或重试次数。

目录与阅读设置

记录一个想法

MCP 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通