现代网络架构

// OkHttpClient 中创建 Call 的核心方法
// 每次调用 newCall() 都会返回一个新的 RealCall 实例
override fun newCall(request: Request): Call {
    // 将当前 client 配置和请求信息传入 RealCall
    return RealCall(this, request, forWebSocket = false)
}

// RealCall 类的核心结构（简化版）
class RealCall(
    val client: OkHttpClient,        // 持有客户端配置的引用
    val originalRequest: Request,    // 原始请求对象
    val forWebSocket: Boolean        // 是否为 WebSocket 请求
) : Call {
    
    // 使用 AtomicBoolean 保证线程安全的执行状态检查
    private val executed = AtomicBoolean()
    
    // 同步执行：阻塞当前线程直到响应返回
    override fun execute(): Response {
        // CAS 操作确保只能执行一次
        // compareAndSet: 如果当前值为 false，则设置为 true 并返回 true
        // 如果当前值已经是 true，直接返回 false
        if (!executed.compareAndSet(false, true)) {
            throw IllegalStateException("Already Executed")
        }
        
        try {
            // 通知 Dispatcher 当前请求开始同步执行
            // 这样 Dispatcher 可以追踪正在运行的请求数量
            client.dispatcher.executed(this)
            
            // 通过拦截器链获取响应（核心处理逻辑）
            return getResponseWithInterceptorChain()
        } finally {
            // 无论成功失败，都要通知 Dispatcher 请求已完成
            client.dispatcher.finished(this)
        }
    }
    
    // 异步执行：将请求放入队列，通过回调返回结果
    override fun enqueue(responseCallback: Callback) {
        // 同样使用 CAS 保证只执行一次
        if (!executed.compareAndSet(false, true)) {
            throw IllegalStateException("Already Executed")
        }
        
        // 将回调包装成 AsyncCall（实现了 Runnable 接口）
        // 然后交给 Dispatcher 进行调度
        client.dispatcher.enqueue(AsyncCall(responseCallback))
    }
}

class Dispatcher {
    // 等待执行的异步请求队列
    // 当正在执行的请求数达到上限时，新请求会先放入这里
    private val readyAsyncCalls = ArrayDeque<AsyncCall>()
    
    // 正在执行的异步请求队列
    // 这些请求已经提交给线程池，正在运行中
    private val runningAsyncCalls = ArrayDeque<AsyncCall>()
    
    // 正在执行的同步请求集合
    // 同步请求不需要调度，但 Dispatcher 需要追踪它们以计算并发数
    private val runningSyncCalls = ArrayDeque<RealCall>()
    
    // 异步请求入队的核心逻辑
    internal fun enqueue(call: AsyncCall) {
        synchronized(this) {
            // 首先将请求放入等待队列
            readyAsyncCalls.add(call)
            
            // 如果不是 WebSocket 请求，尝试复用同一 host 的现有连接计数
            // 这是为了更精确地统计 perHost 并发数
            if (!call.call.forWebSocket) {
                val existingCall = findExistingCallWithHost(call.host)
                if (existingCall != null) {
                    call.reuseCallsPerHostFrom(existingCall)
                }
            }
        }
        // 触发调度逻辑，尝试将等待队列中的请求提升到执行队列
        promoteAndExecute()
    }
    
    // 核心调度方法：提升等待请求并执行
    private fun promoteAndExecute(): Boolean {
        // 收集本次可以执行的请求
        val executableCalls = mutableListOf<AsyncCall>()
        val isRunning: Boolean
        
        synchronized(this) {
            // 遍历等待队列
            val i = readyAsyncCalls.iterator()
            while (i.hasNext()) {
                val asyncCall = i.next()
                
                // 检查全局并发上限
                if (runningAsyncCalls.size >= maxRequests) break
                
                // 检查单主机并发上限
                if (asyncCall.callsPerHost.get() >= maxRequestsPerHost) continue
                
                // 通过检查，从等待队列移除
                i.remove()
                
                // 增加该主机的并发计数
                asyncCall.callsPerHost.incrementAndGet()
                
                // 加入可执行列表和执行队列
                executableCalls.add(asyncCall)
                runningAsyncCalls.add(asyncCall)
            }
            isRunning = runningCallsCount() > 0
        }
        
        // 在同步块外执行，避免持锁时间过长
        for (asyncCall in executableCalls) {
            // 将 AsyncCall 提交给线程池执行
            asyncCall.executeOn(executorService)
        }
        
        return isRunning
    }
}

// Dispatcher 的默认线程池配置
val executorService: ExecutorService
    get() {
        if (executorServiceOrNull == null) {
            // 核心线程数 = 0：没有常驻线程，空闲时资源消耗为零
            // 最大线程数 = Int.MAX_VALUE：理论上无上限（实际受 maxRequests 控制）
            // keepAliveTime = 60秒：空闲线程存活时间
            // SynchronousQueue：无缓冲队列，任务直接交给线程
            executorServiceOrNull = ThreadPoolExecutor(
                0,                          // corePoolSize
                Int.MAX_VALUE,              // maximumPoolSize
                60L,                         // keepAliveTime
                TimeUnit.SECONDS,           // unit
                SynchronousQueue(),         // workQueue
                threadFactory("OkHttp Dispatcher", false)
            )
        }
        return executorServiceOrNull!!
    }

// RealCall 中构建并启动拦截器链
@Throws(IOException::class)
internal fun getResponseWithInterceptorChain(): Response {
    // 按顺序构建拦截器列表
    val interceptors = mutableListOf<Interceptor>()
    
    // 1. 首先添加用户自定义的 Application Interceptors
    // 这些拦截器最先执行，可以拿到最原始的请求
    interceptors += client.interceptors
    
    // 2. 添加核心拦截器（顺序固定，不可改变）
    interceptors += RetryAndFollowUpInterceptor(client)
    interceptors += BridgeInterceptor(client.cookieJar)
    interceptors += CacheInterceptor(client.cache)
    interceptors += ConnectInterceptor
    
    // 3. 如果不是 WebSocket，添加 Network Interceptors
    // 这些拦截器在连接建立后、实际请求前执行
    if (!forWebSocket) {
        interceptors += client.networkInterceptors
    }
    
    // 4. 最后添加实际执行网络请求的拦截器
    interceptors += CallServerInterceptor(forWebSocket)
    
    // 构建责任链，初始 index = 0，从第一个拦截器开始
    val chain = RealInterceptorChain(
        call = this,
        interceptors = interceptors,
        index = 0,                    // 当前拦截器索引
        exchange = null,
        request = originalRequest,
        connectTimeoutMillis = client.connectTimeoutMillis,
        readTimeoutMillis = client.readTimeoutMillis,
        writeTimeoutMillis = client.writeTimeoutMillis
    )
    
    // 启动责任链，开始处理请求
    val response = chain.proceed(originalRequest)
    
    // 检查响应有效性
    if (response.body == null) {
        throw IllegalStateException("interceptor ${interceptors[chain.index - 1]} returned a response with no body")
    }
    
    return response
}

