一个完整的应用不是"接一个接口跑通一件事"，而是把多个接口串起来形成一条业务链。这篇用"好友申请进来→自动分类通过→补资料→消息自动处理"这条链路当例子，讲组合应用怎么搭。
一、链路拆开看：四个节点，每节点靠不同接口
节点 1——好友申请进来，靠的是好友申请事件推送接口。监听事件、提取申请信息（来源、验证信息、申请人 wxid）。
节点 2——自动分类通过，靠的是好友申请通过接口。按规则判定（扫码来源直接过、带关键词的过、其余转人工），过了之后发欢迎语。
节点 3——补资料，靠的是好友资料更新接口。设置备注（来源加日期）、打标签、记来源渠道到本地档案。
节点 4——消息自动处理，靠的是消息回调接口。接收后续消息、按关键词或意图分类、调不同的处理逻辑（自动回复/转人工/进队列）。
二、接口串联的关键：事件驱动加状态机
四个节点不是串行同步执行的——好友申请通过之后，欢迎语可能失败要重试，补资料可能因为频率限制延后。整条链路用状态机管理，每个节点有独立状态（待处理/处理中/成功/失败待重试/失败转人工），失败不影响下游继续接收新申请。
状态机的好处是某一步挂了不会整条链停摆，恢复时能从断点接着走。
三、幂等：每节点都要做
好友申请事件可能被平台重推、补资料接口可能超时重放——同一个申请进来多次，如果没幂等就会出现重复通过、重复发欢迎语、重复打标签。
每个节点用不同的幂等键：好友申请按"申请 ID"，补资料按"wxid 加操作类型"，消息处理按"消息 ID"。
四、组合应用对照
节点 | 依赖接口 | 状态 | 幂等键 | 失败动作 |
|---|---|---|---|---|
申请监听 | 事件推送 | 待处理 | 申请 ID | 转人工 |
自动通过 | 通过接口 | 处理中 | 申请 ID | 重试3次 |
补资料 | 资料更新 | 待补 | wxid+操作 | 入待补队列 |
消息处理 | 回调接口 | 处理中 | 消息 ID | 入死信 |
完整链路实现
import time class FullOnboardPipeline: def __init__(self, api, store, handler): self.api = api self.store = store # 持久化状态机 self.handler = handler # 后续消息处理 def on_friend_request(self, req): key = f"fr:{req['req_id']}" if self.store.state(key) == "done": return "skip" # 节点 1：监听（已收到） self.store.set_state(key, "received") # 节点 2：分类通过 if not self._should_accept(req): self.store.set_state(key, "manual") return "manual" self.store.set_state(key, "accepting") try: self.api.post("/friend/accept", {"req_id": req["req_id"]}) except Exception: self.store.set_state(key, "accept_retry") return "retry" self.store.set_state(key, "accepted") time.sleep(3) self.api.post("/send", { "wxid": req["wxid"], "content": self.welcome(req["source"]), }) # 节点 3：补资料（异步，可能延后） self.store.set_state(key, "enriching") self.store.enqueue_later("enrich", { "wxid": req["wxid"], "source": req["source"], }, delay=10) # 节点 4：后续消息交给统一 handler self.handler.register_user(req["wxid"], req["source"]) self.store.set_state(key, "done") return "ok" def _should_accept(self, req): if req["wxid"] in self.store.blacklist(): return False return req["source"] == "qrcode" or "推荐" in req.get("msg", "")落地建议
组合应用不是"接一个接口"，是把多个接口串成一条业务链，每个节点独立状态管理，失败不影响后续。整条链用事件驱动加状态机，每节点有独立状态和失败动作，挂了能从断点恢复。幂等每节点都要做，不同节点用不同幂等键。补资料这类可能延后的操作单独入队，别跟主链路绑定死。微信侧的好友、消息接口由Eyun这类个人微信API平台 提供，状态机和链管理在自建服务实现，具体字段以平台开发文档为准。
