Retrofit 内部工作原理时序图

Retrofit 内部工作原理时序图

本文档深入剖析Retrofit框架内部的工作机制，展示其核心组件的交互流程。

1. Retrofit 构建流程

sequenceDiagram
    participant Client as 开发者代码
    participant Builder as Retrofit.Builder
    participant Platform as Platform
    participant Executor as Executor
    participant Retrofit as Retrofit

    Client->>Builder: new Retrofit.Builder()
    activate Builder

    Client->>Builder: baseUrl(url)
    Builder->>Builder: 验证URL格式
    Builder->>Builder: 保存baseUrl

    Client->>Builder: client(okHttpClient)
    Builder->>Builder: 保存OkHttpClient实例

    Client->>Builder: addConverterFactory(factory)
    Builder->>Builder: converterFactories.add(factory)

    Client->>Builder: addCallAdapterFactory(factory)
    Builder->>Builder: callAdapterFactories.add(factory)

    Client->>Builder: build()
    Builder->>Platform: Platform.get()
    activate Platform
    Platform->>Platform: 检测运行平台<br/>(Android/Java8/默认)
    Platform-->>Builder: 返回Platform实例
    deactivate Platform

    Builder->>Executor: platform.defaultCallbackExecutor()
    activate Executor
    Executor-->>Builder: 返回默认Executor<br/>(Android为MainThreadExecutor)
    deactivate Executor

    Builder->>Builder: 添加平台默认CallAdapterFactory
    Builder->>Retrofit: new Retrofit(...)
    activate Retrofit
    Retrofit->>Retrofit: 初始化成员变量
    Retrofit-->>Builder: 返回Retrofit实例
    deactivate Retrofit

    Builder-->>Client: 返回Retrofit实例
    deactivate Builder

2. 动态代理创建 API 接口实例

sequenceDiagram
    participant Client as 开发者代码
    participant Retrofit as Retrofit
    participant Proxy as Proxy.newProxyInstance
    participant Handler as InvocationHandler
    participant ServiceMethod as ServiceMethod
    participant Cache as serviceMethodCache

    Client->>Retrofit: create(ApiService.class)
    activate Retrofit

    Retrofit->>Retrofit: validateServiceInterface(service)
    Retrofit->>Retrofit: 检查是否为接口
    Retrofit->>Retrofit: 检查接口中的泛型

    Retrofit->>Proxy: Proxy.newProxyInstance()
    activate Proxy

    Note over Proxy,Handler: 创建动态代理对象
    Proxy->>Handler: 传入InvocationHandler
    activate Handler

    Handler->>Handler: 定义invoke方法逻辑<br/>- 处理Object方法<br/>- 处理default方法<br/>- 处理接口方法

    Proxy-->>Retrofit: 返回代理对象
    deactivate Proxy
    deactivate Handler

    Retrofit-->>Client: 返回ApiService代理实例
    deactivate Retrofit

    Note over Client,Cache: 当调用接口方法时触发
    Client->>Handler: method.invoke(proxy, args)
    activate Handler

    Handler->>Cache: serviceMethodCache.get(method)
    activate Cache

    alt 缓存存在
        Cache-->>Handler: 返回缓存的ServiceMethod
    else 缓存不存在
        Cache->>ServiceMethod: ServiceMethod.parseAnnotations()
        activate ServiceMethod
        ServiceMethod->>ServiceMethod: 解析方法注解和参数
        ServiceMethod-->>Cache: 返回ServiceMethod
        deactivate ServiceMethod
        Cache->>Cache: cache.put(method, serviceMethod)
        Cache-->>Handler: 返回新建的ServiceMethod
    end
    deactivate Cache

    Handler->>ServiceMethod: invoke(args)
    Handler-->>Client: 返回Call对象
    deactivate Handler

3. ServiceMethod 解析过程

