Java 生态做个人微信二次开发，最大的障碍从来不是语言本身，而是微信协议：网页版协议基本不可用，Hook
方案封号风险高，微信版本一升级就要重新适配。WTAPI 这类微信机器人接口框架把这些脏活累活收口到了服务端——基于 iPad / Mac 协议，Java 侧只需要发标准 HTTP 请求，就能操作已登录的微信实例。

一、准备工作

控制台完成两步：「Token回调」页拿到 X-finder-TOKEN（部分环境还需 Authorization: Bearer 头，以文档为准）；「微信实例」页扫码登录，系统生成实例标识 appId。

API 基础地址：`WTAPI框架

二、发送文本消息

官方文档各接口提供多语言请求示例，Java 示例使用 Unirest。先引入依赖，再调用消息接口 postText：

<dependency>
    <groupId>com.konghq</groupId>
    <artifactId>unirest-java</artifactId>
    <version>3.14.5</version>
</dependency>

import kong.unirest.HttpResponse;
import kong.unirest.Unirest;

public class WtapiDemo {

    public static void main(String[] args) {
        HttpResponse<String> response = Unirest.post(
                "https://wx.chuapi.com/finder/v2/api/message/postText")
            .header("X-finder-TOKEN", "YOUR_TOKEN")
            .header("Authorization", "Bearer YOUR_JWT")   // 部分环境需要
            .header("Content-Type", "application/json")
            .body("{\"appId\":\"YOUR_APPID\","
                + "\"toWxid\":\"filehelper\","
                + "\"content\":\"Hello, WTAPI\"}")
            .asString();

        System.out.println(response.getBody());
    }
}

请求体三个参数均为官方定义：appId 设备 ID、toWxid 接收方 wxid、content 文本内容。联调第一站建议 toWxid 传 filehelper，发给文件传输助手，一分钟验证凭证是否配通。

通讯录同步同理，文档接口 POST /finder/v2/api/contacts/fetchContactsList，请求体只需 {"appId":"YOUR_APPID"}，可用于落库好友和群聊数据。

三、Spring Boot 接收 Webhook 回调

发消息跑通后，在控制台配置回调 URL，即可接收微信侧事件推送。用 Spring Boot 接收的可选写法（回调字段取自官方「回调信息速览」）：

import org.springframework.web.bind.annotation.*;
import java.util.Map;

@RestController
public class WxCallbackController {

    @PostMapping("/wtapi/callback")
    public String callback(@RequestBody Map<String, Object> body) {
        // 官方要求：3秒内返回响应，耗时业务请异步处理
        String typeName = (String) body.get("TypeName");
        if ("AddMsg".equals(typeName)) {
            Map<String, Object> data = (Map<String, Object>) body.get("Data");
            // 官方去重键：Appid + Data.NewMsgId
            // 文本消息 MsgType=1，正文在 Data.Content.string
            // FromUserName.string 以 @chatroom 结尾即群消息
            System.out.println(data);
        }
        return "";
    }
}

三条官方规则务必照做：3 秒内返回响应（接大模型等耗时逻辑必须异步）；按 Appid + Data.NewMsgId 做幂等去重，避免重推导致重复回复；新设备登录后 1-3 天朋友圈功能受限，相关任务错后排期。

至此“接收消息 → 业务处理 → API 回复”的 Java 微信机器人闭环已经成型，AI 客服、社群运营、CRM 对接都在此之上扩展。