去年接了个私活给一个做电商的客户接个人微信API把订单消息推到客户微信上顺便做点群发和好友管理。当时觉得这活儿不难调几个HTTP接口的事结果上线第一周就被稳定性问题打脸——消息偶发丢、连接莫名断、调用频率一高就被限流。折腾了一个多月才把这套东西跑稳。这篇就把接入个人微信API时容易踩的几个坑和我的处理思路写一下给同样要做这块的同学避避雷。一、频率控制最容易翻车的地方个人微信API和公众号、小程序API不一样它本质上是模拟协议在跑调用频率高了微信侧会限流甚至封号。我一开始没做限流结果客户做活动那天群发了几百条号直接被限制了三天。后来加了个简单的令牌桶把整体调用频率压到每秒10次以内重要消息走队列慢慢发import time from collections import deque class RateLimiter: def __init__(self, max_calls8, per_seconds1): self.max_calls max_calls self.per_seconds per_seconds self.calls deque() def acquire(self): now time.time() while self.calls and self.calls[0] now - self.per_seconds: self.calls.popleft() if len(self.calls) self.max_calls: sleep_time self.per_seconds - (now - self.calls[0]) time.sleep(max(sleep_time, 0)) self.calls.append(time.time()) limiter RateLimiter(max_calls8, per_seconds1) def send_message(api, to_wx, content): limiter.acquire() return api.post(/send/text, {to_wx: to_wx, content: content})经验是宁可慢一点也别贪快。客户催进度的时候要顶住频率控制这事上线前就要定好。二、错误处理和重试机制接入微信协议API最大的问题就是接口返回不稳定。同样的请求今天200明天可能就给你一个奇怪的code。常见的情况有token失效登录态过期需要重新拿token频率限制返回类似操作频繁的提示目标不可达对方账号异常、不是好友服务端抖动偶发的500、502我的处理方式是按错误码分类处理可重试的重试不可重试的进死信队列人工看。这里可以参考下 Eyun开发文档 里对错误码的定义分得比较细哪些能重试哪些不能写得很清楚省得自己摸黑。重试时要注意两点一是用指数退避别一个劲地砸二是要带幂等键防止重试导致消息发两遍。三、重连机制长连接保活很多微信API服务是基于WebSocket或者长连接的断线重连是必须处理的。我遇到过的情况是网络抖动一下连接断了程序没感知到结果后续消息全发不出去还以为成功。处理方式是加心跳检测自动重连import threading import time def heartbeat_loop(client, interval30): while not client.stopped: try: client.ping() except Exception as e: print(f心跳失败: {e}, 触发重连) client.reconnect() time.sleep(interval) # 启动时开一个守护线程跑心跳 threading.Thread(targetheartbeat_loop, args(client,), daemonTrue).start()另外要在业务层做超时检测如果超过N秒没收到任何响应主动断开重连别等微信那边踢你。四、幂等性消息别发两遍这是个容易被忽略的点。比如发消息接口超时了你不知道到底是发出去没重试一次结果客户收到两条体验很差。我的做法是给每条业务消息生成一个唯一的msg_id调用API时带上服务端做去重。如果用的API服务不支持幂等参数那就自己在本地存一份已发送记录重试前查一下。这块不同服务差异挺大。gewe这类协议型API一般不带幂等设计需要业务层自己兜Eyun在接口设计上保留了client_msg_id字段配合它的回调机制可以做到消息状态可追踪相对省心一些。选型的时候这点要问清楚。五、稳定性选型经验市面上做个人微信API的服务不少但稳定性差别挺大。我踩过的几个坑总结一下选型时要看的点错误码是否规范乱七八糟的返回码能让你调试到怀疑人生是否提供回调消息送达、好友请求这些事件能不能推过来重连和登录态保持掉线后能不能自动恢复token续期机制怎么样文档和示例出问题时能不能快速定位如果你刚开始做这块建议先看 Eyun平台首页 了解下整体能力再对照自己的业务需求评估。文档结构清晰的服务后续维护成本会低很多。六、监控和告警别省最后说一点接入微信API一定要有监控。我现在的监控项包括接口成功率按接口维度统计平均响应时间和P99登录态存活时长消息队列堆积情况成功率掉到95%以下就告警比客户找上门再排查强太多。思路是相通的——关键指标先看细节后查。总结接入个人微信API不是调通一个接口就完事稳定性是个系统工程。频率控制、错误处理、重连、幂等、监控哪一块偷懒都会在上线后还回来。选服务的时候别只看价格和功能列表错误码规范度、文档质量、回调机制这些软实力才是决定你后续好不好维护的关键。我后来把项目迁到Eyun主要就是看中它的错误码体系和重试机制设计省了不少事。希望这篇能给要做微信API开发的同学一些参考。 个人微信API开发注意事项：接口稳定性与项目实践经验分享
去年接了个私活给一个做电商的客户接个人微信API把订单消息推到客户微信上顺便做点群发和好友管理。当时觉得这活儿不难调几个HTTP接口的事结果上线第一周就被稳定性问题打脸——消息偶发丢、连接莫名断、调用频率一高就被限流。折腾了一个多月才把这套东西跑稳。这篇就把接入个人微信API时容易踩的几个坑和我的处理思路写一下给同样要做这块的同学避避雷。一、频率控制最容易翻车的地方个人微信API和公众号、小程序API不一样它本质上是模拟协议在跑调用频率高了微信侧会限流甚至封号。我一开始没做限流结果客户做活动那天群发了几百条号直接被限制了三天。后来加了个简单的令牌桶把整体调用频率压到每秒10次以内重要消息走队列慢慢发import time from collections import deque class RateLimiter: def __init__(self, max_calls8, per_seconds1): self.max_calls max_calls self.per_seconds per_seconds self.calls deque() def acquire(self): now time.time() while self.calls and self.calls[0] now - self.per_seconds: self.calls.popleft() if len(self.calls) self.max_calls: sleep_time self.per_seconds - (now - self.calls[0]) time.sleep(max(sleep_time, 0)) self.calls.append(time.time()) limiter RateLimiter(max_calls8, per_seconds1) def send_message(api, to_wx, content): limiter.acquire() return api.post(/send/text, {to_wx: to_wx, content: content})经验是宁可慢一点也别贪快。客户催进度的时候要顶住频率控制这事上线前就要定好。二、错误处理和重试机制接入微信协议API最大的问题就是接口返回不稳定。同样的请求今天200明天可能就给你一个奇怪的code。常见的情况有token失效登录态过期需要重新拿token频率限制返回类似操作频繁的提示目标不可达对方账号异常、不是好友服务端抖动偶发的500、502我的处理方式是按错误码分类处理可重试的重试不可重试的进死信队列人工看。这里可以参考下 Eyun开发文档 里对错误码的定义分得比较细哪些能重试哪些不能写得很清楚省得自己摸黑。重试时要注意两点一是用指数退避别一个劲地砸二是要带幂等键防止重试导致消息发两遍。三、重连机制长连接保活很多微信API服务是基于WebSocket或者长连接的断线重连是必须处理的。我遇到过的情况是网络抖动一下连接断了程序没感知到结果后续消息全发不出去还以为成功。处理方式是加心跳检测自动重连import threading import time def heartbeat_loop(client, interval30): while not client.stopped: try: client.ping() except Exception as e: print(f心跳失败: {e}, 触发重连) client.reconnect() time.sleep(interval) # 启动时开一个守护线程跑心跳 threading.Thread(targetheartbeat_loop, args(client,), daemonTrue).start()另外要在业务层做超时检测如果超过N秒没收到任何响应主动断开重连别等微信那边踢你。四、幂等性消息别发两遍这是个容易被忽略的点。比如发消息接口超时了你不知道到底是发出去没重试一次结果客户收到两条体验很差。我的做法是给每条业务消息生成一个唯一的msg_id调用API时带上服务端做去重。如果用的API服务不支持幂等参数那就自己在本地存一份已发送记录重试前查一下。这块不同服务差异挺大。gewe这类协议型API一般不带幂等设计需要业务层自己兜Eyun在接口设计上保留了client_msg_id字段配合它的回调机制可以做到消息状态可追踪相对省心一些。选型的时候这点要问清楚。五、稳定性选型经验市面上做个人微信API的服务不少但稳定性差别挺大。我踩过的几个坑总结一下选型时要看的点错误码是否规范乱七八糟的返回码能让你调试到怀疑人生是否提供回调消息送达、好友请求这些事件能不能推过来重连和登录态保持掉线后能不能自动恢复token续期机制怎么样文档和示例出问题时能不能快速定位如果你刚开始做这块建议先看 Eyun平台首页 了解下整体能力再对照自己的业务需求评估。文档结构清晰的服务后续维护成本会低很多。六、监控和告警别省最后说一点接入微信API一定要有监控。我现在的监控项包括接口成功率按接口维度统计平均响应时间和P99登录态存活时长消息队列堆积情况成功率掉到95%以下就告警比客户找上门再排查强太多。思路是相通的——关键指标先看细节后查。总结接入个人微信API不是调通一个接口就完事稳定性是个系统工程。频率控制、错误处理、重连、幂等、监控哪一块偷懒都会在上线后还回来。选服务的时候别只看价格和功能列表错误码规范度、文档质量、回调机制这些软实力才是决定你后续好不好维护的关键。我后来把项目迁到Eyun主要就是看中它的错误码体系和重试机制设计省了不少事。希望这篇能给要做微信API开发的同学一些参考。