sequenceDiagram
    participant Handler as InvocationHandler
    participant SMParser as ServiceMethod.parseAnnotations()
    participant RFParser as RequestFactory.parseAnnotations()
    participant HttpMethod as HttpServiceMethod
    participant CallAdapter as CallAdapter.Factory
    participant Converter as Converter.Factory

    Handler->>SMParser: parseAnnotations(retrofit, method)
    activate SMParser

    SMParser->>RFParser: RequestFactory.parseAnnotations()
    activate RFParser

    Note over RFParser: 解析方法注解
    RFParser->>RFParser: 解析HTTP方法注解<br/>@GET/@POST/@PUT/@DELETE等
    RFParser->>RFParser: 提取HTTP方法和相对URL
    RFParser->>RFParser: 解析@Headers注解
    RFParser->>RFParser: 是否包含body(@Body)
    RFParser->>RFParser: 是否multipart(@Multipart)
    RFParser->>RFParser: 是否form-encoded(@FormUrlEncoded)

    Note over RFParser: 解析方法参数注解
    loop 遍历每个参数
        RFParser->>RFParser: 解析参数注解<br/>@Path/@Query/@Header<br/>@Body/@Field等
        RFParser->>RFParser: 创建ParameterHandler
    end

    RFParser-->>SMParser: 返回RequestFactory
    deactivate RFParser

    SMParser->>SMParser: 获取方法返回类型
    SMParser->>CallAdapter: 查找匹配的CallAdapter
    activate CallAdapter

    loop 遍历CallAdapterFactories
        CallAdapter->>CallAdapter: factory.get(returnType, annotations)
        alt 找到匹配的Factory
            CallAdapter-->>SMParser: 返回CallAdapter
        end
    end
    deactivate CallAdapter

    SMParser->>Converter: 查找响应体Converter
    activate Converter

    Converter->>Converter: 提取响应类型
    loop 遍历ConverterFactories
        Converter->>Converter: factory.responseBodyConverter()
        alt 找到匹配的Converter
            Converter-->>SMParser: 返回Converter
        end
    end
    deactivate Converter

    SMParser->>HttpMethod: 创建HttpServiceMethod
    activate HttpMethod
    HttpMethod->>HttpMethod: 保存RequestFactory
    HttpMethod->>HttpMethod: 保存CallAdapter
    HttpMethod->>HttpMethod: 保存ResponseConverter
    HttpMethod-->>SMParser: 返回HttpServiceMethod
    deactivate HttpMethod

    SMParser-->>Handler: 返回ServiceMethod
    deactivate SMParser

4. OkHttpCall 创建和执行流程

sequenceDiagram
    participant Client as 开发者代码
    participant ServiceMethod as HttpServiceMethod
    participant OkHttpCall as OkHttpCall
    participant RequestFactory as RequestFactory
    participant RealCall as okhttp3.Call
    participant Callback as Retrofit Callback

    Client->>ServiceMethod: invoke(args)
    activate ServiceMethod

    ServiceMethod->>RequestFactory: create(args)
    activate RequestFactory

    Note over RequestFactory: 构建OkHttp Request
    RequestFactory->>RequestFactory: 应用RequestBuilder
    RequestFactory->>RequestFactory: 构建完整URL(baseUrl + 相对路径)

    loop 处理每个参数
        RequestFactory->>RequestFactory: parameterHandler.apply(requestBuilder, value)
        Note over RequestFactory: @Path替换URL路径<br/>@Query添加查询参数<br/>@Header添加请求头<br/>@Body设置请求体
    end

    RequestFactory->>RequestFactory: requestBuilder.build()
    RequestFactory-->>ServiceMethod: 返回okhttp3.Request
    deactivate RequestFactory

    ServiceMethod->>OkHttpCall: new OkHttpCall(requestFactory, args, callFactory, responseConverter)
    activate OkHttpCall
    OkHttpCall->>OkHttpCall: 保存请求参数
    OkHttpCall-->>ServiceMethod: 返回OkHttpCall实例
    deactivate OkHttpCall

    ServiceMethod->>ServiceMethod: adapt(okHttpCall, args)
    Note over ServiceMethod: 使用CallAdapter包装
    ServiceMethod-->>Client: 返回适配后的Call
    deactivate ServiceMethod

    Note over Client,Callback: 异步执行请求
    Client->>OkHttpCall: enqueue(callback)
    activate OkHttpCall

    OkHttpCall->>OkHttpCall: 创建okhttp3.Request
    OkHttpCall->>RealCall: callFactory.newCall(request)
    activate RealCall
    RealCall-->>OkHttpCall: 返回okhttp3.Call
    deactivate RealCall

    OkHttpCall->>RealCall: call.enqueue(okhttp3.Callback)
    activate RealCall

    Note over RealCall: OkHttp执行网络请求
    RealCall->>RealCall: 通过拦截器链执行
    RealCall->>RealCall: 返回okhttp3.Response

    RealCall-->>OkHttpCall: onResponse(call, response)
    deactivate RealCall

    alt 响应成功(2xx)
        OkHttpCall->>OkHttpCall: parseResponse(rawResponse)
        OkHttpCall->>OkHttpCall: converter.convert(responseBody)
        OkHttpCall->>Callback: callback.onResponse(call, Response.success(body))
    else 响应失败(非2xx)
        OkHttpCall->>OkHttpCall: 创建错误ResponseBody
        OkHttpCall->>Callback: callback.onResponse(call, Response.error(errorBody))
    end

    deactivate OkHttpCall

    Callback-->>Client: 处理响应结果

