直接讲三个我在企微对接里真踩过的坑——消息丢失、鉴权失败、高并发打挂服务以及最后是怎么修好的。每个坑都带排查思路和落地代码。坑一消息偶尔丢失其实是重复推送被当新消息现象客户说发了三条消息系统只处理了一条。排查翻回调日志发现同一条原材料被打了好几次。原因是我一开始没做幂等——企微回调是至少一次投递网络抖动或我返回慢它就会重推。修复用X-Eyun-Delivery头做去重同一个投递 id 只处理一次delivery request.headers.get(X-Eyun-Delivery) if not redis.setnx(fcb:{delivery}, 1, ex86400): return ok顺带把5 秒内返回这条铁律落实——处理放到队列接口先返回 ok。返回慢是重复推送的主因。坑二鉴权失败两套 code 体系搞混了现象接口返回code: 40001字符串一度以为封套解析错了。排查企微 API 的响应 code 有两套含义。网关和鉴权层的错误code 是字符串业务层的成功是数字 0、失败是 -1具体错误码在 message 里。// 成功 {code: 0, data: {...}, message: } // 业务失败 {code: -1, data: null, message: 具体错误} // 鉴权失败 {code: 401, message: token invalid}修复判断成功别写if code 0就完事要区分类型def is_ok(resp): return resp[code] 0 # 数字 0 才算业务成功另外两个高频原因Token 过期有效期 7200 秒要提前刷新、个人号和企微号的凭证混用两条产品线凭证不通用。坑三高并发下接口被限流打挂现象做活动期间推送量大接口返回 -301002 一片一片业务消息积压。排查-301002 是企微的限流码。当时没有前置限流全靠平台返回后再退避等于把压力全打出去。修复三步前置令牌桶按接口路径分别限速别共用一个桶指数退避被拒后按 2^n 秒重试封顶 32 秒队列削峰业务事件先入队Worker 按节奏消费def call_with_retry(module, action, payload, retries4): for i in range(retries): resp request_call(module, action, payload) if resp[code] -1 and 301002 in str(resp[message]): time.sleep(min(2 ** i, 32)) continue return resp queue.push({module: module, action: action, payload: payload})三个坑的共同教训回头看这三个问题的根子是同一类坑根因关键动作消息丢失没做幂等Delivery 去重 快速返回鉴权失败没搞懂 code 体系区分字符串/数字 code高并发没前置限流令牌桶 退避 队列企微对接要稳靠的不是单点技巧而是幂等、类型清晰、限流前置这三条原则贯穿始终。接口用的是 Eyun 平台的企业微信 API路径统一是/wx-api/api/模块/动作鉴权Bearer eyk_xxxx凭证在官网开通实例时拿到。开发文档里把错误码和封套结构写清楚了对着查比瞎试快得多。