class RealInterceptorChain(
    val interceptors: List<Interceptor>,
    val index: Int,           // 当前要执行的拦截器索引
    val request: Request,
    // ... 其他参数
) : Interceptor.Chain {
    
    @Throws(IOException::class)
    override fun proceed(request: Request): Response {
        // 检查索引是否越界
        check(index < interceptors.size) { "index out of bounds" }
        
        // 创建一个新的 Chain 实例，index + 1 指向下一个拦截器
        // 注意：这里不是修改当前对象，而是创建新对象
        // 这使得每个拦截器持有的 Chain 都是独立的
        val next = copy(index = index + 1, request = request)
        
        // 获取当前索引对应的拦截器
        val interceptor = interceptors[index]
        
        // 调用拦截器的 intercept 方法
        // 拦截器内部可以：
        // 1. 直接返回 Response（短路，不再继续传递）
        // 2. 调用 chain.proceed() 将请求传递给下一个拦截器
        // 3. 修改 Request 后再调用 chain.proceed()
        // 4. 获取 Response 后进行修改再返回
        val response = interceptor.intercept(next)
        
        // 验证响应不为空
        checkNotNull(response.body) { "interceptor $interceptor returned a response with no body" }
        
        return response
    }
}

// 自定义日志拦截器示例
// 记录每个请求的 URL、耗时和响应状态
class LoggingInterceptor : Interceptor {
    
    // 实现 intercept 方法，这是拦截器的核心
    override fun intercept(chain: Interceptor.Chain): Response {
        // 从 chain 中获取当前请求
        val request = chain.request()
        
        // 记录请求开始时间
        val startTime = System.nanoTime()
        
        // 打印请求信息
        Log.d("OkHttp", "Sending request: ${request.url}")
        Log.d("OkHttp", "Headers: ${request.headers}")
        
        // 【关键】调用 chain.proceed() 将请求传递给下一个拦截器
        // 这一行会阻塞，直到获得最终的响应
        // 如果不调用 proceed()，请求链就会中断
        val response = chain.proceed(request)
        
        // 计算请求耗时
        val duration = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startTime)
        
        // 打印响应信息
        Log.d("OkHttp", "Received response for ${request.url}")
        Log.d("OkHttp", "Status: ${response.code}, Time: ${duration}ms")
        
        // 返回响应（可以是原始响应，也可以是修改后的响应）
        return response
    }
}
 
// 将拦截器添加到 OkHttpClient
val client = OkHttpClient.Builder()
    // addInterceptor: 添加 Application Interceptor
    // 特点：最先执行，只执行一次（即使有重定向）
    .addInterceptor(LoggingInterceptor())
    
    // addNetworkInterceptor: 添加 Network Interceptor
    // 特点：在连接建立后执行，每次网络请求都执行（包括重定向）
    // .addNetworkInterceptor(LoggingInterceptor())
    
    .build()

// 创建自定义连接池
val connectionPool = ConnectionPool(
    maxIdleConnections = 10,    // 最大空闲连接数
    keepAliveDuration = 10,      // 空闲连接存活时间
    timeUnit = TimeUnit.MINUTES  // 时间单位
)
 
// 将连接池配置到 OkHttpClient
val client = OkHttpClient.Builder()
    .connectionPool(connectionPool)  // 注入自定义连接池
    .build()

// RealConnection 中判断连接是否可复用的核心逻辑（简化版）
internal fun isEligible(address: Address, routes: List<Route>?): Boolean {
    // 检查当前连接上的流数量是否已达上限
    if (transmitters.size >= allocationLimit) return false
    
    // 检查地址是否兼容（主机、端口、代理、SSL 配置等）
    if (!this.route.address.equalsNonHost(address)) return false
    
    // 检查主机名是否匹配
    if (address.url.host == this.route.address.url.host) {
        return true  // 完美匹配，可以复用
    }
    
    // HTTP/2 连接可能支持连接合并（Connection Coalescing）
    // 这允许相同 IP 但不同主机名的请求复用同一连接
    // 前提是 TLS 证书覆盖了目标主机名
    return supportsConnectionCoalescing(address, routes)
}

// 路由选择的核心数据结构
class Route(
    val address: Address,        // 目标地址（主机名、端口、SSL 配置等）
    val proxy: Proxy,            // 代理配置（DIRECT、HTTP、SOCKS）
    val socketAddress: InetSocketAddress  // 实际的 Socket 地址（IP + 端口）
)
 
// RouteSelector 负责生成所有可能的路由
class RouteSelector(
    private val address: Address,
    private val routeDatabase: RouteDatabase,  // 记录失败路由的数据库
    private val call: Call,
    private val eventListener: EventListener
) {
    // 返回下一组可尝试的路由
    fun next(): Selection {
        // 1. 获取代理列表（可能来自 ProxySelector）
        // 2. 对每个代理，进行 DNS 解析获取 IP 地址
        // 3. 组合生成所有可能的路由
        // 4. 排除已知失败的路由
        // ...
    }
}

// 获取连接的核心逻辑（简化版）
fun findConnection(
    connectTimeout: Int,
    readTimeout: Int,
    writeTimeout: Int,
    pingIntervalMillis: Int,
    connectionRetryEnabled: Boolean
): RealConnection {
    // 第一步：检查是否已有可复用的连接
    val existingConnection = transmitter.connection
    if (existingConnection != null && existingConnection.isHealthy) {
        return existingConnection  // 直接复用当前连接
    }
    
    // 第二步：从连接池中查找匹配的连接
    val pooledConnection = connectionPool.findConnection(
        address = address,
        routes = routeSelection?.routes,
        requireMultiplexed = false
    )
    if (pooledConnection != null) {
        return pooledConnection  // 复用连接池中的连接
    }
    
    // 第三步：选择路由
    if (routeSelection == null || !routeSelection.hasNext()) {
        routeSelection = routeSelector.next()
    }
    val route = routeSelection.next()
    
    // 第四步：再次检查连接池（使用具体路由信息）
    val pooledConnection2 = connectionPool.findConnection(
        address = address,
        routes = listOf(route),
        requireMultiplexed = false
    )
    if (pooledConnection2 != null) {
        return pooledConnection2
    }
    
    // 第五步：创建新连接
    val newConnection = RealConnection(connectionPool, route)
    newConnection.connect(
        connectTimeout, readTimeout, writeTimeout,
        pingIntervalMillis, connectionRetryEnabled, call, eventListener
    )
    
    // 第六步：将新连接放入连接池
    connectionPool.put(newConnection)
    
    return newConnection
}

// HTTP/2 流的简化表示
class Http2Stream(
    val id: Int,                      // 流 ID（奇数为客户端发起，偶数为服务端发起）
    val connection: Http2Connection,   // 所属的 HTTP/2 连接
    var errorCode: ErrorCode? = null   // 流级别的错误码
) {
    // 流有自己的状态：IDLE -> OPEN -> HALF_CLOSED -> CLOSED
    // 流有自己的流量控制窗口，独立于连接级别的窗口
    // 流可以设置优先级，服务器据此决定响应顺序
}

┌─────────────────────────────────────────────────────────────┐
│                    RealConnection                           │
├─────────────────────────────────────────────────────────────┤
│  socket: Socket                                             │
│  handshake: Handshake?                                      │
│  protocol: Protocol (HTTP_1_1 / HTTP_2)                     │
│  allocationLimit: Int (HTTP/1.1=1, HTTP/2=多个)             │
│                                                             │
│  transmitters: MutableList<TransmitterRef>                  │
│     ├── TransmitterRef → Request A (活跃)                   │
│     ├── TransmitterRef → Request B (活跃)                   │
│     └── TransmitterRef → Request C (已完成，待清理)          │
│                                                             │
│  idleAtNs: Long (变为空闲的时间戳)                           │
└─────────────────────────────────────────────────────────────┘

