Java 接入企业微信 API

先决定阻塞还是响应式，多数团队该选阻塞

WebClient 那套响应式栈在「一个线程扛住上万连接」的场景里是对的，但接一个外部 API 的调用量通常够不到那个门槛。换来的成本是实打实的：整条调用链都得跟着响应式，异常栈变得难读，团队里能改这段代码的人少一半，而线上出问题时你需要的恰恰是「谁都能看懂」。

wecomapi 这侧就是一次普通的 HTTPS + JSON 调用，客户端选型不受接口约束，只受你团队现有栈的约束 —— 所以别为了接一个 API 引入一套新范式。三个阻塞式选择的取舍：

• JDK 内置 HttpClient：零依赖，超时和连接复用都能配，缺点是拦截器这类扩展点要自己搭。只调几个接口时它最干净。
• OkHttp：连接池、超时、拦截器都成熟，配置项少而准，是独立服务里最省心的一个。注意它的异步调用还有一层每主机并发上限，同步调用不走那条路径 —— 用 execute() 时别去那儿找为什么并发上不去。
• Spring Boot 项目：直接用 RestClient，阻塞、同步、拦截器齐全。已经在用 RestTemplate 的不必为此重构，两者底层可以共用同一套请求工厂，先把参数配对比换 API 更值。

连接池：三个参数和一个必须做的动作

连接池的默认值是为「偶尔调一下」准备的。持续调用同一个域名时，每路由的最大连接数几乎总是第一个瓶颈，而它的表现不是报错，是延迟整体抬高 —— 多出来的请求安静地排在拿连接那一步。

• 总连接数和每路由连接数要一起调。你只调一个域名，等于所有请求都挤在同一个路由上，只把总数调大完全没用，这一点在 Apache 系客户端上尤其典型。
• 空闲连接的存活时间要短于链路上最短的那个空闲断开时间。留太久会撞上对端或中间设备的回收，表现为偶发的连接重置 —— 频率不高，但每次都要有人去查。
• 池大小和业务线程数要对齐。池小于线程数就是在排队，池远大于线程数就是白占文件描述符。顺序是先定线程数，再定池，不是反过来。

还有一个必须做的动作：响应体一定要读完并关闭。OkHttp 的 ResponseBody、Apache 的 CloseableHttpResponse 没关，连接就不会还回池里。这类泄漏的症状很有辨识度 —— 服务跑几个小时之后所有请求卡在获取连接上，重启就好，于是很容易被当成「内存问题」放着。用 try-with-resources，或者只用框架封装好的高阶方法，别手工管这件事。

超时要配三段，最难查的是漏掉的那一段

1. 1建连超时：TCP 加 TLS 握手的时间。这一段短一点没关系，连不上的目标等再久也连不上。
2. 2读取超时：等对端返回的时间。它必须小于调用你的那一方给你的超时预算，否则你还在等的时候，上游已经放弃了 —— 你后面做的所有事都是在给一个没人听的响应做准备。
3. 3从连接池获取连接的超时：不同库里叫法不同，Apache 系是单独一个参数，OkHttp 上由整次调用的总预算覆盖。这一段最容易漏，而它恰恰是池满时唯一的保护。

漏掉第三段的故障长这样：池被占满之后，业务线程全部堵在拿连接上，监控看是「服务活着但什么都不动」，接口不报错也不返回，线程 dump 里一片相同的栈。它和「对端变慢」的表象几乎一样，但处理方式完全相反 —— 前者要加池、要查泄漏，后者要降速。配上第三段超时，池满会变成明确的失败，至少你能第一眼看出是哪一类。

// 示意逻辑，精确字段、错误分类与端点以线上接口文档为准
OkHttpClient client = new OkHttpClient.Builder()
    // 只调一个域名，所有请求挤在同一个路由上，空闲数按并发估
    .connectionPool(new ConnectionPool(32, 60, TimeUnit.SECONDS))
    .connectTimeout(Duration.ofSeconds(3))    // 建连
    .readTimeout(Duration.ofSeconds(10))      // 等响应
    .callTimeout(Duration.ofSeconds(15))      // 总预算，含拿连接的等待
    .retryOnConnectionFailure(false)          // 重试只留一层，这层关掉
    .build();

