第2章 Retrofit核心机制回顾：OkHttp拦截器链、CallAdapter与Converter、异步与同步调用差异

在埋点异常处理场景中，Retrofit 的三个核心机制——OkHttp拦截器链、CallAdapter 与 Converter、异步与同步调用差异——是埋点数据采集、异常拦截与线程安全的基石。只有深入理解这三者的协作关系，才能在自定义埋点组件时准确选择切入点，避免误拦截、数据丢失或线程错乱。

2.1 OkHttp拦截器链：埋点数据的天然采集点

Retrofit 底层委托 OkHttp 执行网络请求，OkHttp 的拦截器链（Interceptor Chain）是请求/响应流经的管道。每个拦截器可以无侵入地读取、修改甚至终止请求与响应，这一特性使其成为埋点数据采集的首选位置。

以下是一个用于埋点耗时与状态码的应用拦截器示例：

class MetricsInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        val startTime = System.nanoTime()

        return try {
            val response = chain.proceed(request)
            val duration = (System.nanoTime() - startTime) / 1_000_000
            // 埋点记录：URL、耗时、状态码
            MetricsRecorder.record(request.url.toString(), duration, response.code)
            response
        } catch (e: IOException) {
            val duration = (System.nanoTime() - startTime) / 1_000_000
            // 异常埋点：记录超时或网络异常
            MetricsRecorder.recordError(request.url.toString(), duration, e)
            throw e
        }
    }
}

// 添加到OkHttpClient
val client = OkHttpClient.Builder()
    .addInterceptor(MetricsInterceptor())   // 应用拦截器
    .addNetworkInterceptor(LoggingInterceptor()) // 网络拦截器用于调试
    .build()

2.2 CallAdapter与Converter：扩展埋点边界的适配层

CallAdapter 负责将 Call<T> 转换为业务需要的类型（如 RxJava Observable、Kotlin Flow），Converter 负责请求体序列化与响应体反序列化。二者是埋点系统插入统一异常处理和数据预处理的关键扩展点。

2.2.1 CallAdapter：统一装饰调用结果

自定义 CallAdapter 可以在回调发生前或发生后注入埋点逻辑，例如统一捕获解析异常、记录调用堆栈。

class MetricsCallAdapter<T>(private val wrapped: CallAdapter<T, *>) : CallAdapter<T, Any> {
    override fun responseType(): Class<*> = wrapped.responseType()

    override fun adapt(call: Call<T>): Any {
        val adapted = wrapped.adapt(call)
        // 如果adapted是Call，可以包裹一层代理Call来记录调用
        return MetricsCallProxy(adapted)
    }
}

class MetricsCallProxy<T>(private val delegate: Call<T>) : Call<T> by delegate {
    override fun enqueue(callback: Callback<T>) {
        delegate.enqueue(object : Callback<T> {
            override fun onResponse(call: Call<T>, response: Response<T>) {
                // 埋点：记录响应到达
                MetricsRecorder.recordResponse(response)
                callback.onResponse(call, response)
            }
            override fun onFailure(call: Call<T>, t: Throwable) {
                // 埋点：记录失败异常
                MetricsRecorder.recordFailure(t)
                callback.onFailure(call, t)
            }
        })
    }
}

2.2.2 Converter：预处理响应数据

Converter 在反序列化时有机会校验数据完整性、记录数据大小或捕获格式异常。

class MetricsConverter(private val delegate: Converter<ResponseBody, *>) : Converter<ResponseBody, Any> {
    override fun convert(value: ResponseBody): Any? {
        val contentLength = value.contentLength()
        return try {
            val result = delegate.convert(value)
            // 埋点：记录反序列化成功及数据大小
            MetricsRecorder.recordDeserializeSuccess(contentLength)
            result
        } catch (e: Exception) {
            // 埋点：记录反序列化异常
            MetricsRecorder.recordDeserializeError(contentLength, e)
            throw e
        }
    }
}

2.3 异步与同步调用差异：线程安全与埋点时机

Retrofit 同时支持同步（execute()）与异步（enqueue()）两种调用方式，本质差异在于执行线程与回调线程的不同。在埋点场景中，错误的选择会导致 UI 线程阻塞或埋点数据丢失。

// 同步调用（用于后台线程）
fun fetchDataSync(): Result<Data> = runBlocking {
    try {
        val response = apiService.getData().execute()
        if (response.isSuccessful) {
            // 同步埋点：记录成功
            MetricsRecorder.recordSyncSuccess()
            Result.success(response.body()!!)
        } else {
            MetricsRecorder.recordSyncError(response.code())
            Result.failure(HttpException(response))
        }
    } catch (e: Exception) {
        MetricsRecorder.recordSyncException(e)
        Result.failure(e)
    }
}

// 异步调用（用于UI层）
apiService.getData().enqueue(object : Callback<Data> {
    override fun onResponse(call: Call<Data>, response: Response<Data>) {
        // 主线程回调，埋点需确保线程安全
        MetricsRecorder.recordAsyncResponse(response)
    }
    override fun onFailure(call: Call<Data>, t: Throwable) {
        MetricsRecorder.recordAsyncFailure(t)
    }
})