自定义 HostnameVerifier：验证主机名，处理常见的主机名不匹配问题

说实话，主机名验证这个环节，很多开发者在做 SSL/TLS 通信时都容易忽略。大家往往把精力都放在证书链校验上，觉得证书没问题就万事大吉了。但你想过没有——如果证书是合法的，但发给了错误的域名呢？

我在项目中就遇到过这种情况。有一次对接第三方支付 SDK，对方提供的测试环境证书是自签的，域名还写错了。结果线上环境一直报错，排查了半天才发现是 HostnameVerifier 没处理好。嗯，从那以后我对这块就特别上心了。

为什么需要自定义 HostnameVerifier？

默认的 HostnameVerifier 实现，说白了就是检查你连接的服务器主机名，是否和证书里的 CN（Common Name）或 SAN（Subject Alternative Name）匹配。如果匹配不上，就会抛出 SSLException。

但现实情况往往没那么理想：

• 测试环境用的自签证书，域名和线上不一致
• CDN 节点返回的证书域名和请求域名对不上
• 内网 IP 直连场景，证书里根本没有 IP 地址
• 多域名共用证书，但默认校验逻辑太死板

这时候你就得自己写一个 HostnameVerifier，接管主机名验证的逻辑。

默认实现长什么样？

Android 默认用的是 OkHostnameVerifier，它实现了 RFC 2818 规范。我习惯先看看源码，了解默认行为再动手改。

// 默认的严格模式
HostnameVerifier defaultVerifier = HttpsURLConnection.getDefaultHostnameVerifier();
// 或者 OkHttp 里的
HostnameVerifier okHttpVerifier = OkHostnameVerifier.INSTANCE;

默认实现会做两件事：

1. 检查证书中的 SAN 扩展字段
2. 如果没有 SAN，就回退到 CN 字段

但注意了——从 Android 2.3 开始，如果 SAN 存在，CN 字段就不再被检查了。这是个容易踩的坑。

自定义 HostnameVerifier 的正确姿势

我自己写自定义验证器时，通常会遵循一个原则：只在可控范围内放宽校验。千万别直接返回 true，那是把安全大门彻底敞开了。

public class CustomHostnameVerifier implements HostnameVerifier {
    private final String allowedHost;

    public CustomHostnameVerifier(String allowedHost) {
        this.allowedHost = allowedHost;
    }

    @Override
    public boolean verify(String hostname, SSLSession session) {
        // 先走默认校验
        HostnameVerifier defaultVerifier = HttpsURLConnection.getDefaultHostnameVerifier();
        if (defaultVerifier.verify(hostname, session)) {
            return true;
        }

        // 如果默认校验失败，再检查是否是我们信任的特殊域名
        if (allowedHost != null && allowedHost.equalsIgnoreCase(hostname)) {
            return true;
        }

        // 或者支持通配符匹配
        if (allowedHost != null && hostname.endsWith(allowedHost)) {
            return true;
        }

        return false;
    }
}

// ❌ 极度危险的做法
HostnameVerifier dangerousVerifier = (hostname, session) -> true;
HttpsURLConnection.setDefaultHostnameVerifier(dangerousVerifier);

处理常见的主机名不匹配场景

我整理了几种实际开发中经常遇到的情况，以及对应的处理方案：

场景	问题描述	推荐方案
测试环境自签证书	证书域名是 test.example.com，但请求的是 dev.internal	在 Debug 模式下放行特定域名
CDN 多域名共用	证书 SAN 里没有当前请求的域名	维护一个白名单列表
IP 直连	证书里没有 IP 地址字段	使用 SNI 扩展，或自定义 IP 匹配逻辑
旧证书 CN 不匹配	证书 CN 写的是 www.example.com，但请求的是 api.example.com	检查 SAN 或更新证书

实战：带环境判断的 HostnameVerifier

我个人习惯在项目里封装一个带环境判断的验证器。这样 Debug 和 Release 走不同的逻辑，既方便调试又保证安全。

public class FlexibleHostnameVerifier implements HostnameVerifier {
    private final boolean isDebug;
    private final Set<String> debugHosts;

    public FlexibleHostnameVerifier(boolean isDebug, Set<String> debugHosts) {
        this.isDebug = isDebug;
        this.debugHosts = debugHosts != null ? debugHosts : new HashSet<>();
    }

    @Override
    public boolean verify(String hostname, SSLSession session) {
        // 生产环境走严格校验
        if (!isDebug) {
            return HttpsURLConnection.getDefaultHostnameVerifier()
                    .verify(hostname, session);
        }

        // 调试环境：先严格校验，再尝试白名单
        HostnameVerifier defaultVerifier = HttpsURLConnection.getDefaultHostnameVerifier();
        if (defaultVerifier.verify(hostname, session)) {
            return true;
        }

        // 检查是否在白名单中
        for (String allowed : debugHosts) {
            if (hostname.equalsIgnoreCase(allowed) || 
                hostname.endsWith("." + allowed)) {
                return true;
            }
        }

        return false;
    }
}

核心逻辑流程图

下面这张图展示了我推荐的主机名验证流程。说白了就是「先严后宽，分层过滤」的思路。

避坑指南

我曾经在维护一个老项目时，发现代码里直接用了 SSLSocketFactory 的 setHostnameVerifier() 方法，但传进去的验证器只检查了 CN 字段。结果证书换了新版本后，SAN 里没有旧 CN，服务直接就挂了。

这里有几个我踩过的坑，你一定要注意：

• 不要忽略 SAN 字段——现代证书基本都靠 SAN 做域名校验，CN 字段已经逐渐被废弃了
• 通配符匹配要谨慎——*.example.com 能匹配 a.example.com，但匹配不了 a.b.example.com
• IP 地址直连时——证书里通常没有 IP 的 SAN 记录，你需要自己实现 IP 匹配逻辑
• 多线程环境——HttpsURLConnection.setDefaultHostnameVerifier() 是全局设置，会影响所有连接。建议用 OkHttp 的实例级别配置

好了，关于自定义 HostnameVerifier 的内容就这些。说白了就是把握好「严格」和「灵活」之间的平衡点。你在实际项目中如果遇到什么奇葩的主机名不匹配问题，欢迎随时交流。