HTTP/1.1 请求（默认保持连接）:
GET /api/users HTTP/1.1
Host: api.example.com
(不需要额外的头部，连接默认保持)
 
HTTP/1.1 请求（显式关闭连接）:
GET /api/users HTTP/1.1
Host: api.example.com
Connection: close
(服务器响应后将关闭连接)
 
HTTP/1.0 请求（请求保持连接）:
GET /api/users HTTP/1.0
Host: api.example.com
Connection: keep-alive
(如果服务器支持，将保持连接)

HTTP/1.1 200 OK
Connection: keep-alive
Keep-Alive: timeout=60, max=100
 
参数说明：
- timeout=60: 连接空闲超过 60 秒后服务器将关闭
- max=100: 此连接最多再处理 100 个请求

// RealConnection 中的健康检查
fun isHealthy(doExtensiveChecks: Boolean): Boolean {
    // 基础检查：Socket 是否仍然打开
    if (socket.isClosed || socket.isInputShutdown || socket.isOutputShutdown) {
        return false
    }
    
    // HTTP/2 连接检查：GOAWAY 帧和错误状态
    val http2Connection = this.http2Connection
    if (http2Connection != null) {
        return !http2Connection.isShutdown
    }
    
    // 扩展检查：尝试读取 Socket 检测是否有待处理的数据或错误
    if (doExtensiveChecks) {
        return !socket.isInputStreamExhausted()
    }
    
    return true
}

val client = OkHttpClient.Builder()
    .pingInterval(30, TimeUnit.SECONDS)  // 每 30 秒发送一次 PING
    .build()

// 单一后端场景
val singleBackendPool = ConnectionPool(
    maxIdleConnections = 3,
    keepAliveDuration = 5,
    timeUnit = TimeUnit.MINUTES
)
 
// 多域名场景
val multiDomainPool = ConnectionPool(
    maxIdleConnections = 15,
    keepAliveDuration = 3,
    timeUnit = TimeUnit.MINUTES
)

val client = OkHttpClient.Builder()
    .pingInterval(15, TimeUnit.SECONDS)  // 移动网络建议 15-30 秒
    .build()

// 自定义 EventListener 监控连接事件
class ConnectionEventListener : EventListener() {
    
    // 开始获取连接
    override fun connectionAcquired(call: Call, connection: Connection) {
        Log.d("OkHttp", "连接获取: ${connection.route().socketAddress()}")
    }
    
    // 连接释放
    override fun connectionReleased(call: Call, connection: Connection) {
        Log.d("OkHttp", "连接释放: ${connection.route().socketAddress()}")
    }
    
    // TCP 连接开始
    override fun connectStart(call: Call, inetSocketAddress: InetSocketAddress, proxy: Proxy) {
        Log.d("OkHttp", "正在建立连接: $inetSocketAddress")
    }
    
    // TCP 连接完成
    override fun connectEnd(
        call: Call,
        inetSocketAddress: InetSocketAddress,
        proxy: Proxy,
        protocol: Protocol?
    ) {
        Log.d("OkHttp", "连接建立完成: $inetSocketAddress, 协议: $protocol")
    }
}
 
// 使用 EventListener.Factory 为每个请求创建监听器
val client = OkHttpClient.Builder()
    .eventListenerFactory { ConnectionEventListener() }
    .build()

// 确保响应体被正确关闭，以便连接能够复用
client.newCall(request).execute().use { response ->  // use 会自动关闭
    val body = response.body?.string()
    // 处理响应...
}  // response 在这里自动关闭，连接可以归还连接池

// 定义一个 GitHub API 服务接口
// Interface 是 Retrofit 的核心契约，所有 API 端点都在这里声明
interface GitHubApiService {
 
    // @GET 注解标识这是一个 HTTP GET 请求
    // "users/{user}/repos" 是相对路径，{user} 是路径占位符
    @GET("users/{user}/repos")
    // suspend 关键字表示这是一个 Kotlin 协程挂起函数
    // Retrofit 2.6+ 原生支持挂起函数，底层会自动适配
    suspend fun listRepos(
        // @Path 注解将参数值替换到路径中的 {user} 占位符
        @Path("user") user: String,
        // @Query 注解将参数作为 URL 查询字符串 ?sort=...
        @Query("sort") sort: String = "updated"
    ): List<Repo>  // 返回类型会被 Converter 自动反序列化
 
    // POST 请求示例，用于创建资源
    @POST("repos/{owner}/{repo}/issues")
    suspend fun createIssue(
        @Path("owner") owner: String,
        @Path("repo") repo: String,
        // @Body 注解表示整个对象会被序列化为 JSON 请求体
        // 这需要配置相应的 Converter（如 GsonConverterFactory）
        @Body issue: CreateIssueRequest
    ): Issue
 
    // 动态 Header 示例：Token 认证
    @GET("user")
    suspend fun getCurrentUser(
        // @Header 注解允许在运行时动态设置请求头
        // 常用于传递 Authorization Token
        @Header("Authorization") authHeader: String
    ): User
 
    // 表单提交示例
    @FormUrlEncoded  // 标记请求体格式为 application/x-www-form-urlencoded
    @POST("login")
    suspend fun login(
        // @Field 注解将参数编码为表单字段
        @Field("username") username: String,
        @Field("password") password: String
    ): LoginResponse
}

// java.lang.reflect.Proxy 的核心方法签名
public static Object newProxyInstance(
    ClassLoader loader,           // 类加载器
    Class<?>[] interfaces,        // 要代理的接口数组
    InvocationHandler handler     // 调用处理器
) throws IllegalArgumentException

// Retrofit.create() 方法的简化版实现
// 这是理解 Retrofit 工作原理的关键入口
fun <T> create(service: Class<T>): T {
    // 验证传入的必须是接口类型
    validateServiceInterface(service)
    
    // 使用 Java 动态代理创建接口的实现实例
    @Suppress("UNCHECKED_CAST")
    return Proxy.newProxyInstance(
        // 使用服务接口的类加载器
        service.classLoader,
        // 代理类需要实现的接口数组（只有一个：我们的 API 接口）
        arrayOf(service),
        // 核心：InvocationHandler 处理所有方法调用
        object : InvocationHandler {
            // 每当调用代理对象的任何方法时，都会执行这个 invoke
            override fun invoke(
                proxy: Any,           // 代理对象本身
                method: Method,       // 被调用的方法反射对象
                args: Array<out Any>? // 方法参数数组
            ): Any? {
                // 特殊处理：Object 类的方法（如 toString、equals）直接执行
                if (method.declaringClass == Object::class.java) {
                    return method.invoke(this, *(args ?: emptyArray()))
                }
                
                // 核心：加载或创建 ServiceMethod，这是方法元数据的缓存容器
                // loadServiceMethod 会解析方法上的所有注解
                val serviceMethod = loadServiceMethod(method)
                
                // 调用 ServiceMethod 执行实际的网络请求逻辑
                // args 是调用时传入的实际参数值
                return serviceMethod.invoke(args)
            }
        }
    ) as T
}

// Retrofit 内部的 ServiceMethod 缓存
// 使用 ConcurrentHashMap 保证线程安全
private val serviceMethodCache: MutableMap<Method, ServiceMethod<*>> = 
    ConcurrentHashMap()
 
