官网友情链接 wechatapi.net个人微信二次开发系统里消息重复是最常见、也最容易被低估的问题之一。一条客户消息可能因为上游重复回调网络重试消息队列重新投递服务重启消费者超时进入业务系统不止一次。如果系统只依赖“数据库里有没有一模一样的文本”来去重非常不可靠。客户完全可能真的连续发送两句相同内容“在吗”“在吗”这两条是真实消息。而同一个 message_id 被处理两次才属于重复事件。所以微信二次开发需要设计真正的幂等体系。WechatApi 可以作为个人微信API接入层把微信消息、事件标识、账号、群聊和附件带入业务系统。本地事件中心则使用幂等表阻止同一事件重复产生AI回复、工单、CRM记录和客户标签。一、什么是幂等同一个业务事件无论被执行一次还是多次最终业务结果都一样。例如消息M100创建工单候选。第一次执行生成T100。第二次因为队列重复投递。系统识别M100已经执行过 create_ticket_candidate。直接返回T100。而不是生成T101。二、为什么不能只在message表上唯一消息入库幂等只解决同一条消息不重复保存。但一条消息可能触发多个动作AI回复标签CRM工单。所以还要做动作级幂等。三、一个具体例子M100“我这里上传失败。”系统第一次处理保存消息创建AI任务A1创建工单候选T1更新客户最近活跃。队列消费者崩溃。消息重新投递。如果只有message表唯一约束虽然不会再插一条消息但业务代码仍然可能再次创建A2、T2。所以需要idempotency_key M100 action_type。四、幂等表可以保存什么keyaction_typebusiness_object_idstatuscreated_atfinished_atresult_reference。例如M100:ticket_candidate → T1。后续重复请求直接复用。五、WechatApi 在这里的位置WechatApi负责稳定消息标识和真实事件。本地系统基于这个标识建立业务幂等。不能使用消息文本代替稳定标识。六、群消息也必须幂等微信群里一条消息可能从多个接入关系被重复看到。尤其多账号都在同一群时。系统需要把它归一成logical_message_id。再进入业务幂等。否则多个账号都可能触发机器人。七、文件任务幂等图片消息M200。下载任务第一次已经成功。消费者重试时应该直接使用file_id。不要再次下载并保存一份。这可以避免文件重复和资源浪费。八、AI回复幂等更加重要如果AI任务重复创建。即使最终文本不同也会给客户发两次。可以用source_message_batch reply_policy_version生成reply idempotency key。同一个业务输入只允许一个客户可见回复。九、人工点击也会造成重复销售点“发送”。页面卡顿。又点一次。两个请求几乎同时到达。如果后台没有幂等客户收到两条。所以人工动作同样需要request_id / idempotency_token。十、幂等状态不能只有完成有时第一个请求正在执行。第二个请求进来。幂等表状态processing。第二个请求应该等待或返回处理中。不能认为没完成就再执行。十一、执行失败以后是否允许重试可以。状态failed_retryable。下一次继续使用同一个key。但真正客户可见动作执行前还要判断是不是外部其实已经成功。这就是幂等与状态回补的结合。十二、幂等记录生命周期不能无限保存所有低价值幂等key。可以按业务类型设TTL。例如消息业务幂等保留较久。临时后台统计任务可以短一些。但在可能重复投递的时间窗口内必须存在。十三、业务唯一约束比代码判断更可靠代码先查不存在。然后插入。两个并发请求同时查都不存在。仍然重复。所以关键幂等最好结合数据库唯一约束。让底层真正保证只有一个成功。十四、客户标签也需要来源幂等同一消息多次处理不能生成多条同来源标签。唯一键customer tag source_event。如果另一条真实消息再次产生同样标签可以是新的来源。十五、CRM同步消息M100生成CRM跟进。CRM调用超时。重试时携带同一个external_request_id。让上下游都具备幂等能力。仅本地去重仍然不够。十六、数据看板重复事件数量幂等命中重复发送拦截重复工单拦截按账号和消息类型。如果突然大量幂等命中说明上游可能异常重复推送。十七、日志幂等命中时也要记录原执行当前重复请求返回了哪个已有结果。以后排查非常方便。十八、总结个人微信二次开发系统里重复事件不是异常边缘情况而是必须默认会发生的正常工程问题。WechatApi 可以把微信消息和事件稳定接入系统但业务层仍然要通过消息幂等、动作幂等、数据库唯一约束和外部请求ID保证同一个事件无论被投递多少次都只产生一次真实业务结果。真正成熟的微信机器人不是“希望消息不要重复”而是即使重复回调、服务重启、任务重试同时发生客户仍然只收到一次回复、CRM只产生一条记录、工单只创建一次。幂等不是优化项而是生产级微信二次开发的基础能力。