微寻微信协议 API 的 PHP SDK。
覆盖 226 个客户可用接口,强类型、内置限速、大整数安全,配套 WebSocket 实时消息与扫码登录。
composer require weixun/weixun-php
PHP 8.0+(用到 readonly 属性与命名参数)
$c = new Weixun\Client('http://127.0.0.1:7006', '你的协议 license Key');
$res = $c->message()->sendText('wxid_xxxxx', '订单已发货');
if (!$res->ok) {
echo '发送失败: ' . $res->errorMessage;
}这个 SDK 不是简单的 HTTP 包装,它把 API 实际使用中容易踩的坑都处理掉了。
API 绝大多数情况都返回 HTTP 200,成败在响应体的 Code 字段。
而且 Code 可能是数字 200,也可能是字符串 "200"。
判定顺序:
Code存在且为0或200→ 成功Code不存在 → 回退Success == true- 都无法判定 → 失败
关键反例:/user/SetProxy 返回 Code=200 但 Success 缺失或为 false,
所以不能用 Success == true 作为主判据。
new_msg_id 这类字段超过 2^53,JS 的 JSON.parse 会静默截断。
部分接口已做字符串化处理,其余仍是裸数字。
SDK 在契约层就把 23 个 64 位字段声明为 string。
服务端不对请求做频率限制:并发猛发不会收到错误码,而是直接承担微信侧的风控后果。
SDK 默认 40 条/分钟(官方风控建议)。关闭需显式配置,请自行承担风险。
批量发送接口返回数组,但:
- 接收方字段有两种拼写:
toUSerName(14 处)与toUserName(9 处) - 成功标志有 7 种命名:
isSendSuccess/isCommentSuccess/isMarkSuccess/ … - 错误信息有拼写错误:
errMgs(UploadFriendCircleImage)
SDK 统一归一化为 ok / to / errorMessage。
5 个状态(waiting / login_processing / ipad_required / online /
security_verify_required)+ 13 个 reasonCode。轮询节奏建议 2.5 秒(官方推荐)。
src/
├── Client.php 客户端 + 统一调用出口
├── Envelope.php 信封判定 + APIError
├── MessageService.php 消息服务 + 逐条结果归一化
├── MessageResult.php 单条结果
├── LoginService.php 扫码登录状态机(含 LoginState)
├── StreamFrame.php WS 帧解析
├── UploadService.php multipart + base64
└── RateLimiter.php 令牌桶
contract/weixun-api.json 是本 SDK 覆盖的接口定义(OpenAPI 3.0),共 226 个端点。
已修正 64 位整数精度、空引用、非标准类型等问题。
接口若有版本更新,运行 scripts/sync-contract.sh 同步契约后重新生成模型即可。
contract/CONTRACT_VERSION 记录当前契约版本,便于追溯。
php tests/conformance.php测试读取 conformance/fixtures/ 下的行为样本,七个语言跑同一套断言,
任何语言行为不一致都会被发现。
- 本 SDK 是非微信官方接口的客户端,与腾讯无关
- 账号风控由使用者自行承担,建议先用测试 Key 验证
- 微寻只提供收发消息的通道,机器人逻辑与知识库都在调用方自己的程序里
MIT