📚 课程目录第3章 Android网络库选型与版本

第3章：Android网络库选型与版本——证书固定支持对比

证书固定（Certificate Pinning）的实现策略高度依赖底层网络库的版本和公开API。Android开发者在OkHttp、Retrofit、Volley、HttpURLConnection之间做出选择时，必须评估它们各自对证书固定的原生支持程度、版本门槛以及易用性。本章从实现原理出发，对比四类库的证书固定能力，并给出可运行的配置示例和常见陷阱。

3.1 各库证书固定支持一览

库名	底层实现	证书固定API	最低版本要求	固定粒度	稳定性
HttpURLConnection	Java标准库	自定义`HostnameVerifier` + `TrustManager`	API 1+	全域名全局	平台版本差异大
OkHttp	OkHttp 3.x/4.x	`CertificatePinner`内建类	3.0+	单域名或多域名模式	官方推荐，接口简洁
Retrofit	基于OkHttp	复用OkHttp的`CertificatePinner`	2.0+（配套OkHttp）	委托给OkHttp	与OkHttp版本兼容性强
Volley	自定义`HurlStack`或`HttpClientStack`	需要手动注入TrustManager	无原生API	全客户端	官方已不推荐

关键结论：OkHttp 提供了最内建、最可控的证书固定方式，是当前Android网络库中实现HTTPS固定的首选。Retrofit 由于依赖OkHttp，可直接继承其能力。Volley 和 HttpURLConnection 需要手写大量底层 SSL 代码，且容易因平台版本不同而行为不一致。

3.2 各库证书固定实现示例

3.2.1 OkHttp 3.x/4.x 证书固定（推荐方案）

通过 CertificatePinner 直接嵌入 OkHttpClient 构建，支持 SHA-256 公钥指纹。

OkHttpClient client = new OkHttpClient.Builder()
    .certificatePinner(new CertificatePinner.Builder()
        .add("api.example.com",
             "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
             "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")
        .build())
    .build();

版本兼容：OkHttp 3.0+ 支持 CertificatePinner，4.x（Kotlin主版本）保持API一致。建议使用 OkHttp 4.9+ 以获得最佳TLS支持。

3.2.2 Retrofit 证书固定（委托给 OkHttp）

Retrofit 自身不控制 SSL，只需在构建 Retrofit 实例时传入已经配置了 CertificatePinner 的 OkHttpClient。

OkHttpClient client = new OkHttpClient.Builder()
    .certificatePinner(new CertificatePinner.Builder()
        .add("api.example.com", "sha256/...")
        .build())
    .build();

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)  // 直接复用上文client
    .build();

3.2.3 HttpURLConnection 证书固定（手动实现）

需要创建自定义 TrustManager 并注入 SSLContext，代码冗长且容易遗漏异常处理。

TrustManager[] trustAllCerts = new TrustManager[] {
    new X509TrustManager() {
        @Override
        public void checkServerTrusted(X509Certificate[] chain, String authType)
                throws CertificateException {
            // 在这里校验固定指纹，否则放行（不安全示例，请勿直接复制）
        }
        // 其他方法略……
    }
};

SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(null, trustAllCerts, new SecureRandom());
HttpsURLConnection.setDefaultSSLSocketFactory(sslContext.getSocketFactory());

风险提示：HttpURLConnection 缺少原生固定API，极易写出“信任所有证书”的安全漏洞。手动实现 Pin 需要额外解析 X509Certificate 指纹，并自行维护指纹列表，调试难度大。

3.2.4 Volley 证书固定（通过 HurlStack 注入）

继承 HurlStack 并重写 createConnection()，将定制的 SSLSocketFactory 注入请求。过程繁琐且容易破坏 Volley 的连接池。

public class PinnedHurlStack extends HurlStack {
    @Override
    protected HttpURLConnection createConnection(URL url) throws IOException {
        HttpsURLConnection connection = (HttpsURLConnection) super.createConnection(url);
        // 手动设置证书固定逻辑，与 HttpURLConnection 方案类似
        return connection;
    }
}

RequestQueue queue = Volley.newRequestQueue(context, new PinnedHurlStack());

3.3 选型对比与决策树

下图以决策流程方式展示四类库如何在证书固定场景下进行技术选型：

3.4 版本门槛与迁移建议

OkHttp 3.x → 4.x：证书固定API无破坏性变更，CertificatePinner 类名与使用方式完全一致，只需替换包名为 okhttp3。
Retrofit 2.x：必须搭配 OkHttp 3.0+ 使用，若使用证书固定，请确保 OkHttp 版本 ≥ 3.0。
HttpURLConnection：Android 9 (API 28) 默认禁用了 TLS 1.0/1.1，证书固定实现需要额外处理回退逻辑。
Volley：官方已不再维护，Android 10+ 上 HttpClientStack 被废弃，只能走 HurlStack 路线。

性能与稳定性要点：OkHttp 的 CertificatePinner 在握手阶段拦截，不额外增加连接时间；而手动 TrustManager 方案需要在每次连接时解析证书链，可能产生毫秒级延迟。如果追求极致性能，应使用 OkHttp 内建固定。

3.5 常见错误与规避

场景	错误表现	根本原因	解决方案
指纹错误	javax.net.ssl.SSLPeerUnverifiedException	固定了错误公钥或证书链不完整	使用`openssl s_client`提取正确指纹，包含中间CA
证书过期未更新	连接突然全部失败	后端轮转证书但没有更新客户端固定列表	预置备用指纹，并建立监控/热更新机制
HttpURLConnection 信任所有	中间人攻击可成功	开发期为方便暂时信任所有，上线前未清理	严格审核上线前 TrustManager 代码
Retrofit/OkHttp 版本不匹配	编译期找不到 CertificatePinner 类	Retrofit 依赖的 OkHttp 版本过旧	检查 `build.gradle` 中的 transitive 依赖，显式指定版本

在线调试阶段，推荐启用 OkHttp 的日志拦截器以观察 SSL 握手细节：

HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
logging.setLevel(HttpLoggingInterceptor.Level.HEADERS);
OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(logging)
    .build();

日志中将打印 Server: 证书信息，可与本地固定指纹交叉验证。

3.6 本章小结

证书固定的实现可归纳为两条路径：内建支持路径（OkHttp/Retrofit）和手动注入路径（HttpURLConnection/Volley）。从代码量、版本兼容性、社区活跃度与维护成本综合评估，OkHttp 是当前 Android 生态中最优选择。Retrofit 项目可以零成本复用其证书固定能力。Volley 和 HttpURLConnection 仅在遗留项目中被迫使用，且必须加上严格的代码审查与测试覆盖。