个微iPad协议对接场景下Java后端的自定义请求客户端开发与调试技巧

1. iPad协议通信特点与客户端需求

个微iPad协议通常基于私有WebSocket或长轮询通道，配合自定义二进制/JSON混合格式进行消息收发。与标准REST不同，其接口具有：

• 需维持设备会话（device_id + session_key）；
• 请求需携带动态签名（sign = MD5(device_id + timestamp + secret)）；
• 响应含业务码（如 0 成功、401 token过期、503 服务忙）；
• 调试依赖原始报文日志。

因此需封装专用 WeChatClient，统一处理连接、签名、重试、解包逻辑。

2. 定义协议请求/响应结构

package wlkankan.cn.wechat.ipad.dto;

import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.Map;

public class WeChatRequest {
    @JsonProperty("device_id")
    private String deviceId;
    
    private long timestamp;
    private String sign;
    private String cmd; // 如 "send_text", "get_contact"
    private Map<String, Object> payload;

    // 构造器、getter/setter 略
}

public class WeChatResponse {
    private int code;
    private String msg;
    private Map<String, Object> data;

    public boolean isSuccess() {
        return code == 0;
    }
}

3. 实现带签名的HTTP客户端

使用 OkHttp 封装请求流程：

package wlkankan.cn.wechat.ipad.client;

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import wlkankan.cn.wechat.ipad.dto.WeChatRequest;
import wlkankan.cn.wechat.ipad.dto.WeChatResponse;
import wlkankan.cn.wechat.ipad.config.WeChatConfig;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class WeChatHttpClient {

    private final OkHttpClient client;
    private final ObjectMapper objectMapper;
    private final WeChatConfig config;

    public WeChatHttpClient(WeChatConfig config) {
        this.config = config;
        this.client = new OkHttpClient.Builder()
            .connectTimeout(10, TimeUnit.SECONDS)
            .writeTimeout(10, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .build();
        this.objectMapper = new ObjectMapper();
    }

    public WeChatResponse send(String cmd, Map<String, Object> payload) throws Exception {
        long ts = System.currentTimeMillis() / 1000L;
        String sign = generateSign(config.getDeviceId(), ts, config.getSecret());

        WeChatRequest req = new WeChatRequest();
        req.setDeviceId(config.getDeviceId());
        req.setTimestamp(ts);
        req.setSign(sign);
        req.setCmd(cmd);
        req.setPayload(payload);

        String jsonBody = objectMapper.writeValueAsString(req);
        Request request = new Request.Builder()
            .url(config.getBaseUrl() + "/api/v1/dispatch")
            .post(RequestBody.create(jsonBody, MediaType.get("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new RuntimeException("HTTP " + response.code());
            }
            String respBody = response.body().string();
            return objectMapper.readValue(respBody, WeChatResponse.class);
        }
    }

    private String generateSign(String deviceId, long timestamp, String secret) throws Exception {
        String raw = deviceId + timestamp + secret;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = mac.doFinal(raw.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(hash);
    }
}

4. 自动 Token 刷新机制

当返回 code=401 时自动重连并重试：

public WeChatResponse sendWithRetry(String cmd, Map<String, Object> payload, int maxRetries) throws Exception {
    for (int i = 0; i <= maxRetries; i++) {
        WeChatResponse resp = send(cmd, payload);
        if (resp.getCode() == 401 && i < maxRetries) {
            // 触发设备重连
            reconnectDevice();
            Thread.sleep(1000);
            continue;
        }
        return resp;
    }
    throw new RuntimeException("Max retries exceeded");
}

private void reconnectDevice() throws Exception {
    Map<String, Object> authPayload = Map.of(
        "secret", config.getSecret(),
        "version", "3.9.8"
    );
    WeChatResponse resp = send("device_auth", authPayload);
    if (!resp.isSuccess()) {
        throw new IllegalStateException("Reconnect failed: " + resp.getMsg());
    }
    // 更新本地 session（如有）
}

5. 调试模式：记录原始请求/响应

通过 Interceptor 注入日志：

public WeChatHttpClient(WeChatConfig config) {
    // ...
    if (config.isDebugMode()) {
        HttpLoggingInterceptor logging = new HttpLoggingInterceptor(
            message -> LoggerFactory.getLogger(WeChatHttpClient.class).debug("[iPad协议] {}", message)
        );
        logging.setLevel(HttpLoggingInterceptor.Level.BODY);
        this.client = new OkHttpClient.Builder()
            .addInterceptor(logging)
            // ...其他配置
            .build();
    }
}

同时对敏感字段脱敏：

// 在 LoggingInterceptor 内部或单独 Appender 中处理
public static String maskJson(String json) {
    return json.replaceAll("(\"secret\"\\s*:\\s*\")[^\"]+\"", "$1****\"");
}

6. 单元测试模拟协议交互

使用 MockWebServer 验证客户端行为：

@Test
void testSendTextSuccess() throws Exception {
    MockWebServer server = new MockWebServer();
    server.enqueue(new MockResponse()
        .setBody("{\"code\":0,\"msg\":\"ok\",\"data\":{\"msg_id\":\"123456\"}}")
        .setHeader("Content-Type", "application/json"));

    WeChatConfig config = new WeChatConfig();
    config.setBaseUrl(server.url("/").toString());
    config.setDeviceId("DEV_001");
    config.setSecret("MY_SECRET");
    config.setDebugMode(false);

    WeChatHttpClient client = new WeChatHttpClient(config);
    WeChatResponse resp = client.send("send_text", Map.of("to", "wxid_xxx", "content", "Hello"));

    assertTrue(resp.isSuccess());
    assertEquals("123456", resp.getData().get("msg_id"));

    RecordedRequest request = server.takeRequest();
    assertThat(request.getBody().readUtf8()).contains("send_text");
    server.shutdown();
}

7. 异步回调处理与事件分发

对于服务端推送（如新消息到达），需启动独立监听线程：

@Component
public class WeChatEventDispatcher {

    private final WebSocketClient wsClient;
    private final ApplicationEventPublisher eventPublisher;

    @PostConstruct
    public void startListening() {
        wsClient.connect(config.getWsUrl(), new WebSocketListener() {
            @Override
            public void onMessage(WebSocket webSocket, String text) {
                try {
                    WeChatEvent event = objectMapper.readValue(text, WeChatEvent.class);
                    eventPublisher.publishEvent(new WeChatMessageReceivedEvent(event));
                } catch (Exception e) {
                    log.error("解析事件失败: {}", text, e);
                }
            }
        });
    }
}

通过自定义 HTTP/WebSocket 客户端、签名生成、自动重试、调试日志与事件分发，可高效、安全地对接个微 iPad 协议，并在开发阶段快速定位通信问题。