官网友情链接 wechatapi.net
微信二次开发项目上线后，经常会遇到一种非常典型的情况。
客户反馈：
"我发了消息，但是系统没有处理。"
技术人员第一反应可能是微信 API 有没有收到。
但真正排查起来，问题可能发生在任何一个环节。
WechatApi 已经正常回调。
消息也已经入库。
但是 CRM 消费者异常。
或者 AI 服务超时。
或者工单创建失败。
如果系统没有完整日志和监控，排查这种问题会非常困难。
因此，日志和可观测性并不是微信二次开发上线后的附加功能，而应该从一开始就设计。
一、业务痛点或常见误区
很多项目只有简单日志：
"收到消息。"
"发送成功。"
一旦出问题，无法知道消息具体经历了什么。
第二个问题是日志没有统一 ID。
回调接口有自己的日志。
AI 有自己的日志。
CRM 又是另一套。
技术人员无法把它们关联起来。
第三个问题是只有日志，没有监控。
系统已经积压几万条队列任务，但没有任何人知道。
直到客户大量反馈才开始排查。
二、系统设计思路
微信二次开发应该给每条消息生成 traceId。
WechatApi 回调进入系统以后，立即创建 traceId。
后续所有业务动作都携带这个 ID。
例如：
message_received
message_queued
ai_started
ai_completed
crm_sync_started
crm_sync_failed
reply_sent
通过 traceId 可以查看完整调用链。
除了日志，还需要监控指标。
包括：
回调成功率；
队列积压；
消费者处理速度；
发送失败率；
接口错误率；
数据库响应时间。
三、具体落地方式
收到微信消息后记录：
traceId；
messageId；
accountId；
senderId；
messageType；
receiveTime。
入队后记录 queueName。
消费者开始处理时记录 startTime。
处理完成记录 duration。
如果失败，记录：
errorCode；
errorMessage；
retryCount。
如果最终发送回复，也记录发送结果。
这样一条客户消息从进入系统到最终回复，完整链路都有数据。
四、工程细节
日志最好采用结构化日志。
不要只写：
"处理失败。"
应该包含字段。
例如：
traceId=abc123
module=crm_sync
customerId=1001
error=timeout
敏感信息不要直接打印。
手机号需要脱敏。
聊天内容根据实际情况控制。
告警也需要分级。
单条任务失败不一定需要报警。
但如果 5 分钟内失败率超过一定比例，就应该告警。
队列积压超过阈值也应该提醒。
五、风险边界
日志系统本身也存在数据安全问题。
因为日志可能包含客户信息。
因此不能为了方便排查，把完整聊天内容全部输出。
WechatApi 回调原始数据也应限制访问。
普通业务人员没有必要查看底层报文。
日志保留时间需要合理设置。
过期日志可以归档或删除。
六、持续优化或数据复盘
监控数据可以帮助发现很多隐藏问题。
例如凌晨消息处理突然变慢。
可能是数据库定时任务占用资源。
某个微信账号发送失败率明显高于其他账号。
可能需要单独检查账号状态。
AI 平均响应时间不断上升。
可以考虑增加超时和降级策略。
通过监控，可以在客户发现问题之前提前处理。
七、总结
微信二次开发上线以后，很多问题并不是微信 API 本身的问题，而是发生在消息进入系统之后。
WechatApi 可以负责微信 API 接入，但后续还有队列、数据库、AI、CRM、工单和消息发送等多个环节。
只有通过 traceId、结构化日志、监控指标、失败告警和任务补偿，才能真正知道系统现在是否健康。
微信 API 接入只是开始。
看得见每一条消息走到了哪里，才是微信二次开发真正进入稳定运行阶段的重要标志。