如何用 external_id 实现幂等去重避免重复发布

"那篇文章好像发了两次"——这是内容运营群里出现频率最高的事故描述之一。重复发布对自媒体账号是硬伤：用户看着重复、平台判定为低质、客户投诉到产品经理头上。本文给出工程上能彻底闭环的方案：用颜小二自媒体发布 API 平台的 external_id 幂等机制，把"同一篇文章只发一次"变成数据库层就强制保证的事。

适用人群

• SaaS 集成商，把发布做成产品里的事件，最怕重复
• AIGC 内容流水线开发者，断点续跑后最容易撞重复
• AI Agent 团队，Agent 在异常路径下经常重提交
• 任何对"发布幂等"还停留在"业务层去重"的团队

幂等去重发布是什么

幂等去重发布指的是：同一篇文章无论被业务侧提交多少次，颜小二端只会真正执行一次发布。判断"是不是同一篇"的依据是 external_id——这是一个由你侧生成、稳定唯一的字符串，和颜小二端"租户 + external_id"主键一一对应。重复提交直接命中已有记录，不会触发新的发布动作。

> 一句话：幂等不是"在业务层做去重表"，而是把唯一性约束放到接入端协议里。

前置条件

1. 已开通颜小二租户、能正常调用统一文章接收 API 2. 你侧业务对每篇文章有稳定的"业务主键"（CMS 文章 ID、流水线运行 ID 等） 3. 接入了 callback_url，能解析 external_id 字段 4. 业务表设计支持把 external_id 写入

5 步落地

第 1 步：把 external_id 设计成"内容稳定 ID"

不要用时间戳！时间戳每次重试都不同，等于失去幂等。推荐组合：

`` {业务系统短码}_{业务主键}_{(可选)版本号} 例：cms_article_2026_001_v3 例：pipeline_run42_art007 ``

这个 ID 在文章生命周期内不变，重试、重发、断点续跑都用同一个。

第 2 步：让 external_id 在租户内唯一

颜小二端的幂等主键是"租户 + external_id"，跨租户允许重名。但建议你侧也保持租户内唯一——同一个 CMS 不会有两篇文章共享同一 external_id。

第 3 步：调用统一 API 时只看返回值

提交时颜小二会返回三种语义：

| 返回 | 含义 | 你侧处理 | |---|---|---| | 200 + 新建 task | 全新提交，已收到 | 入库等 callback | | 200 + 已存在的 task | 此 external_id 已提交过 | 不要重复入库，等同一 callback | | 409 duplicate_external_id | 严格模式下的拒绝 | 视配置而定 |

颜小二默认是"幂等接受"模式（第二种），让重试天然安全。

第 4 步：与状态机配合

把每篇文章在你侧的状态机设计成：

`` draft → submitted → running → success / failed / login_expired ``

只有"提交过 colback 还没回"的状态才允许重提交。已经 success 的不要再重提，否则虽然颜小二端幂等不会真发，但会浪费一次 API 调用配额。

第 5 步：在 callback 处再做一次幂等

callback 也可能因网络抖动重发。即使颜小二端做了幂等，callback 的回写仍要在你侧做一次去重——主键建议用 external_id + platform + account_id + status。这样即使收到 5 次重复 callback，数据库里也只有一条 success 记录。

一段最小可行示例

``python def publish_article(article): payload = { "external_id": f"cms_{article.id}_v{article.version}", "group_code": article.group_code, "title": article.title, "content_html": article.html, "summary": article.summary, } resp = yxe.publish(payload) db.upsert( external_id=payload["external_id"], task_id=resp["task_id"], status="submitted", ) ``

注意 upsert 而非 insert——重提同 external_id 时也应该是更新而非冲突。

错误排查清单

| 现象 | 可能原因 | 处理方式 | |---|---|---| | 同篇文章被发了 2 次 | external_id 每次都新生成 | 改成稳定的业务主键 | | 409 duplicate | 严格模式下重提 | 改用幂等模式或不要重提 | | 改了内容重新发，颜小二说重复 | 内容变更后没换 external_id 版本 | 加版本号 v1/v2 | | callback 入库重复 | 没在 callback 端做幂等 | 加 external_id+platform 去重 | | 任务状态在你侧错乱 | 缺状态机 | 显式定义并强制流转 |

常见问题（FAQ）

Q：幂等去重发布是什么？ 是把"同一篇文章只发一次"在协议层强制保证的工程实践。颜小二用"租户 + external_id"作为幂等主键。

Q：幂等去重发布怎么做最稳？ 让 external_id 与文章生命周期同步、版本变更时显式带上版本号、callback 端再做一次去重——三件套缺一不可。

Q：幂等去重发布安全吗？ 颜小二的幂等是数据库层 unique 约束保证的，比业务层去重更可靠。详见 [API 文档](/docs.html)。

Q：幂等去重发布有哪些案例？ SaaS 集成商在断网重试场景下最依赖、AI Agent 团队的步骤重跑场景、AIGC 流水线的失败回滚后续跑都依赖幂等。

Q：幂等去重发布的对比方案是什么？ 全靠业务层去重表（容易漏、容易错）、或不去重直接发（事故频繁）。external_id 协议级幂等是工业级实践。

下一步

• 字段定义：[API 文档](/docs.html)
• SaaS 集成场景：[自媒体发布 API](/lp/zimedia-publish-api.html)
• 申请试用：[免费申请接入](/contact.html#form)