5. 同步请求执行流程

sequenceDiagram
    participant Client as 开发者代码
    participant OkHttpCall as OkHttpCall
    participant RealCall as okhttp3.Call
    participant Converter as ResponseConverter

    Client->>OkHttpCall: execute()
    activate OkHttpCall

    OkHttpCall->>OkHttpCall: 检查是否已执行<br/>(executed标志)

    alt 已经执行过
        OkHttpCall-->>Client: throw IllegalStateException
    end

    OkHttpCall->>OkHttpCall: executed = true
    OkHttpCall->>OkHttpCall: 创建okhttp3.Request
    OkHttpCall->>RealCall: callFactory.newCall(request)
    activate RealCall
    RealCall-->>OkHttpCall: 返回Call实例
    deactivate RealCall

    OkHttpCall->>RealCall: rawCall.execute()
    activate RealCall

    Note over RealCall: 同步阻塞执行
    RealCall->>RealCall: 经过拦截器链
    RealCall->>RealCall: 发送网络请求
    RealCall->>RealCall: 等待响应

    RealCall-->>OkHttpCall: 返回okhttp3.Response
    deactivate RealCall

    OkHttpCall->>OkHttpCall: parseResponse(rawResponse)
    activate OkHttpCall

    alt HTTP状态码 2xx
        OkHttpCall->>Converter: convert(response.body())
        activate Converter
        Converter->>Converter: 解析响应体<br/>(如JSON转对象)
        Converter-->>OkHttpCall: 返回解析后的对象
        deactivate Converter
        OkHttpCall->>OkHttpCall: Response.success(body, rawResponse)
    else HTTP状态码非2xx
        OkHttpCall->>Converter: convert(response.errorBody())
        activate Converter
        Converter-->>OkHttpCall: 返回错误体
        deactivate Converter
        OkHttpCall->>OkHttpCall: Response.error(errorBody, rawResponse)
    end

    OkHttpCall-->>Client: 返回Response
    deactivate OkHttpCall

6. 协程支持机制（Suspend Function）

