做后端这些年对接第三方 HTTP 接口算是最常见也最磨人的活。前阵子我在一个聚合支付类的对接项目里实在忍不了了花了两个晚上基于 JDK 自带的 HttpClient 封装了一个叫 JavaRestClient 的轻量级 REST 调用工具。为什么非要自己造轮子因为要把支付、物流、会员、发票几套外部系统的调用方式统一起来又要控制超时、重试、日志这些框架没有替你做完的细节。这篇文章就把这个工具从设计到踩坑的完整过程记录下来适合正在纠结 REST 客户端选型或者想自己封装一套 HTTP 调用工具的开发者参考。1. 为什么还要折腾一个 JavaRestClient而不是直接上框架1.1 真实项目的接口调用场景往往比框架 Demo 复杂很多人在技术选型时会陷入一个误区一看到 REST Client就想到 RestTemplate、WebClient、Feign 全家桶。但真实项目里尤其是中后台系统往往不是选一个框架就能搞定的。我当时面对的情况是这样的同一个 Java 17 服务里需要对接四套外部系统。支付系统给的示例是 RestTemplate物流系统的 SDK 内部用了 OkHttp会员系统提供了一个自己封装的 HttpURLConnection 工具类发票系统干脆只给了一份接口文档让我自己用 HttpClient 写。更麻烦的是每个系统对超时时间、重试策略的要求都不一样日志格式也五花八门。如果直接引一个新框架比如把 Feign 引入进来最大的问题是它是面向微服务调用的强依赖 Spring Cloud 体系对我们这种单体服务来说太重了。而且外部接口的鉴权、签名、幂等等逻辑Feign 也不会帮你做。真正的需求是我想要一个统一的地方把所有第三方 HTTP 调用都收拢起来提供一致的超时配置、重试机制、日志记录和异常包装。这就是我决定手写 JavaRestClient 的出发点。1.2 JDK 自带 HttpClient 到底行不行在 Java 11 之前JDK 自带的 HTTP 客户端一直是个老大难。HttpURLConnection 的 API 设计老、不支持 HTTP/2、连接管理也弱所以大家宁可用第三方库。但 Java 11 引入的java.net.http.HttpClient其实已经足够成熟了它支持 HTTP/1.1 和 HTTP/2、支持同步和异步发送、内置 WebSocket底层默认使用 NIO在高并发下表现并不差。不过JDK 自带的 HttpClient 仍然是一个偏底层的引擎它不会帮你做这些事情不会自动把 JSON 响应体反序列化成 Java 对象不会统一处理超时后的重试逻辑不会把 HTTP 状态码和业务异常做区分不会主动打印请求日志。所以我的做法是把它当作发动机在它上面包一层更贴近业务的使用壳子。这是很典型的依赖 JDK 原生能力 自研薄封装的思路既不引入重量级依赖又能保证可维护性。1.3 主流 REST 客户端方案我拿什么标准去对比为了说服团队里坚持用 RestTemplate 和 OkHttp 的同事我做了一张选型对比表核心关注四件事依赖体积、线程模型、连接池管理、和 Spring 生态的耦合度。客户端方案依赖线程模型连接池管理典型适用场景java.net.http.HttpClient无JDK 11NIO 异步可自定义 Executor自带连接复用但配置项少无第三方依赖的标准化封装RestTemplatespring-web每个请求一个线程同步阻塞默认基于 SimpleClientHttpRequestFactory不推荐高并发池化Spring MVC 老项目WebClientspring-webflux响应式少量线程支撑高并发Reactor Netty 自带成熟连接池全链路异步、响应式架构OkHttpokhttp3同步/异步双模式自带连接池参数丰富移动端、服务端通用性能稳定OpenFeignspring-cloud-openfeign同步通过接口声明式调用取决于底层 HTTP ClientSpring Cloud 微服务间调用对比完之后结论很清晰如果团队还在用 Java 8我会建议直接用 OkHttp如果项目已经在 Spring Cloud 体系里那 Feign 是顺理成章的选项。可我们已经是 Java 17 的单体服务既要统一封装又不想被某套框架套住JDK 自带 HttpClient 反而是最合适的地基。JavaRestClient 的设计目标就是在不引入额外 HTTP 依赖的前提下把超时、重试、日志、泛型反序列化这些能力做进去。2. 核心 API 设计先定清楚这个工具要解决哪些问题2.1 需求边界不重复造轮子封装一个 HTTP 客户端最忌讳的是贪多求全。我一开始就给自己画了条线JavaRestClient 只负责三件事——构造请求、发送请求、解析响应。服务发现不做负载均衡不做熔断降级不做协议解析不做。这些能力要么交给上层业务要么交给基础设施比如 Nacos 做服务发现、Sentinel 做熔断、网关做统一鉴权。边界清晰的直接好处是整个工具类只有十几个文件单测容易写后续替换底层实现也不会牵一发动全身。比如将来如果团队决定全面转向 WebFlux我可以保留同样的 API 形态把内部实现替换成 WebClient上层调用代码完全不用动。2.2 对外暴露的接口长什么样API 设计我参考了 OkHttp 的 Builder 模式同时加入了 Spring 开发者熟悉的链式调用。一个典型的用法长这样JavaRestClient client JavaRestClient.builder() .baseUrl(https://api.example.com) .connectTimeout(Duration.ofSeconds(3)) .requestTimeout(Duration.ofSeconds(8)) .retryTimes(2) .build(); // 同步 GET返回带泛型的业务对象 ResultUser user client.get(/user/info) .queryParam(id, 123) .header(Authorization, Bearer xxx) .execute(new TypeReferenceResultUser() {}); // 异步 POST提交 JSON 请求体 CompletableFutureResultOrder future client.post(/order/create) .body(orderJson) .executeAsync(new TypeReferenceResultOrder() {});这里有两个核心设计点。第一个是TypeReference它用来解决 Java 泛型擦除问题。如果不传这个参数客户端只能反序列化成Result.class里面的data字段拿到的就是一堆LinkedHashMap用起来非常难受。第二个是每次调用返回独立的RequestBuilder可以在一次请求内灵活设置 query 参数、headers、body同时又不会污染全局配置。2.3 同步发送与异步发送的内部衔接很多人在设计时会写两条独立的方法链一条走client.send()一条走client.sendAsync()结果内部逻辑维护了两套。这里我采用了一个更聪明的做法同步方法内部其实也走异步然后通过join()阻塞获取结果。public T T execute(RequestSpec spec, TypeReferenceT type) { try { return executeAsync(spec, type).join(); } catch (CompletionException e) { throw unwrapException(e); } }这样设计的核心收益是底层只有一条发送链路同步只是异步的阻塞包装。不管调用方是普通接口还是异步任务都能共用同一套超时、重试和日志逻辑。但这里有个坑必须提醒join()抛出的异常都被包在CompletionException里不能直接反射出业务异常所以unwrapException要把真正的RestClientException或HttpTimeoutException解出来否则上层 catch 不到正确类型。3. 具体实现中绕不开的几个关键点3.1 连接配置与连接池复用JDK 自带 HttpClient 的连接池是内置的但它提供给你的可调旋钮非常少。最要紧的是自定义Executor因为异步发送任务默认跑在一个 cached 线程池上高并发时线程数会炸。我封装时提供了一个默认的线程池配置private static ExecutorService createExecutor() { return new ThreadPoolExecutor( 8, 16, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue(1000), new ThreadFactoryBuilder() .setNameFormat(rest-client-%d) .build(), new ThreadPoolExecutor.CallerRunsPolicy() ); }为什么核心线程数设成 8、最大 16因为 HTTP 调用是 IO 密集型操作线程数不需要跟 CPU 核数走反而要控制住避免大量请求同时进来时创建过多线程造成上下文切换开销。有界队列设成 1000是防止任务无限堆积导致内存溢出。拒绝策略用CallerRunsPolicy意思是队列满了就让调用线程自己执行这样会自动增加上游响应时间起到天然背压作用而不是直接抛异常丢掉任务。至于连接池本身如果你只用 JDK HttpClient它的复用机制不透明我建议在工具里留一个HttpClientProvider接口把底层真正干活的客户端藏起来。需要更强连接池控制的时候内部换成 OkHttp 或 Apache HttpClient 都可以。实际上我在后期排查超时问题时就是通过这个接缝把底层切成了 OkHttp下文会详细讲。3.2 超时控制与重试机制JVM 的网络超时其实分三个层面建立连接超时、读取响应超时、整体请求超时。JDK 的HttpClient.Builder.connectTimeout只控制建立连接HttpRequest.timeout()控制整体请求时间它覆盖了连接、发送、等待响应的全过程。所以我在封装里暴露的是requestTimeout()方法映射到HttpRequest.timeout()。重试机制是整个封装里最容易出问题的地方。我的原则很简单只有满足幂等语义的请求才重试。GET、PUT、DELETE 默认是幂等的可以重试POST 请求要谨慎除非上游接口做了幂等键校验否则重复提交可能产生重复订单。判断是否重试的代码可以抽象成接口public boolean shouldRetry(int statusCode, Throwable ex) { if (ex instanceof HttpTimeoutException) return true; if (ex instanceof IOException) return true; return statusCode 500; }重试间隔不能是固定值。如果所有客户端都在超时后 1 秒重试那高并发下等于给下游再制造一波流量高峰。我采用指数退避加随机抖动private Duration nextRetryDelay(int attempt) { long base 200L * (1L Math.min(attempt - 1, 5)); long jitter ThreadLocalRandom.current().nextLong(0, base / 2); return Duration.ofMillis(base jitter); }第一次重试大概 200ms 到 300ms 后第二次 500ms 到 600ms 后最多到 6.4 秒封顶避免长时间挂起。3.3 JSON 序列化与泛型反序列化几乎所有 REST 接口返回的都是 JSON所以 JavaRestClient 内部集成了 JacksonObjectMapper但刻意做了 SPI 解耦让别人可以替换成 Gson 或 Fastjson。做泛型反序列化时有一个关键操作public T T fromBody(String body, TypeReferenceT type) throws IOException { JavaType javaType objectMapper.getTypeFactory().constructType(type.getType()); return objectMapper.readValue(body, javaType); }如果直接用objectMapper.readValue(body, type.getClass())是拿不到ResultUser里的User真实类型的这就是为什么必须用TypeReference传入完整泛型信息。ObjectMapper的配置也影响兼容性。我给团队定的默认配置大致是ObjectMapper mapper new ObjectMapper() .registerModule(new JavaTimeModule()) .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false) .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);第一行解决LocalDateTime反序列化问题。第三行很关键很多外部接口会多返回几个字段如果默认行为是失败那字段稍微一变客户端就崩了。但注意这也会掩盖接口结构调整的问题所以我建议在日志里记录一下原始响应体方便排查。3.4 请求日志与异常封装统一的日志是封装 HTTP 客户端最大的价值之一。我在 JavaRestClient 里规定DEBUG 级别打印完整请求头、请求体、响应体、耗时INFO 级别只打印 method、URL、状态码、耗时WARN 级别记录重试事件和超时事件。日志格式尽量统一方便接入 ELK 或 Loki。比如[rest-client] methodGET url/user/info cost235ms status200异常层面我定义了一个RestClientException继承 RuntimeException把状态码、响应体、耗时都带进去方便上层打印。public class RestClientException extends RuntimeException { private final int statusCode; private final String responseBody; private final long costMillis; }这样业务方 catch 到异常后不用再从一大堆字符串里去解析状态码。4. 实战排障一次接口调用超时背后的完整排查链路4.1 现象高峰期偶发超时贴一张我们当时的事故现场每天上午 10 点到 12 点物流查询接口会偶发性抛出HttpTimeoutException概率大约 2% 到 3%。但上游物流服务商反馈他们的监控显示所有请求都正常返回了没有看到超时。也就是说请求已经打到对方服务器对方也处理完了但我们的客户端在等待响应时超时了。这种两端对不上账的现场往往不是服务端处理慢而是客户端侧的连接管理出了问题。4.2 排查第一步看应用日志和线程 dump我先在日志里加了每个环节的时间戳发现耗时集中在校验签名之前也就是纯粹卡在发起 HTTP 访问到收到响应这个中间态。接下来用jstack抓了超时时刻的线程栈发现大量业务线程 BLOCKED 在java.net.http.HttpClient内部的锁上而不是 RUNNABLE。这非常关键。如果线程是 RUNNABLE说明它一直在等网络 IO如果是 BLOCKED说明它在等某个共享资源比如连接池里的连接。再结合线程数曲线明显可以看出高峰期线程数量猛增但活跃线程的实际处理效率却在下降。4.3 排查第二步连接池配置不当是真凶根因很快浮出水面我封装的第一版 JavaRestClient 用的是 JDK 自带 HttpClient但没有自定义 Executor。JDK 默认的异步执行器是 cached 线程池会在高并发请求下不断创建线程且底层连接池的复用表现也不够稳定。更致命的是我之前给每个请求都设置了较短的requestTimeout()一旦某个接口响应稍慢大量请求一起超时触发重试新线程和新连接一起拥进来直接把连接池打满。解决办法是分层做的自定义有界线程池控制并发上限。引入 OkHttp 作为底层HttpClientProvider利用它的ConnectionPool做更精细的连接管理比如设置maxIdleConnections(20)和keepAliveDuration。把重试策略进一步收紧只对 GET 请求重试而且重试次数从 2 次降到 1 次避免放大流量。替换后同样的高峰期客户端超时率降到了 0.1% 以下。这里我要强调一句JDK 自带 HttpClient 并没有那么差问题出在没有配置合理的线程池和连接策略上而不是它本身不能用。4.4 解决后的一些加固措施上线稳定后我又补了几个监控项在 JavaRestClient 里暴露活跃线程数、队列积压数、最近一分钟请求量给所有请求设置独立的 read timeout而不是只依赖整体超时在 WARN 日志里输出连接池的活跃连接数方便下次快速定位对下游服务做分级配置比如核心支付接口可以超时 3 秒重试 2 次边缘查询接口只超时 1 秒不重试。这些措施不属于什么高深技术但真实排障时非常管用。5. 把这些能力放进 Spring 项目里的正确姿势5.1 注册成单例 Bean 还是每次 newJavaRestClient 内部的 HttpClient 以及线程池都是重量级资源如果每个地方都new JavaRestClient()等于每个调用方都在创建连接池和线程池系统早晚被自己拖垮。因此在 Spring 项目里一定要注册成单例 Bean。Configuration public class RestClientConfig { Bean public JavaRestClient javaRestClient(RestClientProperties props) { return JavaRestClient.builder() .baseUrl(props.getBaseUrl()) .connectTimeout(props.getConnectTimeout()) .requestTimeout(props.getRequestTimeout()) .retryTimes(props.getRetryTimes()) .build(); } }这样所有业务模块注入同一个 JavaRestClient内部连接池和线程池天然共享。需要注意的是一旦注册为单例它的生命周期由 Spring 容器管理项目关闭时最好把 ThreadPoolExecutor 的shutdown()也放到PreDestroy里避免线程没释放。5.2 与 RestTemplate 共存时的取舍很多老项目里已经有 RestTemplate 在用了直接一刀切替换不现实也没必要。我建议的做法是新接口用 JavaRestClient老接口逐步迁。共存阶段最容易出现的问题是连接数失控。因为 RestTemplate 默认的SimpleClientHttpRequestFactory每次请求都会新建连接而 JavaRestClient 内部有自己的连接池两边加在一起导致网关或者下游服务看到的源端口特别多可能会触发防火墙连接数限制。如果老接口确实需要保留至少给 RestTemplate 配置一个连接池实现比如HttpComponentsClientHttpRequestFactory避免并发高时创建大量 TIME_WAIT 连接。5.3 从 JavaRestClient 迁移到 WebClient 的平滑路径如果未来项目要转向 WebFluxJavaRestClient 的异步 API 能降低迁移痛苦。因为它返回的是CompletableFuture而 WebFlux 的Mono可以直接从CompletableFuture转换MonoResultUser userMono Mono.fromFuture( restClient.get(/user/info) .executeAsync(new TypeReferenceResultUser() {}) );这样业务层可以先按照同步方式调用等整个链路切换成响应式时只需要在调用入口包一层Mono.fromFuture不用把每个接口调用点都改一遍。要我说这是自研 API 设计时最值得的一笔投资。6. 最后分享几个我实际使用中的调试技巧6.1 用本地 Mock 服务快速验证客户端对接第三方接口之前我习惯先在本地搭一个 Mock 服务把响应内容、响应延迟、状态码都预先配好验证 JavaRestClient 的超时和重试是否正常。最快速的办法是用 JDK 自带的com.sun.net.httpserver.HttpServerHttpServer server HttpServer.create(new InetSocketAddress(8081), 0); server.createContext(/api/test, exchange - { Thread.sleep(500); byte[] bytes {\code\:0,\data\:\ok\}.getBytes(StandardCharsets.UTF_8); exchange.sendResponseHeaders(200, bytes.length); exchange.getResponseBody().write(bytes); exchange.close(); }); server.start();这段代码足够用来验证客户端行为比启动 Spring Boot 再写 Controller 轻量得多。另外也可以配合 WireMock 做更复杂的匹配规则但日常调试我个人觉得 HttpServer 就够了。6.2 低成本的 RPS 压测方法没有专业压测平台的时候我常用一种很简单的穷人压测用虚拟线程或者固定线程池同时发几百个请求配合CountDownLatch看整体耗时和异常数量。ListCompletableFutureResultUser futures new ArrayList(); for (int i 0; i 500; i) { futures.add(restClient.get(/user/info) .queryParam(id, i) .executeAsync(new TypeReferenceResultUser() {})); } CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();这个方法能快速暴露连接池不足、线程数配置不合理、响应时间突刺等问题。不过建议只压本地 Mock 服务不要拿这个循环直接压测试环境的真实下游否则容易把别人环境搞挂。6.3 日志分级与脱敏最后提一个非常现实的细节HTTP 客户端日志里最容易出现敏感信息。我之前就见过有人把Authorization头打到日志里然后日志文件还被同步到开发服务器相当于令牌直接裸奔。我现在的约定是在 DEBUG 日志里也脱敏所有 header 通过MaskUtils.maskSensitive()过滤Authorization、X-Api-Key、password、token这些字段统一显示成前三位 星号响应体如果太大超过 2KB 就截断防内存浪费也防敏感数据刷屏。脱敏函数很直接就不贴代码了关键是你要把这个习惯焊在封装层而不是指望每个业务工程师自己记得脱敏。这套 JavaRestClient 工具从最初的一个疑问到中间踩坑再到线上稳定运行前后也就一周时间。如果非要说有什么经验值得分享那就是REST 客户端选型没有一个万能解JDK 自带 HttpClient、RestTemplate、WebClient、OkHttp 各有各的位置关键是根据自己的线程模型、连接池边界和团队维护成本去做取舍。自己封装不丢人把为什么这么设计、边界设在哪里想清楚反而比盲目引一个全家桶框架要踏实得多。
