做了这么多个微API项目，踩过的坑比写的代码还多。
回想第一次接Eyun 那会儿，我天真地以为照着文档撸代码就完事了。结果上线第二天就被用户骂到怀疑人生——消息发不出去、回调收不到、号还被封了。那时候才明白，文档教会你怎么用API，但教不会你怎么不踩坑。
今天把这几年踩过的坑整理一下，挑出8个最容易被忽略的误区，每个都配真实故事，希望你看完能少走点弯路。
误区一：HTTP 200就是成功
错误做法：调发送消息接口，看到返回200就觉得万事大吉，日志都不打。
踩坑故事：有次做客服自动回复，客户反馈消息经常漏发。我查日志全是200，一度怀疑是客户撒谎。后来仔细看响应体，里面写的是"投递中，task_id=xxx"。原来这API是异步的，200只代表"我收到你的请求了"，不代表"消息发出去了"。真正的结果要靠回调或者主动查询task_id。
正确做法：拿到响应后保存task_id，监听回调里的状态事件，失败的要重试，别信200。
踩坑代价：客户投诉3天，差点丢单。
误区二：不需要限流，反正API能扛
错误做法：写个循环一把梭，几万条消息一秒钟全打出去。
踩坑故事：去年双十一，老板让给老客户群发优惠信息，我写了段for循环没加任何sleep。结果发到第800条号就被风控了，提示"操作过于频繁"。更惨的是后面群发的全是失败，号也禁言了24小时。
正确做法：按文档建议的QPS限流，个微API一般建议每秒5-10条，批量发送还要加随机间隔，别让请求看起来像机器刷的。
踩坑代价：号禁言一天，双十一活动黄了一半。
误区三：回调里同步处理业务逻辑
错误做法：收到回调，直接在里面查数据库、调外部接口、写文件，处理完再返回。
踩坑故事：有次在回调里同步去查用户订单系统，结果订单系统慢查询卡了6秒，微信那边5秒超时，直接把这次回调当失败重试了。然后我这边同一个事件被处理了3遍，用户收到了3条重复回复。
正确做法：回调收到立马返回200，业务逻辑丢到消息队列或者线程池里异步处理。
踩坑代价：用户被刷屏投诉，口碑掉了一截。
误区四：全量订阅事件，能收的都收
错误做法：图省事，把Eyun 所有事件类型全订阅了，反正多收不亏。
踩坑故事：早期项目我这么干过，结果每天日志几十G，全是心跳、状态变更这种我根本用不上的事件。真正有用的消息被淹没在里面，排查问题时grep半天都翻不到。服务器磁盘一周爆一次。
正确做法：只订阅业务真正需要的事件，比如做客服就订阅消息接收和发送状态，别订阅什么群成员变更、设备状态这种无关的。
踩坑代价：磁盘费、日志费、排查时间，三重打击。
误区五：不做幂等，反正不会重复
错误做法：消息处理逻辑直接往下走，不加任何去重判断。
踩坑故事：接了个红包提醒功能，结果某天微信回调重试机制触发，同一条红包消息被处理了2次，用户被提醒了2遍。还有更绝的，自动入群欢迎语，新成员被欢迎了3次，尴尬得要死。
正确做法：每条消息用msg_id或者事件唯一标识做幂等key，处理前先查Redis，已处理过的直接跳过。
踩坑代价：用户体验差，产品被吐槽不专业。
误区六：硬编码AppSecret到代码里
错误做法：直接把AppSecret写在配置文件或者代码里，方便嘛。
踩坑故事：同事把项目push到公开Git仓库，AppSecret也在里面。第二天就被人扫到了，拿我们的号去群发垃圾广告，号直接被封30天。整个团队重新走申请流程，项目延期两周。
正确做法：所有密钥走环境变量或者密钥管理服务，代码里绝不出现明文，Git仓库加pre-commit hook扫描敏感信息。
踩坑代价：号被封30天，项目延期2周，老板脸黑了一周。
误区七：用主号做测试
错误做法：图方便，直接拿自己日常用的微信号调API测各种边界情况。
踩坑故事：我入职第一周，拿自己号测群发功能，结果触发了批量发送风控，号被封了30天。那时候女朋友找我都联系不上，解释半天。从那以后我再也不敢用主号测了。
正确做法：单独准备1-2个测试号，跟主号完全隔离，封了也不心疼。最好号的注册时间、好友数量都接近真实场景。
误区八：不做监控，全靠用户反馈
错误做法：上线后就不管了，等用户投诉才知道出了问题。
踩坑故事：去年有个项目，发送成功率从98%掉到60%，我硬是半天没发现，因为没监控。等客户打电话过来骂，我才知道API那边出了故障，我们这边一直在重试一直失败。从那以后我学乖了。
正确做法：关键指标都要监控——成功率、响应时间、回调延迟、队列堆积。设阈值告警，微信API或者个微API出问题第一时间能感知。
踩坑代价：故障持续半天，损失一批客户。
八大误区速查表
误区 | 错误做法 | 正确做法 |
|---|---|---|
200=成功 | 只看状态码 | 解析响应体+监听回调 |
不限流 | 一把梭批量发 | 按QPS限流+随机间隔 |
同步回调 | 回调里处理业务 | 快速返回+异步队列 |
全量订阅 | 收所有事件 | 只订需要的事件 |
不幂等 | 直接处理消息 | 用msg_id去重 |
硬编码密钥 | 写代码里 | 走环境变量/密钥服务 |
主号测试 | 用自己号 | 准备独立测试号 |
不监控 | 靠用户反馈 | 全链路监控+告警 |
一个正确的回调处理长啥样
下面这段是我现在项目里在用的回调处理模板，快速返回+异步处理+幂等校验三件套：
def handle_callback(request): event = request.json msg_id = event.get("msg_id") or event.get("task_id") # 幂等校验，已处理过的直接返回200，别让微信重试 if redis.exists(f"processed:{msg_id}"): return {"code": 200}, 200 # 标记为处理中，设5分钟过期防死锁 redis.set(f"processed:{msg_id}", "1", ex=300) # 丢到队列异步处理，回调本身不阻塞 queue.push("wechat_events", event) # 立即返回，绝不在这里处理业务 return {"code": 200}, 200这段代码看着简单，但每行都是踩坑换来的：幂等是教训五换来的，异步是教训三换来的，快速返回是5秒超时换来的。
写在最后
这些坑我都踩过，有些踩得还挺疼，希望你别再踩。
做微信API开发，技术只是基础，真正决定项目能不能稳定跑下去的，是这些细节——限流、幂等、监控、密钥管理。这些事情文档不会强调，但实战里全是血泪。
如果你也在做这块，建议把上面8条对照自己项目过一遍，有问题的赶紧改。早改一天，少踩一个坑。
更多个微API和Eyun相关的开发实践，可以看 Eyun开发文档，文档挺全的，踩坑之前先看一遍能少走不少弯路。