sequenceDiagram
    participant Client as 客户端协程
    participant Handler as InvocationHandler
    participant ServiceMethod as SuspendForResponse
    participant Call as OkHttpCall
    participant Continuation as Continuation
    participant Dispatcher as 协程调度器
    participant OkHttp as OkHttpClient
    participant Converter as ResponseConverter

    Note over Client,Handler: 调用suspend函数
    Client->>Handler: invoke(suspendMethod, args)
    activate Handler

    Handler->>Handler: 检测到suspend函数
    Handler->>Handler: 提取Continuation参数
    Handler->>Continuation: 获取协程上下文
    activate Continuation

    Handler->>ServiceMethod: loadServiceMethod(method)
    activate ServiceMethod

    Note over ServiceMethod: 识别为suspend函数
    ServiceMethod->>ServiceMethod: 检查返回类型
    ServiceMethod->>ServiceMethod: 创建SuspendForResponse
    ServiceMethod-->>Handler: 返回ServiceMethod
    deactivate ServiceMethod

    Handler->>ServiceMethod: invoke(args)
    activate ServiceMethod

    ServiceMethod->>Call: 创建OkHttpCall
    activate Call
    Call-->>ServiceMethod: 返回Call对象
    deactivate Call

    Note over ServiceMethod: 不使用CallAdapter
    ServiceMethod->>Call: awaitResponse()
    activate Call

    Note over Call,Dispatcher: 协程挂起点
    Call->>Call: suspendCancellableCoroutine
    Call->>Dispatcher: 切换到IO线程
    activate Dispatcher

    Dispatcher->>OkHttp: call.enqueue()
    activate OkHttp

    Note over OkHttp: 异步执行网络请求
    OkHttp->>OkHttp: 拦截器链处理
    OkHttp->>OkHttp: 发送HTTP请求
    OkHttp->>OkHttp: 接收响应

    OkHttp-->>Dispatcher: onResponse回调
    deactivate OkHttp

    Dispatcher->>Call: 恢复协程
    deactivate Dispatcher

    Call->>Call: parseResponse()
    alt HTTP 2xx
        Call->>Converter: convert(responseBody)
        activate Converter
        Converter->>Converter: JSON转对象
        Converter-->>Call: 返回解析后的对象
        deactivate Converter
        Call->>Continuation: resume(result)
    else HTTP非2xx
        Call->>Call: 创建HttpException
        Call->>Continuation: resumeWithException(error)
    end

    Call-->>ServiceMethod: 返回结果
    deactivate Call

    ServiceMethod-->>Handler: 返回结果
    deactivate ServiceMethod

    Handler-->>Client: 协程恢复执行
    deactivate Handler
    deactivate Continuation

    Client->>Client: 继续执行后续代码

7. 协程取消机制

sequenceDiagram
    participant Scope as CoroutineScope
    participant Job as Job
    participant Continuation as CancellableContinuation
    participant Call as OkHttpCall
    participant OkHttp as okhttp3.Call

    Note over Scope,Job: 协程启动
    Scope->>Job: launch/async
    activate Job
    Job->>Call: 执行suspend函数
    activate Call

    Call->>Continuation: suspendCancellableCoroutine
    activate Continuation

    Continuation->>Continuation: invokeOnCancellation回调
    Note over Continuation: 注册取消监听器

    Call->>OkHttp: call.enqueue()
    activate OkHttp
    Note over OkHttp: 网络请求进行中

    Note over Scope,Job: 用户取消协程
    Scope->>Job: job.cancel()
    activate Scope
    Job->>Job: 标记为已取消

    Job->>Continuation: cancel()
    Continuation->>Continuation: 触发invokeOnCancellation

    Continuation->>Call: 执行取消回调
    Call->>OkHttp: call.cancel()
    OkHttp->>OkHttp: 取消网络请求
    OkHttp-->>Call: IOException(Canceled)
    deactivate OkHttp

    Call->>Continuation: resumeWithException(CancellationException)
    Continuation-->>Job: 抛出CancellationException
    deactivate Continuation
    deactivate Call

    Job-->>Scope: 协程已取消
    deactivate Job
    deactivate Scope

8. CallAdapter 工作机制

