EasyWeChat 3.x 消息体系全解析：统一抽象的消息类型、服务端回复与客服消息实战

后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载EasyWeChat 将微信开放平台 API 中形形色色的消息接收消息、回复消息、客服消息、群发消息、素材消息全部抽象为统一的 PHP 消息类让开发者彻底告别手工拼装微信那套命名混乱的 XML 与 JSON。本文以 3.x 消息文档 为骨架结合仓库源码逐类讲解消息的属性、构造方式与在服务端、客服、群发场景中的落地用法读完即可写出面向对象、开箱即用的消息处理代码。消息抽象的设计思想类型统一格式无关微信的消息散布在多个接口域中形态各异接收的消息是 XML客服消息是 JSON群发素材又有一套专属结构字段命名也经常不统一例如media_id、MediaId、thumb_media_id。EasyWeChat 的解法是把消息按业务语义抽象成类型屏蔽底层格式差异。在阅读以下内容时请忽略是接收消息还是回复消息二者使用同一套消息类型区别仅在最终被发送到哪个接口。这一点在仓库源码中也有印证所有消息类的基类是 src/Kernel/Message.php 中的抽象类EasyWeChat\Kernel\Message它实现了JsonSerializable、ArrayAccess与Jsonable接口并通过 src/Kernel/Traits/HasAttributes.php 提供属性存取、toArray()、toJson()、merge()等能力。而当前仓库中的具体应用例如 src/OfficialAccount/Message.php即直接继承该基类并扩展Event、MsgType等动态属性——这正是统一消息类型设计在源码层的延续。消息类型总览SDK 将消息划分为以下类型文本、图片、视频、声音、链接、坐标、图文、文章以及一种特殊的原始消息此外还有专门用于群发与客服的素材消息。注意回复消息与客服消息里的图文类型为图文News群发与素材中的图文为文章Article两者结构不同不要混用。所有消息类都位于EasyWeChat\Message命名空间下下面逐类讲解。文本消息Text属性列表属性说明content文本内容?php use EasyWeChat\Message\Text; $text new Text([content 您好overtrue。]); // or $text new Text(); $text-content 您好overtrue。; // or $text new Text(); $text-setAttribute(content, 您好overtrue。);图片消息Image属性列表属性说明media_id媒体资源 ID素材上传后返回?php use EasyWeChat\Message\Image; $text new Image([media_id $mediaId]); // or $text new Image(); $text-media_id $mediaId; // or $text-mediaId $media; // or $text new Image(); $text-setAttribute(media_id, $mediaId);视频消息Video属性列表属性说明title标题description描述media_id媒体资源 IDthumb_media_id封面资源 ID?php use EasyWeChat\Message\Video; $video new Video([ title $title, media_id $mediaId, description ..., // ... ]); // or $video new Video(); $video-media_id $mediaId; // or $video-mediaId $media; $video-description video description...; // or $video-description $description; // ... // or $video new Video(); $video-setAttribute(media_id, $mediaId); // ...声音消息Voice属性列表属性说明media_id媒体资源 ID?php use EasyWeChat\Message\Voice; $voice new Voice([media_id $mediaId]); // or $voice new Voice(); $voice-media_id $mediaId; // or $voice-mediaId $media; // or $voice new Voice(); $voice-setAttribute(media_id, $mediaId);链接消息Link与坐标消息Location这两类消息用于接收用户消息微信目前不支持主动回复链接或坐标消息微信目前不支持回复链接消息 微信目前不支持回复坐标消息图文消息News属性列表属性说明title标题description描述image图片链接url链接 URL?php use EasyWeChat\Message\News; $news new News([ title $title, description ..., url $url, image $image, // ... ]); // or $news new News(); $news-title EasyWeChat; $news-description 微信 SDK ...; // ...文章消息Article文章消息用于群发与素材场景注意区别于客服/回复场景的News。属性列表属性说明title标题author作者content具体内容thumb_media_id图文消息的封面图片素材 id必须是永久 mediaIDdigest图文消息的摘要仅单图文消息才有摘要多图文此处为空source_url来源 URLshow_cover是否显示封面0 为 false不显示1 为 true显示?php use EasyWeChat\Message\Article; $article new Article([ title EasyWeChat, author overtrue, content EasyWeChat 是一个开源的微信 SDK它... ..., // ... ]); // or $article new Article(); $article-title EasyWeChat; $article-author overtrue; $article-content 微信 SDK ...; // ...素材消息Material素材消息用于群发与客服消息时发送已上传的素材属性只有一个media_id。构造时需要两个参数参数说明$type素材类型目前支持mpnews、mpvideo、voice、image等$mediaId素材 ID从接口查询或上传后得到use EasyWeChat\Message\Material; $material new Material(mpnews, $mediaId);以上便是微信支持的所有基本消息类型。值得注意的是你不需要关心微信消息字段本身叫什么——SDK 使用了更标准的命名并在中间层自动完成字段转换因此你只需面向这些统一的属性编程即可。原始消息Raw原始消息是一种特殊类型适用场景是不想使用其它消息类型想自己手动拼消息。比如回复消息时想自己拼 XMLuse EasyWeChat\Message\Raw; $message new Raw(xml ToUserName![CDATA[toUser]]/ToUserName FromUserName![CDATA[fromUser]]/FromUserName CreateTime12345678/CreateTime MsgType![CDATA[image]]/MsgType Image MediaId![CDATA[media_id]]/MediaId /Image /xml);客服消息是 JSON 结构同样可以交给Raw原样发送use EasyWeChat\Message\Raw; $message new Raw({ touser:OPENID, msgtype:text, text: { content:Hello World } });总之Raw就是直接写微信接口要求的格式内容。此类型消息在 SDK 中不存在转换行为格式必须严格符合微信规范写错不会得到任何提示修正。消息属性的三种构造方式从上面的例子可以看到每种消息类型除Raw外都支持三种等价写法构造数组传参new Text([content ...])——最推荐一次成型魔法属性赋值$text-content ...——可链式逐步设置且兼容驼峰变体如mediaIdsetAttribute()显式赋值$text-setAttribute(content, ...)——适合动态 key 的场景。这种灵活的属性机制并非魔术而是有源码支撑的当前仓库的 src/Kernel/Traits/HasAttributes.php 实现了__set/__get魔法方法、ArrayAccess接口与offsetSet/offsetGet属性统一存放在$attributes数组中并可随时通过toArray()、toJson()导出或通过merge()合并追加属性。因此文档中的三种写法本质都是对同一份属性数组的操作。在 SDK 中使用消息在服务端回复消息在 服务端 一节中已经讲过了服务端的搭建回复消息的写法如下// ... 前面部分省略 $app new Application($options); $server $app-server; $server-setMessageHandler(function ($message) { return 您好欢迎关注我!; }); $server-serve()-send();上面return了一句普通的文本内容这只是为了方便大家——最后 SDK 会有一个隐式转换为Text类型即文本消息的动作。如果要回复其它类型的消息就需要返回一个具体的消息实例了。比如回复一张图片use EasyWeChat\Message\Image; // ... $server-setMessageHandler(function ($message) { return new Image([media_id ........]); }); // ...注意从 服务端 的实现可知3.x 之后所有消息与事件都统一由setMessageHandler处理回调中的$message是消息对象可通过$message-FromUserName、$message-MsgType等属性判断来源与类型在回调内部用switch按MsgType分流即可。回复多图文消息多图文消息其实就是单图文消息的一个数组use EasyWeChat\Message\News; // ... $server-setMessageHandler(function ($message) { $news1 new News(...); $news2 new News(...); $news3 new News(...); $news4 new News(...); return [$news1, $news2, $news3, $news4]; }); // ...作为客服消息发送客服消息多客服的使用方式与回复消息一致直接传入消息实例即可use EasyWeChat\Message\Text; $message new Text([content Hello world!]); $result $app-staff-message($message)-to($openId)-send(); //...发送多图文消息同样地多图文即单图文的数组$news1 new News(...); $news2 new News(...); $news3 new News(...); $news4 new News(...); $app-staff-message([$news1, $news2, $news3, $news4])-to($openId)-send();群发消息群发消息请参考群发消息其中图文的正确类型是Article文章消息而非News。消息转发给客服系统当公众号需要接入多客服时可将收到的用户消息转发给客服系统具体实现参见多客服消息转发。源码视角消息从接收、解析到回复的底层链路结合当前仓库源码可以更清楚地理解这套消息体系的工作机理统一基类src/Kernel/Message.php 定义抽象基类EasyWeChat\Kernel\Message构造函数接收属性数组并保留原始内容originContent提供getOriginalContents()回溯原始报文__toString()会输出 JSON 序列化结果自动解析src/Kernel/Support/MessageParser.php 是纯粹的解析器它会先尝试用json_decode解析失败后再用Xml::parse解析 XML两者都失败则抛出BadRequestException——这正对应了接收消息是 XML、客服消息是 JSON两种格式在 SDK 内部被无感统一的现实接收入口Message::createFromRequest()与createFromStringContent()基于MessageParser将 HTTP 请求体或字符串解析为消息实例属性即可通过魔法属性、ArrayAccess或toArray()访问属性层src/Kernel/Traits/HasAttributes.php 支撑了上文三种构造写法也让消息对象同时可被当作数组使用如$message[MsgType]。小结EasyWeChat 的消息体系把微信生态里最琐碎、最容易出错的消息拼装问题收敛为 9 种语义清晰的消息类型配合三种等价构造方式、服务端回复与客服消息的统一调用形态让开发者把精力聚焦在业务逻辑上。记住几个关键点即可回复/客服图文用News、群发图文用Article、发送已有素材用Material、完全自定义格式用Raw且无转换、需自行保证格式正确。赞分享后端即时通讯【免费下载链接】easywechat 一个 PHP 微信 SDK项目地址https://gitcode.com/gh_mirrors/ea/easywechat点击查看免费下载相关推荐Forge中的项目管理构建LLM驱动的任务管理系统Forge中的项目管理构建LLM驱动的任务管理系统 Forge是一个功能强大的Python框架专为自托管LLM工具调用和多步骤代理工作流设计。它提供了完整的后端即时通讯Teable v2 adapter-logger-pino 架构解析基于 Pino 的 ILogger 端口适配器与日志工厂设计Teable v2 adapter logger pino 架构解析基于 Pino 的 ILogger 端口适配器与日志工厂设计 导读 packages/v2后端即时通讯EasyWeChat 4.x 公众号客服系统实战客服管理、消息发送与多客服会话控制EasyWeChat 4.x 公众号客服系统实战客服管理、消息发送与多客服会话控制 导读 本文基于 EasyWeChat 4.x 官方文档中「客服」章节展开后端即时通讯上一篇突破单视频限制Plyr播放列表功能全解析与实战指南下一篇freeCodeCamp 每日编程挑战解析Challenge 274 Oldest Person 找出年龄最大的人创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考