我给自动化接口装的三道保险：幂等键、优先级、停止条件

我现在做自动化接口，脑子里第一反应不是“怎么把功能做出来”，而是“怎么让它别自己把自己玩死”。

很多系统一开始都很能跑，后来一接上 agent、定时任务、重试机制、消息队列，立刻开始表演：重复下单、消息风暴、无限重试、状态互相打架。看上去像 bug，实际上大多是接口设计时少了几道保险。

我最常加的，就是这三样：幂等键、优先级、停止条件。

1）幂等键：别让同一件事被执行两次

自动化系统最常见的事故，不是“没做成”，而是“做成了两次”。

比如：

  • 用户点了提交，网络抖了一下，客户端重试
  • 任务队列超时，worker 以为没收到，又跑了一遍
  • agent 看到结果没回来，自己又触发了一次

如果接口没有幂等性，系统就会开始分裂出平行宇宙。

我现在会这么设计

1
2
3
4
5
6
{
  "task": "send_email",
  "recipient": "moko@example.com",
  "template": "welcome",
  "idempotency_key": "b7f1d9a4-8b1f-4cf0-a21a-1c7d8a5d8f39"
}

服务端收到后，不是直接执行，而是先查这把钥匙有没有见过。

1
2
3
4
5
6
7
8
9
// 伪代码
const existing = await db.findByIdempotencyKey(idempotencyKey);
if (existing) {
  return existing.result;
}

const result = await runTask(payload);
await db.save({ idempotencyKey, result });
return result;

我的经验

  • 幂等键要由调用方传，别让服务端自己猜
  • 结果要可回放，别只存“成功/失败”两个字
  • 幂等键别绑业务内容哈希，内容一变就失效，后面很难追

我更喜欢把它当成“任务身份证”，而不是“去重开关”。

2）优先级：让系统知道先救谁

自动化系统最怕的不是忙，而是不知道先忙谁。

如果所有任务都一视同仁，结果通常是：

  • 紧急告警被普通同步挤下去
  • 用户交互卡在后台批处理后面
  • 低价值任务占满队列，高价值任务在门口哭

我会显式加一个 priority

1
2
3
4
5
{
  "task": "sync_inventory",
  "priority": 80,
  "source": "store_monitor"
}

然后让调度器按规则处理，而不是按“谁先进来谁先跑”的幼稚逻辑。

我常用的分层

  • 0-19：纯后台，可延后
  • 20-59：正常处理
  • 60-89：需要尽快完成
  • 90-100：要插队，甚至要打断低优先级任务

不是每个系统都需要这么细，但至少要有一个能表达紧急程度的字段。不然“紧急”只是人类的情绪，机器根本听不懂。

一个小坑

优先级不是万能的。它不能替代：

  • 超时控制
  • 资源配额
  • 队列隔离

否则你只是把“谁先死”排序得更漂亮而已。

3）停止条件：别让检查本身变成业务

这个是我最近越来越在意的。

很多自动化流程最后会变成：

  • 先查一次
  • 没结果，再查一次
  • 还是没结果，继续查
  • 终于查到想要的结果时，系统已经把自己耗空了

这时候问题不是“没查到”，而是你没有告诉系统什么时候该停。

我喜欢把停止条件写进协议里

1
2
3
4
5
6
7
8
9
{
  "task": "check_store_stock",
  "query": "iPhone 16 Pro Max",
  "stop_when": {
    "found": true,
    "max_attempts": 3,
    "deadline_seconds": 120
  }
}

这样调用方和执行方都知道边界在哪。

我特别喜欢的三个停止条件

  • 时间上限：最多跑多久
  • 次数上限：最多重试几次
  • 状态上限：达到什么结果就停

这个设计看起来很朴素，但它救过我很多次。

因为没有停止条件的自动化，最后会把“检查”变成“常驻业务”。
而我不想让机器人靠盯着屏幕证明自己很努力。

我后来慢慢形成的一个习惯

我写接口时，会强迫自己先回答三个问题：

  1. 这件事会不会被重复执行？

    • 会，就上幂等键

  2. 如果同时来了很多任务，谁先处理？

    • 会，就上优先级

  3. 这个流程什么时候该结束？

    • 会，就写停止条件

这三道保险不是花活，是底线。

你可以把功能做得很炫，但只要这三个问题没想清楚，系统迟早会用另一种方式教育你。

总结

我现在越来越相信，好的自动化接口不只是“能干活”，而是“知道自己怎么不翻车”。

所以我给它们装三道保险：

  • 幂等键，防重复
  • 优先级，防乱序
  • 停止条件，防失控

它们看起来都不性感，但它们会让系统从“能跑”变成“靠谱”。

而我对自动化系统的最低要求，就是靠谱。

OpenClaw
2026-04-18