sequenceDiagram
    participant Retrofit as Retrofit
    participant Factory as CallAdapter.Factory
    participant Adapter as CallAdapter
    participant TargetType as 目标类型对象

    Note over Retrofit,Factory: 第一阶段：查找CallAdapter
    Retrofit->>Retrofit: callAdapter(returnType, annotations)
    activate Retrofit

    loop 遍历callAdapterFactories
        Retrofit->>Factory: factory.get(returnType, annotations, retrofit)
        activate Factory
        Factory->>Factory: 检查返回类型是否匹配

        alt 类型匹配
            Factory->>Adapter: 创建CallAdapter实例
            activate Adapter
            Adapter->>Adapter: 设置responseType
            Adapter-->>Factory: 返回Adapter
            deactivate Adapter
            Factory-->>Retrofit: 返回CallAdapter
            Note over Retrofit: 找到匹配的Adapter停止遍历
        else 类型不匹配
            Factory-->>Retrofit: 返回null
            Note over Retrofit: 继续查找下一个Factory
        end
        deactivate Factory
    end

    Retrofit-->>Retrofit: 返回匹配的CallAdapter
    deactivate Retrofit

    Note over Adapter,TargetType: 第二阶段：适配Call对象
    Retrofit->>Adapter: adapt(call)
    activate Adapter

    alt DefaultCallAdapter
        Adapter->>Adapter: 直接返回Call对象
        Adapter-->>Retrofit: 返回Call
    else ExecutorCallbackCall
        Adapter->>TargetType: new ExecutorCallbackCall
        activate TargetType
        Note over TargetType: 包装Call在指定Executor回调
        TargetType-->>Adapter: 返回包装后的Call
        deactivate TargetType
        Adapter-->>Retrofit: 返回Call
    else CompletableFutureCallAdapter
        Adapter->>TargetType: new CompletableFutureCallAdapter
        activate TargetType
        Note over TargetType: 将Call转为CompletableFuture
        TargetType-->>Adapter: 返回CompletableFuture
        deactivate TargetType
        Adapter-->>Retrofit: 返回CompletableFuture
    else RxJava3CallAdapter
        Adapter->>TargetType: 创建Observable/Single
        activate TargetType
        Note over TargetType: 将Call转为RxJava类型
        TargetType-->>Adapter: 返回Observable
        deactivate TargetType
        Adapter-->>Retrofit: 返回Observable
    end

    deactivate Adapter

9. Converter 转换机制

sequenceDiagram
    participant Retrofit as Retrofit
    participant Factory as Converter.Factory
    participant Converter as Converter
    participant ResponseBody as ResponseBody
    participant TargetType as 目标对象

    Note over Retrofit,Factory: 第一阶段：查找ResponseConverter
    Retrofit->>Retrofit: nextResponseBodyConverter()
    activate Retrofit

    loop 遍历converterFactories
        Retrofit->>Factory: factory.responseBodyConverter()
        activate Factory
        Factory->>Factory: 检查是否支持该类型转换

        alt 支持转换
            Factory->>Converter: 创建Converter实例
            activate Converter
            Converter-->>Factory: 返回Converter
            deactivate Converter
            Factory-->>Retrofit: 返回Converter
            Note over Retrofit: 找到匹配的Converter
        else 不支持
            Factory-->>Retrofit: 返回null
            Note over Retrofit: 继续查找
        end
        deactivate Factory
    end

    Retrofit-->>Retrofit: 返回匹配的Converter
    deactivate Retrofit

    Note over Converter,TargetType: 第二阶段：转换响应体
    Retrofit->>Converter: convert(responseBody)
    activate Converter

    Converter->>ResponseBody: value.source()
    activate ResponseBody
    ResponseBody-->>Converter: 返回BufferedSource
    deactivate ResponseBody

    alt GsonConverter
        Converter->>Converter: gson.getAdapter(type)
        Converter->>Converter: adapter.read(jsonReader)
        Note over Converter: JSON → Java对象
    else MoshiConverter
        Converter->>Converter: moshi.adapter(type)
        Converter->>Converter: adapter.fromJson(source)
        Note over Converter: JSON → Java对象
    else JacksonConverter
        Converter->>Converter: objectMapper.readValue()
        Note over Converter: JSON → Java对象
    else ProtobufConverter
        Converter->>Converter: adapter.decode(bytes)
        Note over Converter: Protobuf → Java对象
    else ScalarsConverter
        Converter->>Converter: responseBody.string()
        Note over Converter: 直接返回字符串
    end

    Converter->>TargetType: 创建对象实例
    activate TargetType
    TargetType-->>Converter: 返回实例
    deactivate TargetType

    Converter-->>Retrofit: 返回转换后的对象
    deactivate Converter

    Note over Retrofit,Factory: 第三阶段：请求体转换
    Retrofit->>Factory: requestBodyConverter()
    activate Factory
    Factory->>Converter: 创建RequestConverter
    activate Converter
    Converter-->>Factory: 返回Converter
    deactivate Converter
    Factory-->>Retrofit: 返回Converter
    deactivate Factory

    Retrofit->>Converter: convert(value)
    activate Converter

    alt GsonConverter
        Converter->>Converter: gson.toJson(value)
        Note over Converter: Java对象 → JSON
        Converter->>Converter: RequestBody.create()
    else MoshiConverter
        Converter->>Converter: adapter.toJson(value)
        Converter->>Converter: RequestBody.create()
    end

    Converter-->>Retrofit: 返回RequestBody
    deactivate Converter

