Skip to content

About

微寻微信协议 API 的 Java SDK:226 个接口、强类型、内置限速

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

weixun-java

微寻微信协议 API 的 Java SDK。

覆盖 226 个客户可用接口,强类型、内置限速、大整数安全,配套 WebSocket 实时消息与扫码登录。

安装

<dependency>
  <groupId>site.weixun</groupId>
  <artifactId>weixun-java</artifactId>
  <version>0.1.0</version>
</dependency>

Java 11+

快速开始

var c = new Client("http://127.0.0.1:7006", "你的协议 license Key");

var res = c.message().sendText("wxid_xxxxx", "订单已发货");
if (!res.ok()) {
    System.out.println("发送失败: " + res.errorMessage());
}

核心设计

这个 SDK 不是简单的 HTTP 包装,它把 API 实际使用中容易踩的坑都处理掉了。

1. 成功判定不是看 HTTP 状态码

API 绝大多数情况都返回 HTTP 200,成败在响应体的 Code 字段。 而且 Code 可能是数字 200,也可能是字符串 "200"。

判定顺序:

  1. Code 存在且为 0 或 200 → 成功
  2. Code 不存在 → 回退 Success == true
  3. 都无法判定 → 失败

关键反例:/user/SetProxy 返回 Code=200 但 Success 缺失或为 false, 所以不能用 Success == true 作为主判据。

2. 64 位 ID 一律用字符串

new_msg_id 这类字段超过 2^53,JS 的 JSON.parse 会静默截断。 部分接口已做字符串化处理,其余仍是裸数字。

SDK 在契约层就把 23 个 64 位字段声明为 string。

3. 内置限速(服务端不限流)

服务端不对请求做频率限制:并发猛发不会收到错误码,而是直接承担微信侧的风控后果。

SDK 默认 40 条/分钟(官方风控建议)。关闭需显式配置,请自行承担风险。

4. 逐条结果字段不统一

批量发送接口返回数组,但:

  • 接收方字段有两种拼写:toUSerName(14 处)与 toUserName(9 处)
  • 成功标志有 7 种命名:isSendSuccess / isCommentSuccess / isMarkSuccess / …
  • 错误信息有拼写错误:errMgs(UploadFriendCircleImage)

SDK 统一归一化为 ok / to / errorMessage。

5. 登录状态机

5 个状态(waiting / login_processing / ipad_required / online / security_verify_required)+ 13 个 reasonCode。轮询节奏建议 2.5 秒(官方推荐)。

目录结构

src/main/java/site/weixun/sdk/
├── Client.java          客户端 + 统一调用出口
├── Envelope.java        信封判定 + APIError
├── MessageService.java  消息服务 + 逐条结果归一化
├── MessageResult.java   单条结果
├── LoginService.java    扫码登录状态机
├── Stream.java          WS 帧解析 + 建连
├── UploadService.java   multipart + base64
└── RateLimiter.java     令牌桶

接口契约

contract/weixun-api.json 是本 SDK 覆盖的接口定义(OpenAPI 3.0),共 226 个端点。 已修正 64 位整数精度、空引用、非标准类型等问题。

接口若有版本更新,运行 scripts/sync-contract.sh 同步契约后重新生成模型即可。 contract/CONTRACT_VERSION 记录当前契约版本,便于追溯。

测试

mvn test

测试读取 conformance/fixtures/ 下的行为样本,七个语言跑同一套断言, 任何语言行为不一致都会被发现。

边界

  • 本 SDK 是非微信官方接口的客户端,与腾讯无关
  • 账号风控由使用者自行承担,建议先用测试 Key 验证
  • 微寻只提供收发消息的通道,机器人逻辑与知识库都在调用方自己的程序里

许可证

MIT

About

微寻微信协议 API 的 Java SDK:226 个接口、强类型、内置限速

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages