第3章：埋点请求的专用OkHttpClient——独立连接池与超时配置、拦截器定制、日志级别分离

3.1 为什么需要独立的埋点 OkHttpClient

默认的 Retrofit OkHttpClient 实例通常与业务接口共享连接池、超时和拦截器。埋点请求具有 高频、轻量、容忍失败 的特点，若与业务请求混用会导致：

• 连接池污染：业务长连接占用连接数，埋点短连接可能排队超时。
• 超时冲突：业务超时时间通常 30s+，埋点应在 5s 内完成否则丢弃。
• 拦截器冗余：业务 Header 添加、重试策略可能干扰埋点数据。
• 日志噪音：业务日志与埋点日志混在一起，难以排查埋点异常。

3.2 独立连接池与超时配置

OkHttpClient 的 ConnectionPool 默认每 5 分钟清理空闲连接。埋点请求建议缩小空闲存活时间并控制最大连接数，避免空闲连接占用内存。

推荐配置参数对比

代码实现：独立 OkHttpClient 构建

// TrackingClientFactory.kt
object TrackingClientFactory {
    private const val TRACKING_CONNECT_TIMEOUT = 5L
    private const val TRACKING_READ_TIMEOUT = 5L
    private const val TRACKING_WRITE_TIMEOUT = 3L
    private const val MAX_IDLE_CONNECTIONS = 2
    private const val KEEP_ALIVE_DURATION_SECONDS = 30L

    fun create(): OkHttpClient {
        return OkHttpClient.Builder()
            .connectTimeout(TRACKING_CONNECT_TIMEOUT, TimeUnit.SECONDS)
            .readTimeout(TRACKING_READ_TIMEOUT, TimeUnit.SECONDS)
            .writeTimeout(TRACKING_WRITE_TIMEOUT, TimeUnit.SECONDS)
            .connectionPool(
                ConnectionPool(
                    MAX_IDLE_CONNECTIONS,
                    KEEP_ALIVE_DURATION_SECONDS,
                    TimeUnit.SECONDS
                )
            )
            .addInterceptor(TrackingHeaderInterceptor())    // 自定义埋点专用拦截器
            .addInterceptor(TrackingLoggingInterceptor())   // 日志级别可控
            .build()
    }
}

3.3 拦截器定制：埋点专用 Header 与安全策略

埋点请求需要携带固定的 Content-Type: application/json、设备标识、时间戳等，同时应滤除业务鉴权 。

// TrackingHeaderInterceptor.kt
class TrackingHeaderInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val original = chain.request()
        val newRequest = original.newBuilder()
            .header("Content-Type", "application/json")
            .header("X-Tracking-SDK-Version", BuildConfig.VERSION_NAME)
            .header("X-Device-ID", DeviceUtils.getDeviceId())
            .header("X-Timestamp", System.currentTimeMillis().toString())
            // 明确不携带业务 Authorization
            .removeHeader("Authorization")
            .build()
        return chain.proceed(newRequest)
    }
}

3.4 日志级别分离：只输出埋点异常

常规 HttpLoggingInterceptor 会打印所有请求/响应体，在线上会产生大量日志。埋点客户端应自定义日志拦截器，根据日志级别决定输出等级。

实现思路

• 使用 BuildConfig.DEBUG 控制：debug 环境打印 BODY，release 环境仅打印 NONE 或 HEADERS。
• 为埋点日志单独定义 Tag：Tracking-OKHttp，便于 logcat 过滤。
• 异常埋点请求（非 2xx 或 IOException）即使 release 也打印错误摘要。

// TrackingLoggingInterceptor.kt
class TrackingLoggingInterceptor : Interceptor {
    private val logger = Logger.getLogger("Tracking-OKHttp")

    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        val startNs = System.nanoTime()
        var response: Response? = null
        var exception: Exception? = null
        try {
            response = chain.proceed(request)
        } catch (e: Exception) {
            exception = e
        } finally {
            val elapsed = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startNs)
            if (BuildConfig.DEBUG) {
                // debug 模式打印完整请求
                logger.fine("${request.method} ${request.url} → ${response?.code ?: "FAIL"} (${elapsed}ms)")
                if (response != null) {
                    logger.fine("Response body: ${response.body?.string()}")
                }
            } else if (response != null && response.code >= 400) {
                // release 只打印错误请求的 HTTP 状态码
                logger.warning("Tracking request failed: ${response.code} ${response.message} (${elapsed}ms)")
            } else if (exception != null) {
                logger.warning("Tracking request error: ${exception.message}")
            }
        }
        return response ?: throw exception!!
    }
}

3.5 整体架构流程

下图展示了埋点专用 OkHttpClient 的构造与请求链路：

3.6 调试与验证

配置独立 Client 后，可通过以下方式验证隔离效果：

• 在 logcat 中使用 adb logcat -s Tracking-OKHttp 过滤仅埋点日志。
• 在 Stetho/Charles 中观察请求 Header：埋点请求不应携带 Authorization。
• 模拟网络延迟：连接超时应在 5s 内抛出 SocketTimeoutException，不影响业务请求。

3.7 常见错误与避坑

3.8 性能与稳定性优化要点

1. 复用 OkHttpClient 实例：使用单例（如 TrackingClientFactory），避免每次埋点都新建 Client，浪费线程和 socket。
2. 减少 DNS 解析：若埋点服务域名唯一，可考虑使用 .dns() 预解析或直接使用 IP 直连。
3. 控制并发数：通过 dispatcher.maxRequests = 10 限制同时最大请求数，防止突发流量打满线程池。
4. 失败降级：遇到 IOException 时不应重试（埋点数据时效性弱），直接丢弃或写入本地 DB。