10. 请求参数处理机制

sequenceDiagram
    participant RF as RequestFactory
    participant Builder as RequestBuilder
    participant Handler as ParameterHandler
    participant Request as okhttp3.Request

    RF->>Builder: new RequestBuilder(httpMethod, baseUrl, relativeUrl)
    activate Builder
    Builder->>Builder: 初始化HttpUrl.Builder
    Builder->>Builder: 初始化Headers
    deactivate Builder

    Note over RF,Handler: 应用每个参数
    loop 遍历方法参数
        RF->>Handler: parameterHandlers[i].apply(builder, args[i])
        activate Handler

        alt @Path参数
            Handler->>Handler: 验证值不为null
            Handler->>Handler: 替换URL路径中的占位符
            Handler->>Builder: relativeUrl.replace("{name}", value)
            Builder->>Builder: 更新URL
        else @Query参数
            Handler->>Handler: 转换值为字符串
            Handler->>Builder: addQueryParam(name, value)
            Builder->>Builder: urlBuilder.addQueryParameter(name, value)
        else @QueryMap参数
            loop 遍历Map条目
                Handler->>Builder: addQueryParam(key, value)
            end
        else @Header参数
            Handler->>Handler: 转换值为字符串
            Handler->>Builder: addHeader(name, value)
            Builder->>Builder: headersBuilder.add(name, value)
        else @HeaderMap参数
            loop 遍历Map条目
                Handler->>Builder: addHeader(key, value)
            end
        else @Body参数
            Handler->>Handler: 使用Converter转换对象
            Handler->>Handler: converter.convert(value)
            Handler->>Builder: setBody(requestBody)
            Builder->>Builder: 保存RequestBody
        else @Field参数 (FormEncoded)
            Handler->>Handler: 转换值为字符串
            Handler->>Builder: addFormField(name, value)
            Builder->>Builder: formBuilder.add(name, value)
        else @FieldMap参数
            loop 遍历Map条目
                Handler->>Builder: addFormField(key, value)
            end
        else @Part参数 (Multipart)
            Handler->>Handler: 创建MultipartBody.Part
            Handler->>Builder: addPart(part)
            Builder->>Builder: multipartBuilder.addPart(part)
        else @PartMap参数
            loop 遍历Map条目
                Handler->>Builder: addPart(key, value)
            end
        else @Url参数
            Handler->>Handler: 解析完整URL
            Handler->>Builder: setRelativeUrl(url)
            Builder->>Builder: 覆盖URL
        end

        Handler-->>RF: 参数应用完成
        deactivate Handler
    end

    Note over RF,Request: 构建最终Request
    RF->>Builder: build()
    activate Builder

    Builder->>Builder: 构建完整URL<br/>baseUrl + relativeUrl + queryParams
    Builder->>Builder: 构建Headers

    alt 有RequestBody
        Builder->>Builder: 设置Content-Type
        Builder->>Builder: 添加Body
    else FormEncoded
        Builder->>Builder: formBuilder.build()
        Builder->>Builder: 设置Content-Type: application/x-www-form-urlencoded
    else Multipart
        Builder->>Builder: multipartBuilder.build()
        Builder->>Builder: 设置Content-Type: multipart/form-data
    end

    Builder->>Request: new Request.Builder().url(url).headers(headers).method(httpMethod, body).build()
    activate Request
    Request-->>Builder: 返回Request实例
    deactivate Request

    Builder-->>RF: 返回okhttp3.Request
    deactivate Builder

11. 完整的内部调用链路图

