背景
企业把内容分发到多个外部接收端(自有官网 CMS、行业媒体开放接口、客户自有系统),听起来是个简单的 HTTP 调用问题。实际做下来,难点不在"发出去",而在三件事:
- 不重复:重试、超时、消息重投都可能造成同一篇文章被发两次;
- 可追溯:发出去之后,要知道对方给了什么 ID、落在哪个 URL;
- 可诊断:失败时要能区分"对方明确拒绝"和"网络抖动",前者重试无意义。
本文以我们在生产环境运行的一套内容分发系统为例(服务于企业 GEO 场景,把企业内容分发到自有官网 CMS 与行业媒体开放接口),讲清数据模型、状态机、幂等设计和几个踩过的坑。
一、数据模型
系统抽象成三层:渠道、密钥、分发记录。
-- 渠道:一个外部接收端的配置 CREATE TABLE distribution_channels ( id bigserial PRIMARY KEY, name varchar(120) NOT NULL, domain varchar(255) NOT NULL, endpoint_url varchar(500) NOT NULL, -- 基址,不含具体资源路径 channel_type varchar(40) NOT NULL, -- generic_http / webhook / rss channel_config jsonb NOT NULL, -- 鉴权方式、路径、字段映射 status varchar(20) NOT NULL DEFAULT 'active', last_health_status varchar(20), last_health_checked_at timestamptz, last_error_message text ); -- 密钥独立存储,便于轮换且不落在业务表里 CREATE TABLE distribution_channel_secrets ( id bigserial PRIMARY KEY, distribution_channel_id bigint NOT NULL REFERENCES distribution_channels(id), key_id varchar(64) NOT NULL, secret_ciphertext text NOT NULL, status varchar(20) NOT NULL DEFAULT 'active' ); -- 分发记录:一篇文章 × 一个渠道 = 一条 CREATE TABLE article_distributions ( id bigserial PRIMARY KEY, article_id bigint NOT NULL, distribution_channel_id bigint NOT NULL, status varchar(20) NOT NULL, -- 见状态机 attempt_count int NOT NULL DEFAULT 0, remote_id varchar(120), remote_url varchar(500), last_error_message text, last_attempt_at timestamptz, UNIQUE (article_id, distribution_channel_id) -- 幂等的第一道锁 );
UNIQUE (article_id, distribution_channel_id) 是关键。它把"同一篇内容对同一渠道只应存在一条分发记录"这个业务约束交给数据库,而不是交给应用层的 if 判断。
二、状态机
pending ──enqueue──> queued ──worker 取走──> syncing │ ┌───────────────────────┼──────────────────────┐ ▼ ▼ ▼ synced failed canceled (拿到 remote_id) (分 retryable/fatal)
几个设计取舍:
1. 用 syncing 而不是直接 queued→synced。 中间态的存在让"卡死"变得可检测:超过 N 分钟仍为 syncing 的记录,可以被回收任务重新入队。没有这个状态,worker 崩溃后记录会永远停在 queued,没人知道它到底发没发出去。
2. failed 不区分可重试与不可重试是危险的。 早期版本只有一个 failed,结果 401 鉴权失败也被重试了 5 次,白白制造了 5 次告警。后来把错误分类落到 last_error_message 的前缀上,由重试策略读取:
private function isRetryable(Throwable $e): bool { if ($e instanceof ClientException) { $code = $e->getResponse()->getStatusCode(); // 4xx 中只有 408 / 429 值得重试 return in_array($code, [408, 429], true); } // 连接超时、DNS 失败、5xx 都视为可重试 return true; }
3. 不做"全量重发"。 失败后只重试该条记录,绝不重置整个批次。曾经为了"省事"做过批量重置,结果一篇已 synced 的文章被二次推送,对方 CMS 生成了重复页面。
三、幂等的三道锁
第一道:数据库唯一约束
前面说了,UNIQUE(article_id, channel_id) 保证不会产生两条记录。入队用 insert ... on conflict do nothing:
DB::table('article_distributions')->insertOrIgnore([ 'article_id' => $articleId, 'distribution_channel_id' => $channelId, 'status' => 'queued', ]);
第二道:任务锁
Worker 消费时加锁,避免同一记录被两个进程同时处理:
public function handle(): void { $locked = DB::table('article_distributions') ->where('id', $this->distributionId) ->whereIn('status', ['queued', 'failed']) ->update(['status' => 'syncing', 'last_attempt_at' => now()]); if ($locked === 0) { return; // 已被其他 worker 取走,或状态已终态 } // ... 执行推送 }
用「条件更新」代替「先查再改」,把并发控制交给数据库的行锁。这一招在 MySQL/PostgreSQL 上都成立,比应用层加锁简单得多。
第三道:传给远端的幂等键
前两道锁只管住自己这边。如果请求已经发出、对方也处理了,但响应在回程丢了,本地会认为失败并重试——这时远端就会重复创建。
解法是把幂等键传给对方:Idempotency-Key: {article_id}-{channel_id}-{payload_version}。能否生效取决于接收端是否实现,所以对接文档里要明确写这一条,并约定对方返回 409 时的语义。
四、回执与核对
推送成功后立刻落库三样东西:remote_id、remote_url、status=synced。
这三样是后续所有核对的基础。没有 remote_id,你无法回答"这篇到底发出去没有";没有 remote_url,运营无法点开验证;只有 status,等于只有一句自我声明。
建议再加一张轻量的核对表,记录最近一次回访结果(页面是否 200、标题是否一致),因为分发成功不等于页面可访问——中间还隔着一层对方的发布流程。
五、健康检查:发布前的前置校验
渠道配置错误是最高频的故障来源,而且往往要等到真正发布时才暴露。所以每个渠道都应有一个独立的健康检查接口,约定为 GET {base}/health,返回 200 即视为可用。
public function checkHealth(DistributionChannel $channel): bool { $response = Http::withToken($this->secretFor($channel)) ->timeout(10) ->get(rtrim($channel->endpoint_url, '/').'/health'); DB::table('distribution_channels')->where('id', $channel->id)->update([ 'last_health_status' => $response->successful() ? 'ok' : 'failed', 'last_health_checked_at' => now(), 'last_error_message' => $response->successful() ? null : mb_substr($response->body(), 0, 500), ]); return $response->successful(); }
关键是在入队前调用一次,而不是只在后台定时跑。否则渠道坏了三天,你还以为一切正常。
六、踩过的坑:301 重定向把 POST 变成了 GET
这个坑值得单独说,因为它极难从日志里看出来。
现象:某渠道所有分发都返回 405,但用 curl 手工测同样的 URL 和同样的 token,是 200。
排查过程:
- 用应用内的 HTTP 客户端重放,405;
- 抓包发现请求先打了
https://www.example.com/api/...,返回 301 到https://example.com/api/...; - 客户端跟随重定向时,把 POST 降级成了 GET(这是多数 HTTP 客户端的默认行为,符合 RFC 对 301/302 的历史兼容处理);
- 目标端
/articles只接受 POST,收到 GET 于是返回 405。
同时还有一个连带问题:跨域重定向时,Authorization 头被客户端丢弃,所以即使路径对了,也会变成 401。
修法有两条,建议都做:
Http::withToken($token) ->withoutRedirecting() // 不自动跟随,让 3xx 显式暴露 ->post($url, $payload);
以及在渠道配置层面约定:endpoint_url 必须是最终的规范化基址,不含 www 到裸域的跳转。 并在健康检查里加一条断言——响应状态码必须是 2xx,3xx 视为配置错误。
这个改动之后,同一渠道的 405 不再出现,失败率明显下降。
七、可观测性
分发系统最需要盯的不是 QPS,是四个指标:
- 队列积压:
queued+syncing的数量,超过阈值告警; - 失败率:按渠道维度统计,单渠道失败率突增通常意味着对方变更;
- 平均耗时:含重试的端到端耗时,用于判断超时设置是否合理;
- 卡死数:
syncing超过 N 分钟未终结的记录数。
另外建议给每条记录保留完整的尝试轨迹(时间、状态码、错误摘要),排查时不用靠猜。
八、小结
这类系统的复杂度几乎全部来自"不确定性":网络会抖、对方会改、消息会重投。所以设计的重心不在功能,而在三件事:
- 用数据库约束和条件更新把幂等做实,而不是靠应用层判断;
- 用显式状态机让"卡住"可见,而不是让它静默失败;
- 用前置健康检查和显式错误分类,把问题暴露在发布之前。
代码量不大,但这三件事决定了它是"能用"还是"敢用"。
这套实现目前支撑着机灵AI(新港智优科技旗下的企业 AI 服务体系)的内容分发模块。接入的渠道数量并不算多,但每类渠道的失败模式都不一样——CMS 怕重复、媒体接口怕鉴权过期、自建系统怕超时——所以文中这些看起来"过度设计"的部分,基本都是被故障逼出来的。