// loadServiceMethod 的简化实现
fun loadServiceMethod(method: Method): ServiceMethod<*> {
    // 首先尝试从缓存获取
    var result = serviceMethodCache[method]
    if (result != null) return result
    
    // 缓存未命中，需要同步解析（双重检查锁定）
    synchronized(serviceMethodCache) {
        result = serviceMethodCache[method]
        if (result == null) {
            // 调用 ServiceMethod.parseAnnotations 执行完整解析
            // 这是一个相对耗时的反射操作
            result = ServiceMethod.parseAnnotations(this, method)
            // 解析完成后放入缓存
            serviceMethodCache[method] = result
        }
    }
    return result!!
}

// ParameterHandler 的核心职责示意
// 每种参数注解都有对应的 Handler 实现
abstract class ParameterHandler<T> {
    // 将参数值应用到 RequestBuilder 上
    abstract fun apply(builder: RequestBuilder, value: T)
}
 
// @Path 参数处理器
class Path<T>(
    private val name: String,           // 占位符名称，如 "user"
    private val valueConverter: Converter<T, String>  // 值转换器
) : ParameterHandler<T>() {
    override fun apply(builder: RequestBuilder, value: T) {
        // 将参数值转换为字符串，替换 URL 中的 {name} 占位符
        builder.addPathParam(name, valueConverter.convert(value))
    }
}
 
// @Query 参数处理器
class Query<T>(
    private val name: String,           // 查询参数名
    private val valueConverter: Converter<T, String>,
    private val encoded: Boolean        // 是否已经 URL 编码
) : ParameterHandler<T>() {
    override fun apply(builder: RequestBuilder, value: T) {
        // 将参数添加到 URL 查询字符串：?name=value
        val convertedValue = valueConverter.convert(value)
        builder.addQueryParam(name, convertedValue, encoded)
    }
}
 
// @Body 参数处理器
class Body<T>(
    private val converter: Converter<T, RequestBody>  // JSON 序列化转换器
) : ParameterHandler<T>() {
    override fun apply(builder: RequestBuilder, value: T) {
        // 将对象序列化为 RequestBody，设置为请求体
        val body = converter.convert(value)
        builder.setBody(body)
    }
}

// Converter.kt - Retrofit 核心转换接口
// 泛型 F 表示输入类型（From），T 表示输出类型（To）
interface Converter<F, T> {
    // 执行实际的转换操作
    // 将类型 F 的输入转换为类型 T 的输出
    @Throws(IOException::class)
    fun convert(value: F): T?
}

// Converter.Factory - 转换器工厂抽象类
abstract class Factory {
    // 创建 ResponseBody → 目标类型 的转换器
    // type: 方法返回值的泛型类型（如 User、List<Order>）
    // annotations: 方法上的注解数组
    // retrofit: Retrofit 实例，可用于递归查找其他转换器
    open fun responseBodyConverter(
        type: Type,                    // 目标类型，如 User::class.java
        annotations: Array<Annotation>,// 方法注解，如 @GET、@POST
        retrofit: Retrofit             // Retrofit 实例引用
    ): Converter<ResponseBody, *>? = null
    
    // 创建 目标类型 → RequestBody 的转换器
    // 用于 @Body 注解的参数序列化
    open fun requestBodyConverter(
        type: Type,
        parameterAnnotations: Array<Annotation>, // 参数上的注解
        methodAnnotations: Array<Annotation>,    // 方法上的注解
        retrofit: Retrofit
    ): Converter<*, RequestBody>? = null
    
    // 创建 目标类型 → String 的转换器
    // 用于 @Query、@Path、@Header 等字符串参数
    open fun stringConverter(
        type: Type,
        annotations: Array<Annotation>,
        retrofit: Retrofit
    ): Converter<*, String>? = null
}

// build.gradle.kts 依赖配置
dependencies {
    // Retrofit 核心库
    implementation("com.squareup.retrofit2:retrofit:2.9.0")
    // Gson 转换器适配库
    implementation("com.squareup.retrofit2:converter-gson:2.9.0")
}

// Retrofit 实例构建
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    // 添加 Gson 转换器工厂
    // create() 使用默认配置的 Gson 实例
    .addConverterFactory(GsonConverterFactory.create())
    .build()

{
    "id": 1001,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2024-03-15T10:30:00Z"
}

// 用户数据模型
// @SerializedName 注解用于指定 JSON 字段名与属性名的映射关系
// 当 JSON 字段名与属性名不一致时（如下划线 vs 驼峰），必须使用此注解
data class User(
    val id: Long,                           // JSON 字段名与属性名一致，无需注解
    val name: String,
    val email: String,
    @SerializedName("created_at")           // JSON 字段 "created_at" 映射到 createdAt
    val createdAt: String
)
 
// API 接口定义
interface UserService {
    // GET 请求获取用户信息
    // 返回类型 User 会被 GsonConverterFactory 处理
    @GET("users/{id}")
    suspend fun getUser(@Path("id") userId: Long): User
}

// GsonConverterFactory.java 核心实现（简化版）
public final class GsonConverterFactory extends Converter.Factory {
    // 持有的 Gson 实例，所有转换操作都委托给它
    private final Gson gson;
    
    // 私有构造函数，强制通过 create() 工厂方法创建
    private GsonConverterFactory(Gson gson) {
        this.gson = gson;
    }
    
    // 静态工厂方法：使用默认 Gson 配置
    public static GsonConverterFactory create() {
        return create(new Gson());
    }
    
    // 静态工厂方法：使用自定义 Gson 配置
    public static GsonConverterFactory create(Gson gson) {
        if (gson == null) throw new NullPointerException("gson == null");
        return new GsonConverterFactory(gson);
    }
    
    // 响应体转换器：ResponseBody → 目标类型
    @Override
    public Converter<ResponseBody, ?> responseBodyConverter(
            Type type, Annotation[] annotations, Retrofit retrofit) {
        // 获取目标类型对应的 TypeAdapter
        // TypeAdapter 是 Gson 的核心类，负责具体的序列化/反序列化逻辑
        TypeAdapter<?> adapter = gson.getAdapter(TypeToken.get(type));
        // 返回封装了 TypeAdapter 的转换器
        return new GsonResponseBodyConverter<>(gson, adapter);
    }
    
    // 请求体转换器：目标类型 → RequestBody
    @Override
    public Converter<?, RequestBody> requestBodyConverter(
            Type type, Annotation[] paramAnnotations, 
            Annotation[] methodAnnotations, Retrofit retrofit) {
        TypeAdapter<?> adapter = gson.getAdapter(TypeToken.get(type));
        return new GsonRequestBodyConverter<>(gson, adapter);
    }
}

// GsonResponseBodyConverter.java - 响应体转换器实现
final class GsonResponseBodyConverter<T> implements Converter<ResponseBody, T> {
    private final Gson gson;
    private final TypeAdapter<T> adapter;
    
    GsonResponseBodyConverter(Gson gson, TypeAdapter<T> adapter) {
        this.gson = gson;
        this.adapter = adapter;
    }
    
