所有微信消息最终都是数据但不同类型消息的数据结构不同。理解结构差异才能正确解析内容、做对应处理。一、消息数据的共同部分不管什么类型的消息回调数据都有几个公共字段msgId消息唯一标识、fromUser发送人 wxid、groupId群ID私聊为空、createTime时间戳、messageType类型标识。这些公共字段是消息处理的入口——先读 messageType 决定怎么处理再读 fromUser 和 groupId 知道消息从哪来。msgId 做幂等去重createTime 做时序排序。二、消息数据的差异部分差异在 content 字段。文本消息的 content 是纯文本字符串程序直接读。图片消息的 content 是素材引用临时地址或标识程序要先下载才能拿到图片。文件消息的 content 也是素材引用额外带 fileName 字段。语音消息的 content 是音频素材引用需要下载后转文字。链接消息的 content 可能包含标题、描述、URL 三个子字段。系统消息的 content 是事件数据JSON 结构不是聊天内容。三、为什么必须区分类型不区分类型统一处理会导致把素材引用当文本回复给用户发一串看不懂的标识、把系统事件当聊天消息处理触发不该触发的回复、下载操作阻塞回调响应5秒超时。区分类型的核心目的不同类型走不同处理函数文本走语义理解多媒体走下载解析系统消息走事件处理。各走各的路互不干扰。四、消息结构设计的启示消息结构里公共字段差异字段的设计在程序里对应统一入口分发处理的模式。回调入口统一接收按 messageType 分发到不同 handler每个 handler 只处理自己负责的类型。这个模式的好处是扩展性——新增消息类型时只需要加一个 handler 函数不改分发逻辑和公共字段处理。消息结构对照消息类型content 内容附加字段处理路径文本纯文本字符串无直接语义处理图片素材引用无下载→OCR/存储文件素材引用fileName下载→按类型处理语音素材引用duration下载→ASR转文字链接JSON含标题描述URL无解析JSON→提取URL系统事件事件JSONeventType触发事件处理统一分发架构# 消息处理器注册表 HANDLERS { 1: handle_text, # 文本 3: handle_image, # 图片 34: handle_voice, # 语音 49: handle_file, # 文件 } def handle_text(d): 文本直接处理内容 text d[content] reply process_text(d[fromUser], text) if reply: sendText(WID, d[fromUser], reply) def handle_image(d): 图片先下载再处理 raw download_async(d[content], d[msgId]) text ocr_service.recognize(raw) if text: process_text(d[fromUser], text) def handle_file(d): 文件按扩展名分发 raw download_async(d[content], d[msgId]) ext d.get(fileName, ).rsplit(., 1)[-1].lower() handler FILE_HANDLERS.get(ext, archive_only) handler(raw, d) app.post(/webhook) def webhook(): d request.json msg_type d.get(messageType) # 公共处理幂等去重 if db.exists(messages, msgIdd[msgId]): return {code: 1000} # 已处理 db.save(messages, {msgId: d[msgId], fromUser: d[fromUser], type: msg_type, time: d[createTime]}) # 分发到对应handler handler HANDLERS.get(msg_type, handle_unknown) handler(d) return {code: 1000}落地建议消息结构的核心设计是统一入口分发处理。公共字段统一处理幂等、落库、日志差异字段分发处理按类型走不同函数。新增类型只需要加一行注册不改入口逻辑。handler 函数里多媒体类型务必异步下载不在回调里同步做耗时操作。消息类型字段值和结构说明参考 Eyun 开发文档平台开通见 Eyun 官网。