如何处理Vert.x WebClient发起HTTPS请求时的SSL连接错误

我看到你在用Vert.x WebClient发送HTTPS请求时碰到了SSL连接问题，咱们一步步来解决这个事儿。首先得从错误捕获入手，然后再聊聊更安全的SSL配置——毕竟setTrustAll(true)只能用来临时测试，生产环境这么搞风险太高了。

1. 先把SSL异常捕获处理起来 #

你的代码用了CompletableFuture，那可以通过Vert.x请求的回调来精准捕获SSL相关的错误，比如握手失败、证书验证不通过这些。给你改改请求部分的代码，加上错误处理逻辑：

webClient.get(port, host, api)
    .send()
    .onSuccess(response -> {
        // 这里处理成功响应，把结果解析后传给CompletableFuture
        completableFuture.complete(parseResponse(response)); // 假设你有parseResponse方法转成T类型
    })
    .onFailure(throwable -> {
        // 针对性处理不同的SSL错误
        if (throwable instanceof SSLHandshakeException) {
            completableFuture.completeExceptionally(
                new RuntimeException("SSL握手失败：证书不被信任或主机名匹配错误", throwable)
            );
        } else if (throwable instanceof ConnectException) {
            completableFuture.completeExceptionally(
                new RuntimeException("无法建立SSL连接：主机不可达或端口错误", throwable)
            );
        } else if (throwable instanceof SSLException) {
            completableFuture.completeExceptionally(
                new RuntimeException("SSL连接异常", throwable)
            );
        } else {
            // 其他通用错误
            completableFuture.completeExceptionally(new RuntimeException("请求失败", throwable));
        }
    });

2. 换掉不安全的setTrustAll(true)，配置合法的SSL信任 #

生产环境绝对不能用setTrustAll(true)，这等于跳过所有证书验证，中间人随便就能截你的请求。根据你的场景选对应的配置方式：

场景A：对接用自定义CA签发证书的服务 #

如果你的目标服务用的是自己公司或团队签发的CA证书，把CA证书文件（比如my-ca.pem）放到项目资源里，然后加载到WebClient的信任库：

// 加载本地CA证书文件
Buffer caCertBuffer = vertx.fileSystem().readFileBlocking("classpath:my-ca.pem");

// 初始化KeyStore并添加CA证书
KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());
keyStore.load(null, null);
CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
X509Certificate caCert = (X509Certificate) certFactory.generateCertificate(
    new ByteArrayInputStream(caCertBuffer.getBytes())
);
keyStore.setCertificateEntry("custom-ca", caCert);

// 创建TrustManagerFactory
TrustManagerFactory trustManagerFactory = TrustManagerFactory.getInstance(
    TrustManagerFactory.getDefaultAlgorithm()
);
trustManagerFactory.init(keyStore);

// 配置WebClientOptions
WebClientOptions webClientOptions = new WebClientOptions()
    .setSsl(true)
    .setVerifyHost(true) // 强制验证主机名，防止中间人攻击
    .setTrustManagers(trustManagerFactory.getTrustManagers());

场景B：对接用公共CA签发证书的服务 #

如果目标服务用的是Let's Encrypt这类公共信任的CA证书，那简单了——直接删掉setTrustAll(true)就行，Vert.x会自动使用系统默认的信任库：

WebClientOptions webClientOptions = new WebClientOptions()
    .setSsl(true)
    .setVerifyHost(true); // 这个是默认值，也可以省略，但显式写出来更清晰

3. 常见SSL错误的排查小技巧 #

• SSLHandshakeException: No subject alternative names present：证书里的主机名和你请求的host不匹配，要么检查证书的SAN字段，要么确认请求的host是不是写错了。
• SSLHandshakeException: PKIX path building failed：客户端不信任服务器的证书，得把服务器的CA证书加到信任库（参考场景A）。
• ConnectException: Connection refused：先确认服务器的HTTPS端口是不是对的，防火墙有没有开放，主机能不能正常访问。

内容的提问来源于stack exchange，提问作者TiantianHe