    @Override
    public T convert(ResponseBody value) throws IOException {
        // 从 ResponseBody 获取字符流
        JsonReader jsonReader = gson.newJsonReader(value.charStream());
        try {
            // 使用 TypeAdapter 将 JSON 流解析为目标对象
            T result = adapter.read(jsonReader);
            // 检查是否还有未读取的 JSON 内容（格式校验）
            if (jsonReader.peek() != JsonToken.END_DOCUMENT) {
                throw new JsonIOException("JSON document was not fully consumed.");
            }
            return result;
        } finally {
            // 确保关闭 ResponseBody，释放连接资源
            value.close();
        }
    }
}

// 构建自定义配置的 Gson 实例
val customGson = GsonBuilder()
    // 日期格式化：统一 ISO 8601 格式
    .setDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'")
    // 序列化 null 值：默认情况下 Gson 会忽略 null 字段
    .serializeNulls()
    // 字段命名策略：自动将 camelCase 转换为 snake_case
    // 这样就不需要每个字段都加 @SerializedName 注解
    .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
    // 宽松解析模式：允许一些不规范的 JSON 格式
    .setLenient()
    // 排除特定修饰符的字段：如排除 transient 和 static 字段
    .excludeFieldsWithModifiers(Modifier.TRANSIENT, Modifier.STATIC)
    // 注册自定义 TypeAdapter：处理特殊类型
    .registerTypeAdapter(Date::class.java, CustomDateAdapter())
    .create()
 
// 使用自定义 Gson 创建转换器
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create(customGson))
    .build()

// build.gradle.kts 依赖配置
plugins {
    id("com.google.devtools.ksp") version "1.9.0-1.0.13" // KSP 插件
}
 
dependencies {
    // Moshi 核心库
    implementation("com.squareup.moshi:moshi:1.15.0")
    // Moshi Kotlin 代码生成器（推荐）
    ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.0")
    // Retrofit Moshi 转换器
    implementation("com.squareup.retrofit2:converter-moshi:2.9.0")
}

// 使用 @JsonClass 注解启用代码生成
// generateAdapter = true 表示在编译时生成 JsonAdapter
@JsonClass(generateAdapter = true)
data class User(
    val id: Long,
    val name: String,
    val email: String,
    // @Json 注解指定 JSON 字段名映射（类似 Gson 的 @SerializedName）
    @Json(name = "created_at")
    val createdAt: String,
    // Moshi 正确处理 Kotlin 默认参数
    // 如果 JSON 中没有 avatar 字段，会使用默认值而非 null
    val avatar: String = "default_avatar.png"
)

// 构建 Moshi 实例
val moshi = Moshi.Builder()
    // 如果使用反射模式而非代码生成，需要添加 KotlinJsonAdapterFactory
    // .add(KotlinJsonAdapterFactory())
    // 添加自定义适配器
    .add(CustomDateAdapter())
    .build()
 
// 构建 Retrofit 实例
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(MoshiConverterFactory.create(moshi))
    .build()

// 假设 User 类定义了 name 为非空类型
@JsonClass(generateAdapter = true)
data class User(
    val id: Long,
    val name: String  // 非空类型
)
 
// 当服务端返回 {"id": 1, "name": null} 时
// Gson：静默将 name 设为 null，后续访问 name 时抛 NullPointerException
// Moshi：立即抛出 JsonDataException: Non-null value 'name' was null at $.name

val moshi = Moshi.Builder()
    // 添加 Kotlin 反射适配器
    .add(KotlinJsonAdapterFactory())
    .build()

// 使用 @JsonClass(generateAdapter = true) 注解的类
// 编译时会生成 UserJsonAdapter 类
@JsonClass(generateAdapter = true)
data class User(...)
 
// 生成的适配器直接访问字段，无反射开销
// 伪代码展示生成的 UserJsonAdapter
class UserJsonAdapter(moshi: Moshi) : JsonAdapter<User>() {
    override fun fromJson(reader: JsonReader): User {
        var id: Long? = null
        var name: String? = null
        // ... 直接字段赋值，无反射
    }
}

{
    "code": 200,
    "message": "success",
    "data": { /* 实际业务数据 */ }
}

// 统一响应包装类
data class ApiResponse<T>(
    val code: Int,
    val message: String,
    val data: T
)
 
// 自定义转换器工厂：自动解包 data 字段
class UnwrapConverterFactory(
    private val delegate: Converter.Factory  // 委托给实际的 JSON 转换器
) : Converter.Factory() {
    
    override fun responseBodyConverter(
        type: Type,
        annotations: Array<Annotation>,
        retrofit: Retrofit
    ): Converter<ResponseBody, *>? {
        // 检查是否有 @Unwrap 注解，决定是否需要解包
        val unwrap = annotations.any { it is Unwrap }
        if (!unwrap) {
            // 没有 @Unwrap 注解，委托给原始转换器
            return delegate.responseBodyConverter(type, annotations, retrofit)
        }
        
        // 构造包装类型 ApiResponse<T>
        val wrappedType = TypeToken.getParameterized(
            ApiResponse::class.java, 
            type
        ).type
        
        // 获取包装类型的转换器
        val wrappedConverter = delegate.responseBodyConverter(
            wrappedType, annotations, retrofit
        ) ?: return null
        
        // 返回解包转换器
        @Suppress("UNCHECKED_CAST")
        return UnwrapConverter(wrappedConverter as Converter<ResponseBody, ApiResponse<Any>>)
    }
}
 
// 解包转换器实现
class UnwrapConverter<T>(
    private val delegate: Converter<ResponseBody, ApiResponse<T>>
) : Converter<ResponseBody, T> {
    
    override fun convert(value: ResponseBody): T? {
        // 先用委托转换器解析完整响应
        val response = delegate.convert(value)
        // 检查业务状态码
        if (response?.code != 200) {
            throw ApiException(response?.code ?: -1, response?.message ?: "Unknown error")
        }
        // 返回解包后的 data
        return response.data
    }
}
 
// 标记注解：表示该方法返回值需要解包
@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class Unwrap
 
// 使用示例
interface UserService {
    @Unwrap  // 添加此注解，返回值会自动解包
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Long): User  // 直接返回 User，而非 ApiResponse<User>
}

// 自定义日期格式转换器工厂
class DateStringConverterFactory : Converter.Factory() {
    
    // 日期格式化器，线程安全
    private val dateFormat = SimpleDateFormat("yyyy-MM-dd", Locale.US)
    
    override fun stringConverter(
        type: Type,
        annotations: Array<Annotation>,
        retrofit: Retrofit
    ): Converter<*, String>? {
        // 只处理 Date 类型
        if (type != Date::class.java) {
            return null  // 返回 null 表示不处理，交给下一个 Factory
        }
        return DateToStringConverter(dateFormat)
    }
    
    private class DateToStringConverter(
        private val format: SimpleDateFormat
    ) : Converter<Date, String> {
        override fun convert(value: Date): String {
            return synchronized(format) {
                format.format(value)
            }
        }
    }
}
 
// 使用示例
interface OrderService {
    @GET("orders")
    suspend fun getOrders(
        @Query("from") fromDate: Date,  // 会被转换为 "2024-03-15" 格式
        @Query("to") toDate: Date
    ): List<Order>
}

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    // 工厂注册顺序决定查找优先级
    .addConverterFactory(UnwrapConverterFactory(MoshiConverterFactory.create(moshi)))
    .addConverterFactory(ScalarsConverterFactory.create())  // 处理原始类型
    .addConverterFactory(MoshiConverterFactory.create(moshi))
    .build()

// CallAdapter 接口定义（位于 retrofit2 包下）
// 泛型参数 R 代表 Response body 类型，T 代表适配后的返回类型
interface CallAdapter<R, T> {
    