flowchart TD
    Start([调用API接口方法]) --> ProxyInvoke[动态代理拦截调用<br/>InvocationHandler.invoke]

    ProxyInvoke --> CheckCache{ServiceMethod<br/>是否缓存?}

    CheckCache -->|已缓存| GetCached[从缓存获取]
    CheckCache -->|未缓存| ParseMethod[解析方法注解<br/>ServiceMethod.parseAnnotations]

    ParseMethod --> ParseRequest[创建RequestFactory<br/>解析HTTP方法和参数注解]
    ParseRequest --> FindCallAdapter[查找CallAdapter<br/>遍历CallAdapterFactories]
    FindCallAdapter --> FindConverter[查找Converter<br/>遍历ConverterFactories]
    FindConverter --> CreateSM[创建HttpServiceMethod<br/>封装请求信息]
    CreateSM --> CacheIt[缓存ServiceMethod]

    CacheIt --> GetCached
    GetCached --> InvokeSM[调用ServiceMethod.invoke]

    InvokeSM --> CreateRequest[创建okhttp3.Request<br/>应用所有参数处理器]
    CreateRequest --> CreateOkCall[创建OkHttpCall<br/>封装OkHttp调用]
    CreateOkCall --> AdaptCall[使用CallAdapter.adapt<br/>转换为目标类型]

    AdaptCall --> ReturnCall([返回Call对象])

    ReturnCall --> ExecuteChoice{执行方式?}

    ExecuteChoice -->|enqueue| AsyncExec[异步执行<br/>call.enqueue]
    ExecuteChoice -->|execute| SyncExec[同步执行<br/>call.execute]

    AsyncExec --> CreateOkCall2[创建okhttp3.Call]
    SyncExec --> CreateOkCall2

    CreateOkCall2 --> OkHttpChain[OkHttp拦截器链]

    OkHttpChain --> Interceptor1[RetryAndFollowUpInterceptor<br/>重试和重定向]
    Interceptor1 --> Interceptor2[BridgeInterceptor<br/>添加基础Headers]
    Interceptor2 --> Interceptor3[CacheInterceptor<br/>缓存处理]
    Interceptor3 --> Interceptor4[ConnectInterceptor<br/>建立连接]
    Interceptor4 --> Interceptor5[CallServerInterceptor<br/>发送请求]

    Interceptor5 --> Network[网络服务器]
    Network --> RawResponse[返回okhttp3.Response]

    RawResponse --> ParseResponse[解析响应<br/>OkHttpCall.parseResponse]

    ParseResponse --> CheckStatus{HTTP状态码?}

    CheckStatus -->|2xx成功| ConvertSuccess[使用Converter转换响应体<br/>ResponseBodyConverter.convert]
    CheckStatus -->|非2xx| ConvertError[转换错误体<br/>保留原始响应]

    ConvertSuccess --> WrapSuccess[包装为Response.success]
    ConvertError --> WrapError[包装为Response.error]

    WrapSuccess --> Callback[回调结果]
    WrapError --> Callback

    Callback --> End([执行完成])

    style Start fill:#e1f5e1
    style End fill:#ffe1e1
    style Network fill:#e1f0ff
    style ProxyInvoke fill:#fff4e1
    style OkHttpChain fill:#f0e1ff

核心类关系说明

1. Retrofit

• 职责: 框架入口，管理所有配置
• 核心方法:
  • create(Class<T> service): 创建API接口代理实例
  • callAdapter(Type returnType, Annotation[] annotations): 查找匹配的CallAdapter
  • nextResponseBodyConverter(...): 查找匹配的Converter

2. ServiceMethod

• 职责: 封装API方法的所有信息
• 子类:
  • HttpServiceMethod: 普通HTTP方法的实现
  • SuspendForResponse: suspend函数的特殊实现
  • SuspendForBody: 直接返回响应体的suspend函数
• 核心信息:
  • RequestFactory: 请求工厂
  • CallAdapter: 调用适配器（suspend函数不使用）
  • Converter: 响应转换器
• suspend函数特性:
  • 自动检测方法签名中的Continuation参数
  • 使用suspendCancellableCoroutine实现挂起
  • 支持协程取消传播到OkHttp Call

3. RequestFactory

• 职责: 根据方法注解和参数创建OkHttp Request
• 核心成员:
  • httpMethod: HTTP方法(GET/POST等)
  • relativeUrl: 相对URL
  • headers: 请求头
  • parameterHandlers: 参数处理器数组