Request req = new Request.Builder()
    .url("https://manager.wecomapi.com/message/sendText")
    .header("Authorization", "Bearer " + token.get())
    .post(RequestBody.create(payload, JSON))  // payload: {guid, toId, content}
    .build();

// body 必须读完并关闭，否则连接不还池，几小时后全部卡在拿连接
try (Response resp = client.newCall(req).execute()) {
    String raw = resp.body().string();
    // HTTP 层与业务层分开判，判定方式以文档为准
}

重试别配两层

Java 生态里重试太容易配了：客户端库自带一个、Spring Retry 一个、Resilience4j 一个、业务代码里再来个 for 循环。它们不会互相知道，只会相乘 —— 客户端 3 次乘业务 3 次是 9 次，而你排期时按 3 次算的。真出故障时，这个乘法会把一次抖动放大成一波自制的洪峰。

• 全站只在一层做重试，通常是你自己的调用封装那一层，客户端库自带的重试显式关掉。哪一层不重要，唯一一层才重要。
• 重试之前先分类，参数与权限类的错误重试多少次都是同样的结果。分类与退避的完整策略见站内讲频控与重试那篇，这里只说 Java 的落点：分类方法要独立成一个类，不要散在拦截器里。
• POST 参与重试的前提是带幂等键。这条在 Java 侧特别容易被跳过，因为库层的重试是你没写的代码，它不会提醒你请求非幂等。
• 用 Resilience4j 时，Retry 和 CircuitBreaker 的装配顺序要显式确认，别依赖默认。顺序不同，决定的是「一次重试里的每次尝试都被熔断器计数」还是「整组重试只算一次」，这两种行为在故障时差别很大。

线程池：别让回调消费和主动调用抢同一池

两类流量的失败模式完全不同。回调事件的消费是尖峰型的、允许延迟几秒；主动调用挂在业务同步链路上，延迟就是用户在等。共用一个线程池的结果是一波回调把业务调用饿死，而这件事只在业务高峰当天发生。

把 wecomapi 的出向调用和回调事件的消费放进两个命名清楚的线程池里，出问题时线程 dump 能直接告诉你是哪一侧在堵 —— 池起名这件事零成本，却是深夜排障时最有用的一个决定。另外三条：

• Spring 里 @Async 不指定执行器时用的是框架默认的那个，别依赖它。显式声明自己的 Executor 并给它起名，同时确认它不是每次都新建线程的那种。
• CompletableFuture 不传 Executor 时跑在公共的 ForkJoinPool 上，那是给 CPU 密集的短任务准备的、线程数按核数定。拿它做阻塞 I/O，会把 JVM 里所有用到这个池的地方一起拖住，包括一些你根本没意识到在用它的库。
• 用有界队列加明确的拒绝策略。无界队列不是「不会拒绝」，是把背压变成一次 OOM，而 OOM 发生时你已经没有机会优雅降级了。

关于虚拟线程：Java 21 之后阻塞写法确实能扩得很开，但它解决的是「线程不够用」，不解决「连接不够用」—— 瓶颈会立刻平移到连接池上，而且平移之后更难发现，因为线程数这个最直观的指标不再涨了。另外在早期版本上，synchronized 块里的阻塞会把载体线程钉住，涉及 I/O 的临界区改用 ReentrantLock 更稳。

反序列化与上线自检

别给响应建全量 DTO 再开严格模式。对端加一个字段，你的反序列化就抛异常，而这件事会发生在你完全没改代码的那一天，排查方向从一开始就是错的。Jackson 关掉未知字段报错，只映射你真的要用的字段，同时把原始响应体留一份进日志 —— 这一份留痕在对账和复盘时的价值，远超它占的那点存储。

1. 1连接池上限、业务线程数、并发闸三个数是对齐的，不是三个人各配各的。
2. 2三段超时都配了，读取超时短于上游给你的预算。
3. 3全链路只有一层重试，客户端库自带的已显式关闭，POST 重试带幂等键。
4. 4回调消费和主动调用用不同的、有名字的线程池，队列有界。
5. 5响应体在所有分支上都会被关闭，包括抛异常的那条分支 —— 这条用 try-with-resources 保证，不靠自觉。