    // 返回 Response body 的类型
    // 例如对于 Observable<User>，这里返回 User 的 Type
    // Retrofit 据此选择合适的 Converter 来解析响应体
    fun responseType(): Type
    
    // 核心方法：将 Retrofit 原生的 Call<R> 适配成目标类型 T
    // 参数 call 是 Retrofit 内部创建的 OkHttpCall 实例
    // 返回值就是接口方法声明的返回类型（如 Observable、Deferred、LiveData 等）
    fun adapt(call: Call<R>): T
}

// CallAdapter.Factory 抽象类
// 负责根据返回类型和注解判断是否能处理，并创建对应的 CallAdapter
abstract class CallAdapter.Factory {
    
    // 核心方法：尝试为给定的返回类型创建 CallAdapter
    // returnType: 接口方法的返回类型（如 Observable<Response<User>>）
    // annotations: 方法上的注解数组
    // retrofit: Retrofit 实例，可用于递归获取其他 Adapter
    // 返回 null 表示本 Factory 无法处理该类型，Retrofit 会尝试下一个 Factory
    abstract fun get(
        returnType: Type,      // 方法返回类型
        annotations: Array<Annotation>,  // 方法注解
        retrofit: Retrofit     // Retrofit 实例引用
    ): CallAdapter<*, *>?
    
    // 辅助方法：获取泛型参数的上界类型
    // 例如从 Observable<? extends User> 中提取 User
    protected fun getParameterUpperBound(index: Int, type: ParameterizedType): Type
    
    // 辅助方法：获取原始类型
    // 例如从 Observable<User> 中提取 Observable.class
    protected fun getRawType(type: Type): Class<*>
}

// 在 Retrofit 构建时添加 RxJava3 适配器
// 注意：Factory 的添加顺序会影响 Adapter 的选择优先级
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")  // 设置 API 基础 URL
    .client(okHttpClient)                  // 配置 OkHttp 客户端
    .addConverterFactory(GsonConverterFactory.create())  // JSON 转换器
    .addCallAdapterFactory(RxJava3CallAdapterFactory.create())  // RxJava3 适配器
    .build()
 
// 定义支持 RxJava 返回类型的 API 接口
interface UserApi {
    
    // 返回 Observable：适合需要多次发射或组合操作的场景
    // Observable 是"热"的概念，订阅后开始执行
    @GET("users/{id}")
    fun getUserObservable(@Path("id") id: Long): Observable<User>
    
    // 返回 Single：语义上明确表示"只会发射一个值或错误"
    // 最适合 HTTP 请求这种单次响应的场景
    @GET("users/{id}")
    fun getUserSingle(@Path("id") id: Long): Single<User>
    
    // 返回 Maybe：可能有值、可能为空、可能出错
    // 适合可能返回 204 No Content 的接口
    @GET("users/{id}")
    fun getUserMaybe(@Path("id") id: Long): Maybe<User>
    
    // 返回 Flowable：支持背压（Backpressure）的响应式类型
    // 当下游处理速度跟不上上游发射速度时，Flowable 提供背压策略
    @GET("users")
    fun getAllUsersFlowable(): Flowable<List<User>>
    
    // 返回 Completable：只关心操作成功或失败，不需要返回数据
    // 典型场景：DELETE 请求、POST 不返回 body 的请求
    @DELETE("users/{id}")
    fun deleteUser(@Path("id") id: Long): Completable
    
    // 包装 Response：当需要访问 HTTP 状态码、响应头等元信息时使用
    @GET("users/{id}")
    fun getUserWithResponse(@Path("id") id: Long): Single<Response<User>>
    
    // 包装 Result：Retrofit 提供的包装类，可以统一处理成功响应和异常
    @GET("users/{id}")
    fun getUserWithResult(@Path("id") id: Long): Observable<Result<User>>
}

// RxJava3CallAdapter 核心实现原理（简化版）
// 展示如何将 Call<R> 适配成 Observable<R>
class RxJava3CallAdapter<R>(
    private val responseType: Type,  // 响应体类型
    private val scheduler: Scheduler?,  // 可选的订阅调度器
    private val isAsync: Boolean,  // 是否异步执行
    private val isResult: Boolean,  // 是否包装为 Result
    private val isBody: Boolean,   // 是否直接返回 body
    private val isFlowable: Boolean,  // 目标类型标识
    private val isSingle: Boolean,
    private val isMaybe: Boolean,
    private val isCompletable: Boolean
) : CallAdapter<R, Any> {
 
    override fun responseType(): Type = responseType
 
    override fun adapt(call: Call<R>): Any {
        // 核心：创建 Observable，在订阅时执行网络请求
        // 使用 CallEnqueueObservable 或 CallExecuteObservable
        val responseObservable = if (isAsync) {
            // 异步模式：使用 enqueue 非阻塞执行
            CallEnqueueObservable(call)
        } else {
            // 同步模式：使用 execute 阻塞执行（需配合 subscribeOn）
            CallExecuteObservable(call)
        }
        
        // 根据配置转换 Observable 的发射内容
        var observable: Observable<*> = when {
            isResult -> ResultObservable(responseObservable)  // 包装为 Result
            isBody -> BodyObservable(responseObservable)      // 只发射 body
            else -> responseObservable                         // 发射完整 Response
        }
        
        // 如果指定了调度器，自动切换订阅线程
        scheduler?.let { observable = observable.subscribeOn(it) }
        
        // 根据目标类型进行最终转换
        return when {
            isFlowable -> observable.toFlowable(BackpressureStrategy.LATEST)
            isSingle -> observable.singleOrError()
            isMaybe -> observable.singleElement()
            isCompletable -> observable.ignoreElements()
            else -> observable  // 返回 Observable
        }
    }
}
 
// CallEnqueueObservable：将 Call.enqueue() 转换为 Observable
// 这是连接 OkHttp 回调与 RxJava 发射的关键桥梁
class CallEnqueueObservable<T>(
    private val originalCall: Call<T>
) : Observable<Response<T>>() {
 
    override fun subscribeActual(observer: Observer<in Response<T>>) {
        // 每次订阅时克隆 Call，确保可以重复订阅
        // Call 是一次性的，执行后不能再次执行
        val call = originalCall.clone()
        
        // 创建回调包装器，实现 Disposable 接口支持取消
        val callback = CallCallback(call, observer)
        
        // 将 Disposable 传递给 Observer，支持取消订阅
        observer.onSubscribe(callback)
        
        // 如果已经被取消，不执行请求
        if (callback.isDisposed) return
        
        // 执行异步请求，回调中会发射数据
        call.enqueue(callback)
    }
    
    // 回调包装类，桥接 Retrofit Callback 与 RxJava Observer
    private class CallCallback<T>(
        private val call: Call<T>,
        private val observer: Observer<in Response<T>>
    ) : Disposable, Callback<T> {
        
        @Volatile private var disposed = false
        
        override fun onResponse(call: Call<T>, response: Response<T>) {
            if (disposed) return  // 已取消则忽略响应
            
            try {
                observer.onNext(response)  // 发射响应
                if (!disposed) {
                    observer.onComplete()  // 发射完成信号
                }
            } catch (e: Throwable) {
                if (!disposed) {
                    observer.onError(e)  // 发射错误
                }
            }
        }
        
        override fun onFailure(call: Call<T>, t: Throwable) {
            if (disposed) return
            
            try {
                observer.onError(t)  // 网络错误时发射异常
            } catch (inner: Throwable) {
                // 如果 onError 也抛出异常，需要特殊处理
                RxJavaPlugins.onError(CompositeException(t, inner))
            }
        }
        
        override fun isDisposed(): Boolean = disposed
        
        override fun dispose() {
            disposed = true
            call.cancel()  // 取消订阅时同时取消网络请求
        }
    }
}

