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: 检测运行平台
(Android/Java8/默认) Platform-->>Builder: 返回Platform实例 deactivate Platform Builder->>Executor: platform.defaultCallbackExecutor() activate Executor Executor-->>Builder: 返回默认Executor
(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方法逻辑
- 处理Object方法
- 处理default方法
- 处理接口方法 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方法注解
@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: 解析参数注解
@Path/@Query/@Header
@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路径
@Query添加查询参数
@Header添加请求头
@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: 检查是否已执行
(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: 解析响应体
(如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
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[动态代理拦截调用
InvocationHandler.invoke] ProxyInvoke --> CheckCache{ServiceMethod
是否缓存?} CheckCache -->|已缓存| GetCached[从缓存获取] CheckCache -->|未缓存| ParseMethod[解析方法注解
ServiceMethod.parseAnnotations] ParseMethod --> ParseRequest[创建RequestFactory
解析HTTP方法和参数注解] ParseRequest --> FindCallAdapter[查找CallAdapter
遍历CallAdapterFactories] FindCallAdapter --> FindConverter[查找Converter
遍历ConverterFactories] FindConverter --> CreateSM[创建HttpServiceMethod
封装请求信息] CreateSM --> CacheIt[缓存ServiceMethod] CacheIt --> GetCached GetCached --> InvokeSM[调用ServiceMethod.invoke] InvokeSM --> CreateRequest[创建okhttp3.Request
应用所有参数处理器] CreateRequest --> CreateOkCall[创建OkHttpCall
封装OkHttp调用] CreateOkCall --> AdaptCall[使用CallAdapter.adapt
转换为目标类型] AdaptCall --> ReturnCall([返回Call对象]) ReturnCall --> ExecuteChoice{执行方式?} ExecuteChoice -->|enqueue| AsyncExec[异步执行
call.enqueue] ExecuteChoice -->|execute| SyncExec[同步执行
call.execute] AsyncExec --> CreateOkCall2[创建okhttp3.Call] SyncExec --> CreateOkCall2 CreateOkCall2 --> OkHttpChain[OkHttp拦截器链] OkHttpChain --> Interceptor1[RetryAndFollowUpInterceptor
重试和重定向] Interceptor1 --> Interceptor2[BridgeInterceptor
添加基础Headers] Interceptor2 --> Interceptor3[CacheInterceptor
缓存处理] Interceptor3 --> Interceptor4[ConnectInterceptor
建立连接] Interceptor4 --> Interceptor5[CallServerInterceptor
发送请求] Interceptor5 --> Network[网络服务器] Network --> RawResponse[返回okhttp3.Response] RawResponse --> ParseResponse[解析响应
OkHttpCall.parseResponse] ParseResponse --> CheckStatus{HTTP状态码?} CheckStatus -->|2xx成功| ConvertSuccess[使用Converter转换响应体
ResponseBodyConverter.convert] CheckStatus -->|非2xx| ConvertError[转换错误体
保留原始响应] 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接口创建到请求执行的完整流程。