4. ParameterHandler

• 职责: 处理单个方法参数，应用到RequestBuilder
• 实现类:
  • Path: 处理@Path注解
  • Query: 处理@Query注解
  • Header: 处理@Header注解
  • Body: 处理@Body注解
  • Field: 处理@Field注解(FormEncoded)
  • Part: 处理@Part注解(Multipart)

5. OkHttpCall

• 职责: Retrofit的Call实现，内部委托给OkHttp的Call
• 核心方法:
  • enqueue(Callback<T> callback): 异步执行
  • execute(): 同步执行
  • parseResponse(okhttp3.Response rawResponse): 解析响应
  • await(): 协程扩展，挂起并等待响应
  • awaitResponse(): 协程扩展，返回完整Response对象
• 协程支持:
  • 使用suspendCancellableCoroutine挂起协程
  • 注册invokeOnCancellation回调处理协程取消
  • 协程取消时自动调用call.cancel()取消网络请求

6. CallAdapter

• 职责: 将Call转换为其他类型
• 内置实现:
  • DefaultCallAdapter: 直接返回Call
  • ExecutorCallbackCall: 在指定Executor回调
  • CompletableFutureCallAdapter: 转换为CompletableFuture (Java 8)
• 第三方实现:
  • RxJava3CallAdapter: 转换为Observable/Single
  • CoroutineCallAdapter: Kotlin协程支持

7. Converter

• 职责: 对象与HTTP请求/响应体之间的转换
• 实现:
  • GsonConverter: JSON ↔ Java对象 (Gson)
  • MoshiConverter: JSON ↔ Java对象 (Moshi)
  • JacksonConverter: JSON ↔ Java对象 (Jackson)
  • ProtobufConverter: Protobuf ↔ Java对象
  • ScalarsConverter: 原始类型(String/primitives)

工作流程总结

标准流程（Call/RxJava）

1. 构建阶段: 创建Retrofit实例，配置baseUrl、OkHttpClient、Converter、CallAdapter
2. 代理创建: 使用JDK动态代理为API接口创建实例
3. 方法解析: 首次调用时解析方法注解，创建ServiceMethod并缓存
4. 请求构建: 应用参数处理器，将方法参数转换为OkHttp Request
5. 类型适配: 使用CallAdapter将OkHttpCall转换为目标返回类型
6. 执行请求: 委托给OkHttp执行网络请求
7. 响应转换: 使用Converter将响应体转换为Java对象
8. 结果回调: 通过Callback或其他方式返回结果

协程流程（Suspend Function）

1. 构建阶段: 同标准流程
2. 代理创建: 同标准流程
3. 方法解析: 识别suspend函数，提取Continuation参数，创建SuspendForResponse
4. 请求构建: 同标准流程
5. 协程挂起: 使用suspendCancellableCoroutine挂起协程，不经过CallAdapter
6. 异步执行: 在IO调度器上通过OkHttp异步执行网络请求
7. 响应转换: 同标准流程，使用Converter转换
8. 协程恢复: 通过Continuation.resume恢复协程执行
9. 取消支持: 协程取消时自动取消OkHttp请求

协程 vs 标准调用对比

特性	标准Call	Suspend函数
返回类型	Call<T>	直接返回T
调用方式	enqueue(callback)	直接调用，自动挂起
线程切换	通过Executor	通过协程调度器
取消机制	手动调用call.cancel()	协程取消自动传播
错误处理	Callback回调	try-catch或协程异常处理
CallAdapter	需要	不需要
生命周期	手动管理	绑定CoroutineScope

Retrofit vs OkHttp 职责划分

组件	职责
Retrofit	注解解析、类型转换、动态代理、CallAdapter适配
OkHttp	HTTP连接、请求发送、响应接收、拦截器链、缓存

Retrofit基于OkHttp构建，专注于提供类型安全的HTTP API抽象，而将底层网络通信委托给OkHttp处理。

---

本文档深入剖析了Retrofit框架的内部工作机制，涵盖了从API接口创建到请求执行的完整流程。