// 场景一：链式请求 - 先登录后获取用户信息
// RxJava 的操作符让异步流程变得优雅
userApi.login(credentials)  // 返回 Single<LoginResponse>
    .flatMap { loginResponse ->
        // 登录成功后，用 token 获取用户详情
        // flatMap 将上游的结果转换为新的 Single
        userApi.getUserSingle(loginResponse.userId)
    }
    .subscribeOn(Schedulers.io())  // 在 IO 线程执行网络请求
    .observeOn(AndroidSchedulers.mainThread())  // 结果回调切换到主线程
    .subscribe(
        { user -> updateUI(user) },  // 成功回调
        { error -> showError(error) }  // 错误回调
    )
 
// 场景二：并行请求 - 同时获取多个独立数据
// 使用 zip 操作符合并多个请求的结果
Single.zip(
    userApi.getUserSingle(userId),           // 请求 1
    orderApi.getUserOrders(userId),          // 请求 2
    addressApi.getUserAddresses(userId)      // 请求 3
) { user, orders, addresses ->
    // 三个请求都完成后，合并数据
    UserProfile(user, orders, addresses)
}
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe { profile -> displayProfile(profile) }
 
// 场景三：重试机制 - 网络不稳定时自动重试
userApi.getUserSingle(userId)
    .retryWhen { errors ->
        // 遇到错误时，延迟重试
        errors.zipWith(Observable.range(1, 3)) { error, retryCount ->
            // 最多重试 3 次，每次延迟增加
            if (retryCount >= 3) throw error
            retryCount
        }.flatMap { retryCount ->
            // 指数退避：1秒、2秒、4秒
            Observable.timer(retryCount.toLong().pow(2), TimeUnit.SECONDS)
        }
    }
    .subscribe { user -> handleUser(user) }

// 使用协程的 API 接口定义
// 注意：suspend 关键字使方法成为挂起函数
interface UserApi {
    
    // 直接返回实体：最简洁的写法
    // Retrofit 会自动处理请求和响应解析
    // 成功时返回 User，失败时抛出异常
    @GET("users/{id}")
    suspend fun getUser(@Path("id") id: Long): User
    
    // 返回 Response 包装：需要访问状态码、响应头时使用
    // 即使 HTTP 状态码是 4xx/5xx，也不会抛异常，而是返回 Response
    @GET("users/{id}")
    suspend fun getUserWithResponse(@Path("id") id: Long): Response<User>
    
    // 返回 ResponseBody：处理未知结构或流式响应
    // 适合下载文件等场景
    @GET("files/{name}")
    @Streaming  // 标记为流式响应，不将整个响应加载到内存
    suspend fun downloadFile(@Path("name") name: String): ResponseBody
    
    // 带请求体的 POST 请求
    @POST("users")
    suspend fun createUser(@Body user: User): User
    
    // 返回 Unit（或 void）：不关心响应体
    @DELETE("users/{id}")
    suspend fun deleteUser(@Path("id") id: Long)
}

// Retrofit 内部处理 suspend 函数的核心逻辑（简化版）
// 位于 HttpServiceMethod.java 中
abstract class HttpServiceMethod<ResponseT, ReturnT> : ServiceMethod<ReturnT>() {
    
    companion object {
        fun <ResponseT, ReturnT> parseAnnotations(
            retrofit: Retrofit,
            method: Method,
            requestFactory: RequestFactory
        ): HttpServiceMethod<ResponseT, ReturnT> {
            
            // 获取方法的返回类型
            val adapterType = method.genericReturnType
            
            // 检查是否是 Kotlin suspend 函数
            // Kotlin 编译器会将 suspend fun foo(): T 转换为 fun foo(cont: Continuation<T>): Any?
            val isKotlinSuspendFunction = /* 检测逻辑 */
            
            if (isKotlinSuspendFunction) {
                // 获取 Continuation 的泛型参数，即实际的返回类型
                val continuationType = /* 解析 Continuation<T> 中的 T */
                
                // 判断是返回 Response<T> 还是直接返回 T
                return if (getRawType(continuationType) == Response::class.java) {
                    // suspend fun getUser(): Response<User>
                    SuspendForResponse(/* 参数 */)
                } else {
                    // suspend fun getUser(): User
                    SuspendForBody(/* 参数 */)
                }
            }
            
            // 非 suspend 函数走正常的 CallAdapter 流程
            // ...
        }
    }
    
    // SuspendForBody：直接返回响应体的 suspend 函数实现
    class SuspendForBody<ResponseT> : HttpServiceMethod<ResponseT, Any?>() {
        
        override fun adapt(call: Call<ResponseT>, args: Array<Any?>): Any? {
            // 从参数中获取 Continuation（最后一个参数）
            val continuation = args.last() as Continuation<ResponseT>
            
            // 使用 suspendCancellableCoroutine 桥接回调与协程
            return KotlinExtensions.awaitResponse(call, continuation)
        }
    }
}
 
// KotlinExtensions.kt 中的扩展函数
// 将 Call 的回调式 API 转换为协程挂起形式
suspend fun <T> Call<T>.await(): T {
    return suspendCancellableCoroutine { continuation ->
        // 当协程被取消时，同时取消网络请求
        continuation.invokeOnCancellation {
            cancel()  // 取消 OkHttp 请求
        }
        
        // 执行异步请求
        enqueue(object : Callback<T> {
            override fun onResponse(call: Call<T>, response: Response<T>) {
                if (response.isSuccessful) {
                    // HTTP 2xx：恢复协程并返回响应体
                    val body = response.body()
                    if (body != null) {
                        continuation.resume(body)
                    } else {
                        // 响应体为空时抛出异常
                        continuation.resumeWithException(
                            KotlinNullPointerException("Response body is null")
                        )
                    }
                } else {
                    // HTTP 4xx/5xx：抛出 HttpException
                    continuation.resumeWithException(
                        HttpException(response)
                    )
                }
            }
            
            override fun onFailure(call: Call<T>, t: Throwable) {
                // 网络错误：直接传递异常
                continuation.resumeWithException(t)
            }
        })
    }
}
 
// 返回完整 Response 的版本
suspend fun <T> Call<T>.awaitResponse(): Response<T> {
    return suspendCancellableCoroutine { continuation ->
        continuation.invokeOnCancellation { cancel() }
        
        enqueue(object : Callback<T> {
            override fun onResponse(call: Call<T>, response: Response<T>) {
                // 不管状态码如何，都直接返回 Response
                // 调用者自己判断 response.isSuccessful
                continuation.resume(response)
            }
            
            override fun onFailure(call: Call<T>, t: Throwable) {
                continuation.resumeWithException(t)
            }
        })
    }
}

// ViewModel 中使用协程发起网络请求
class UserViewModel(
    private val userApi: UserApi,
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
    
    // 使用 StateFlow 暴露 UI 状态
    private val _uiState = MutableStateFlow<UserUiState>(UserUiState.Loading)
    val uiState: StateFlow<UserUiState> = _uiState.asStateFlow()
    
    // 加载用户数据
    fun loadUser(userId: Long) {
        // viewModelScope：与 ViewModel 生命周期绑定的协程作用域
        // ViewModel 销毁时自动取消所有协程
        viewModelScope.launch {
            _uiState.value = UserUiState.Loading
            
            try {
                // 直接调用 suspend 函数，代码看起来是同步的
                val user = userApi.getUser(userId)
                _uiState.value = UserUiState.Success(user)
            } catch (e: HttpException) {
                // HTTP 错误（4xx、5xx）
                _uiState.value = UserUiState.Error(
                    message = "服务器错误: ${e.code()}",
                    code = e.code()
                )
            } catch (e: IOException) {
                // 网络错误（无网络、超时等）
                _uiState.value = UserUiState.Error(
                    message = "网络连接失败，请检查网络设置"
                )
            }
        }
    }
    
    // 并行请求示例：使用 async 并发执行多个请求
    fun loadUserProfile(userId: Long) {
        viewModelScope.launch {
            try {
                // async 启动并发协程，返回 Deferred
                // coroutineScope 确保所有子协程完成或任一失败时退出
                coroutineScope {
                    val userDeferred = async { userApi.getUser(userId) }
                    val ordersDeferred = async { orderApi.getUserOrders(userId) }
                    val addressDeferred = async { addressApi.getAddresses(userId) }
                    
                    // await() 等待结果，三个请求并行执行
                    val user = userDeferred.await()
                    val orders = ordersDeferred.await()
                    val addresses = addressDeferred.await()
                    
                    _uiState.value = UserUiState.Success(
                        UserProfile(user, orders, addresses)
                    )
                }
            } catch (e: Exception) {
                // 任一请求失败都会进入这里
                _uiState.value = UserUiState.Error(e.message ?: "未知错误")
            }
        }
    }
    
    // 串行请求示例：后一个请求依赖前一个的结果
    fun loginAndLoadProfile(credentials: Credentials) {
        viewModelScope.launch {
            try {
                // 顺序执行：登录 -> 获取用户信息
                val loginResult = authApi.login(credentials)  // 第一步
                val user = userApi.getUser(loginResult.userId)  // 第二步
                _uiState.value = UserUiState.Success(user)
            } catch (e: Exception) {
                handleError(e)
            }
        }
    }
}
 
// UI 状态密封类
sealed class UserUiState {
    object Loading : UserUiState()
    data class Success(val user: User) : UserUiState()
    data class Error(val message: String, val code: Int? = null) : UserUiState()
}

// 添加 LiveData 适配器依赖
// implementation "androidx.lifecycle:lifecycle-livedata:2.x.x"
// 注意：LiveDataCallAdapterFactory 不是 Retrofit 官方提供的
// 通常需要自定义实现或使用第三方库
 
// Retrofit 配置
val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .addCallAdapterFactory(LiveDataCallAdapterFactory())  // 自定义的 LiveData 适配器
    .build()
 
// API 接口定义
interface UserApi {
    
    // 返回 LiveData 包装的响应
    @GET("users/{id}")
    fun getUser(@Path("id") id: Long): LiveData<ApiResponse<User>>
    
    // ApiResponse 是一个密封类，统一封装成功和错误
    @GET("users")
    fun getAllUsers(): LiveData<ApiResponse<List<User>>>
}
 
// ApiResponse：统一的 API 响应包装类
// 使用密封类可以在 when 表达式中穷举所有情况
sealed class ApiResponse<T> {
    
    // 成功响应
    data class Success<T>(val data: T) : ApiResponse<T>()
    
    // HTTP 错误响应（4xx、5xx）
    data class Error<T>(
        val code: Int,
        val message: String
    ) : ApiResponse<T>()
    
    // 网络异常（无网络、超时等）
    data class NetworkError<T>(
        val exception: Throwable
    ) : ApiResponse<T>()
    
    // 正在加载（可选，用于显示加载状态）
    class Loading<T> : ApiResponse<T>()
}

// LiveDataCallAdapterFactory：工厂类实现
class LiveDataCallAdapterFactory : CallAdapter.Factory() {
    
    override fun get(
        returnType: Type,
        annotations: Array<out Annotation>,
        retrofit: Retrofit
    ): CallAdapter<*, *>? {
        
        // 检查返回类型是否是 LiveData
        // getRawType 获取泛型的原始类型（去掉泛型参数）
        if (getRawType(returnType) != LiveData::class.java) {
            return null  // 不是 LiveData，让其他 Factory 处理
        }
        
        // 获取 LiveData 的泛型参数类型
        // 例如 LiveData<ApiResponse<User>> 中的 ApiResponse<User>
        val observableType = getParameterUpperBound(0, returnType as ParameterizedType)
        
        // 检查是否是 ApiResponse 包装类型
        val rawObservableType = getRawType(observableType)
        if (rawObservableType != ApiResponse::class.java) {
            throw IllegalArgumentException("LiveData 的类型参数必须是 ApiResponse")
        }
        
        // 获取 ApiResponse 的泛型参数（实际的数据类型）
        // 例如 ApiResponse<User> 中的 User
        val bodyType = getParameterUpperBound(0, observableType as ParameterizedType)
        
        return LiveDataCallAdapter<Any>(bodyType)
    }
}
 
// LiveDataCallAdapter：适配器实现
class LiveDataCallAdapter<R>(
    private val responseType: Type  // 响应体类型
) : CallAdapter<R, LiveData<ApiResponse<R>>> {
    
    override fun responseType(): Type = responseType
    
    override fun adapt(call: Call<R>): LiveData<ApiResponse<R>> {
        // 返回一个自定义的 LiveData 实现
        // 这个 LiveData 会在有活跃观察者时自动发起请求
        return object : LiveData<ApiResponse<R>>() {
            
            // 用于确保只执行一次请求的原子标志
            private val started = AtomicBoolean(false)
            
            // 当 LiveData 变为活跃状态时调用
            // （有活跃的 Observer 且所在的 LifecycleOwner 至少处于 STARTED 状态）
            override fun onActive() {
                super.onActive()
                
                // CAS 操作：确保只执行一次
                if (started.compareAndSet(false, true)) {
                    // 先发射 Loading 状态
                    postValue(ApiResponse.Loading())
                    
                    // 发起网络请求
                    call.enqueue(object : Callback<R> {
                        
                        override fun onResponse(call: Call<R>, response: Response<R>) {
                            // 请求成功返回
                            val apiResponse = if (response.isSuccessful) {
                                val body = response.body()
                                if (body != null) {
                                    ApiResponse.Success(body)
                                } else {
                                    // 2xx 但 body 为空
                                    ApiResponse.Error(
                                        code = response.code(),
                                        message = "响应体为空"
                                    )
                                }
                            } else {
                                // HTTP 错误码（4xx、5xx）
                                ApiResponse.Error(
                                    code = response.code(),
                                    message = response.errorBody()?.string() ?: "未知错误"
                                )
                            }
                            // postValue 是线程安全的，会切换到主线程
                            postValue(apiResponse)
                        }
                        
                        override fun onFailure(call: Call<R>, t: Throwable) {
                            // 网络异常
                            postValue(ApiResponse.NetworkError(t))
                        }
                    })
                }
            }
        }
    }
}