罗罗编程学习记录
本页内容 展开查看

07.1.1.9.2 Retrofit 与 kotlinx.serialization

所属:全栈开发面试题库 / 07 端侧与桌面开发 / 07.1 原生移动开发 / 07.1.1 Android / 07.1.1.9 网络栈与序列化

本节要解决的问题

本节沿接口调用栈展开:Retrofit 如何用动态代理把注解接口方法解析成 OkHttp 请求,Converter 与 CallAdapter 如何完成序列化与返回类型适配,suspend 方法如何执行与取消,再到 kotlinx.serialization 的配置、未知字段、默认值与多态处理,最后覆盖框架选型、统一错误模型、Mock 契约测试与日志安全。版本基线:Retrofit 2.9+/2.11、kotlinx.serialization 1.7.x、OkHttp 4.x、Android 14 / compileSdk 34;版本敏感行为标「待确认」并写明验证点。

07.1.1.9.2-001 Retrofit 如何把接口方法变成可执行的网络请求?

一句话结论

Retrofit 为接口生成动态代理实现,调用方法时解析方法与参数上的注解,构造 Request,交给底层 OkHttp 客户端执行,再通过 Converter 把响应体解析成声明的返回类型。

概念解释

接口只声明方法签名与注解,不写实现。代理在方法被调用时做注解解析、参数绑定、请求构建;响应回来后经 CallAdapter 适配为 Call、suspend 结果或 Flow 等类型。整个过程可拆成「解析方法 → 构造请求 → 执行交换 → 转换响应」四段。

原理流程

调用 api.method(args)
  → 动态代理解析方法注解与参数注解
  → 组装 OkHttp Request
  → OkHttp 执行交换 → Response
  → Converter 反序列化 → CallAdapter 适配返回类型

代码或图示

interface ApiService {
    @GET("user")
    suspend fun getUser(): User
}

常见误区

  • 以为 Retrofit 自己发 HTTP;它只是接口层封装,底层仍是 OkHttp Call。
  • 把接口当成普通类 new;实例由 Retrofit.create() 生成。

追问

  • 接口方法必须有注解吗?答:是,缺少 HTTP 方法注解代理解析会失败。
  • Retrofit 实例与接口实例是什么关系?答:一个 Retrofit 实例可 create 多个接口,共享 baseUrl、工厂与底层客户端。

07.1.1.9.2-002 动态代理在 Retrofit 中承担什么角色?

一句话结论

Proxy.newProxyInstance 为接口生成运行时代理对象,所有方法调用进入 invoke,由 Retrofit 查找该方法缓存的解析结果并执行请求逻辑;业务代码看到的是普通接口方法调用。

概念解释

动态代理避免为每个接口手写实现类。Retrofit 对每个方法只解析一次注解并缓存 ServiceMethod,后续调用复用解析结果。invoke 内把参数值绑定到方法解析出的参数处理器,再构建请求执行。

原理流程

Retrofit.create(Api::class.java)
  → 动态代理 invoke(proxy, method, args)
  → 查/建 ServiceMethod 解析结果
  → 绑定参数 → 构造 Call → 转换返回

代码或图示

val retrofit = Retrofit.Builder()
    .baseUrl("https://example.com/")
    .build()
val api = retrofit.create(ApiService::class.java)

常见误区

  • 认为每次调用都重新解析注解;解析结果有缓存。
  • 在接口里写默认方法(default method)时期望被网络代理处理;代理只拦截抽象接口方法。

追问

  • ServiceMethod 缓存的粒度是什么?答:按接口方法维度缓存解析结果,具体缓存结构以版本实现为准(待确认)。
  • 代理对象持有什么引用?答:持有 Retrofit 实例引用,注意避免反向持有造成泄漏。

07.1.1.9.2-003 方法注解 @GET/@POST/@PUT/@DELETE 如何映射到 HTTP 方法?

一句话结论

方法上的 HTTP 方法注解给出请求方法与相对路径,Retrofit 据此确定 Request 的 method 与 URL 路径;方法注解与参数注解组合完成完整请求。

概念解释

@GET("users") 等注解的 value 是相对路径,与 baseUrl 拼接;方法名不参与请求构造。HTTP 方法语义遵循协议:GET/HEAD 无体,POST/PUT/PATCH 可带体。注解缺失或与体注解冲突时在解析阶段报错。

原理流程

@GET("users/{id}") → Method=GET,path=users/{id}
@POST("orders")    → Method=POST,path=orders
baseUrl + 相对路径 → 完整 URL

代码或图示

@GET("users/{id}")
suspend fun getUser(@Path("id") id: String): User

@POST("orders")
suspend fun createOrder(@Body body: OrderRequest): OrderResponse

常见误区

  • 路径以 / 开头覆盖 baseUrl 的路径段;相对路径拼接规则需注意。
  • GET 方法加 @Body,注解组合非法。

追问

  • HEAD 请求用哪个注解?答:@HEAD。
  • 方法注解的路径可以留空吗?答:路径由 @Url 参数提供时可留空;规则以版本文档为准(待确认)。

07.1.1.9.2-004 @Path 与 @Query 如何处理 URL 占位与查询参数?

一句话结论

@Path 替换路径段占位符,@Query 追加 key=value 查询参数;两者分别作用于 URL 的路径部分与查询串,编码规则由 Retrofit 统一处理。

概念解释

@Path("id") 对应路径里的 {id},值做路径编码;@Query("page") 拼到 ?page=1,可重复追加多值。@Encoded 变体控制是否二次编码。空值与 null 查询参数的处理按配置与版本行为而定。

原理流程

@GET("users/{id}") getUser(@Path("id") id, @Query("page") page)
→ /users/123?page=2

代码或图示

@GET("search")
suspend fun search(@Query("q") keyword: String, @Query("tag") tags: List<String>): List<Item>

常见误区

  • 把路径参数塞进 @Query,路径占位符未替换导致 404。
  • 手动对 @Path 值编码,造成双重编码。

追问

  • 查询参数为 null 时会被省略吗?答:按版本与配置行为处理,null 是否保留空值需实测确认(待确认)。
  • 多值查询参数如何拼?答:List/数组形式按重复 key 拼接,编码规则由 Retrofit 处理。

07.1.1.9.2-005 @QueryMap 与 @FieldMap 适用什么场景?

一句话结论

参数集合动态不定时用 @QueryMap 拼查询参数、@FieldMap 拼表单字段;两者都是 Map 形式批量绑定,避免方法签名上罗列大量固定参数。

概念解释

@QueryMap 作用于 URL 查询串,@FieldMap 作用于表单体(需配合 @FormUrlEncoded)。Map 的 key 作为参数名,value 作为值;嵌套与编码规则按实现处理。动态筛选条件、多端可选参数适合用 Map。

原理流程

@QueryMap mapOf("a" to "1", "b" to "2") → ?a=1&b=2
@FieldMap mapOf(...) → 表单体 a=1&b=2

代码或图示

@FormUrlEncoded
@POST("login")
suspend fun login(@FieldMap fields: Map<String, String>): Token

常见误区

  • 在 JSON 接口上用 @FieldMap;表单字段只用于编码表单体。
  • Map value 传复杂对象,未约定序列化格式导致编码异常。

追问

  • Map 值可为 null 吗?答:null 条目的处理按版本行为,建议在业务层过滤。
  • @QueryMap 能控制编码吗?答:有 encoded 变体控制是否对值编码,具体注解名以版本为准(待确认)。

07.1.1.9.2-006 @Body 如何序列化请求体?

一句话结论

@Body 标注的参数由请求体 Converter 序列化为报文(JSON/表单等),序列化框架由注册的 Converter.Factory 按类型选择;方法需对应可带体的 HTTP 方法。

概念解释

@Body 对象不经过 @Field 编码,而是交给 requestBodyConverter 生成 RequestBody。JSON 场景下由序列化框架把对象编码成 JSON 字节并设置 Content-Type。Body 对象的字段可见性、可空性直接影响序列化结果。

原理流程

@Body req: OrderRequest
  → Converter 选工厂 → 序列化为 RequestBody(JSON)
  → 写入请求体

代码或图示

@POST("orders")
suspend fun createOrder(@Body req: OrderRequest): OrderResponse

常见误区

  • GET/HEAD 方法使用 @Body,注解组合非法。
  • Body 对象含未序列化的运行时字段,发出非预期报文。

追问

  • 同一接口能既有 @Body 又有 @Field 吗?答:不能混用体编码方式,体只能有一种形式。
  • 如何发送原始 JSON 字符串?答:可用 RequestBody 直接作为参数,绕过对象序列化。

07.1.1.9.2-007 @Header/@Headers/@HeaderMap 如何声明请求头?

一句话结论

@Header 给单个参数动态绑定头,@Headers 在方法上静态声明固定头,@HeaderMap 批量绑定头 Map;头值在出站请求前由桥接层与业务头合并。

概念解释

静态头用 @Headers("X-Version: 1") 写死在方法上;动态头用 @Header("Token") 从参数取值;@HeaderMap 适合一组动态头。同名头多值由追加方式处理。鉴权、追踪头通常在客户端拦截器统一追加,避免每个方法重复声明。

原理流程

静态 @Headers → 固定头
@Header 参数 → 动态头
@HeaderMap → 批量头
→ 合并进 Request.Builder

代码或图示

@Headers("X-Client: android")
@GET("profile")
suspend fun profile(@Header("Authorization") token: String): Profile

常见误区

  • 头名大小写重复定义导致覆盖或多值混乱。
  • 把敏感令牌写进静态注解,明文留在代码与混淆产物中。

追问

  • 方法头与拦截器头谁优先?答:按追加与覆盖规则处理,同名头最终值取决于叠加顺序,需实测确认(待确认)。
  • @Header 值为 null 会怎样?答:null 值通常跳过该头,具体行为以版本为准(待确认)。

07.1.1.9.2-008 @Url 动态覆盖基础地址时要注意什么?

一句话结论

@Url 参数提供完整或相对 URL,覆盖方法注解中的路径;使用动态地址时要注意 baseUrl 拼接规则、证书与路由归属,以及多域名在连接池与安全策略上的隔离。

概念解释

方法注解路径为空时,@Url 给出目标地址。完整 URL 直接使用;相对地址仍与 baseUrl 拼接。动态域名可能脱离原网关,证书固定、代理策略与连接复用都要按新域名评估。

原理流程

@GET suspend fun call(@Url url: String)
url 完整:直接使用
url 相对:拼接到 baseUrl

代码或图示

@GET
suspend fun fetch(@Url fullUrl: String): Data

常见误区

  • 动态 URL 仍期望复用原网关连接;跨域名需新路由与证书校验。
  • 拼接相对路径时开头 / 导致丢失 baseUrl 路径段。

追问

  • 动态地址来自服务端下发安全吗?答:需做域名白名单校验,避免被指向不可信地址。
  • @Url 能与 @Path 同用吗?答:地址由 @Url 提供时路径占位规则按实现处理,建议避免混用。

07.1.1.9.2-009 @FormUrlEncoded 与 @Multipart 有何区别?

一句话结论

@FormUrlEncoded 提交 application/x-www-form-urlencoded 键值对,配合 @Field/@FieldMap;@Multipart 提交 multipart/form-data,配合 @Part/@PartMap,用于文件与多部分混合上传。

概念解释

表单编码把键值对拼成 key=value&...,适合普通提交;多部分把每个字段与文件作为独立 part,带各自 Content-Type 与文件名,适合上传二进制。两者互斥,方法上只能声明一种编码。

原理流程

@FormUrlEncoded + @Field → 表单键值对体
@Multipart + @Part(文件) + @Part(字段) → 多部分体

代码或图示

@Multipart
@POST("upload")
suspend fun upload(
    @Part file: MultipartBody.Part,
    @Part("desc") desc: RequestBody
): UploadResult

常见误区

  • JSON 接口误加 @FormUrlEncoded,请求体编码错误。
  • 文件 part 忘记指定文件名与类型,服务端解析失败。

追问

  • 表单字段值类型有限制吗?答:@Field 绑定字符串或可转字符串类型;复杂对象应走 @Body JSON。
  • 多部分上传大文件如何避免全量进内存?答:part 基于流式 RequestBody 提供字节,不要把文件读成字节数组再传。

07.1.1.9.2-010 @Part/@PartMap 如何构造多部分上传?

一句话结论

@Part 声明单个部分(文件用 MultipartBody.Part,字段用带类型的 RequestBody),@PartMap 批量绑定字段部分;各部分独立命名、编码与类型。

概念解释

文件部分需要文件名、媒体类型与流;普通字段部分是键值对。MultipartBody.Part 手动构造 header 与 body。多部分顺序按参数顺序排列。上传进度需在 RequestBody 写入流中统计。

原理流程

@Part file: Part        → 文件部分
@Part("desc") body: RequestBody → 字段部分
→ MultipartBody 按顺序拼装各 part

代码或图示

val part = MultipartBody.Part.createFormData(
    "avatar", "a.jpg", fileBody
)

常见误区

  • 把文件字节塞进 @Part("key") String,二进制被按文本编码损坏。
  • Part 的 Content-Type 缺失,服务端无法识别文件类型。

追问

  • 上传进度怎么拿?答:自定义 RequestBody 在 writeTo 中按已写字节/总长回调进度。
  • 多 part 字段名重复允许吗?答:按协议支持重复字段名,服务端解析为准。

07.1.1.9.2-011 @Field 与 @Body 在表单/JSON 场景如何选择?

一句话结论

提交编码表单用 @Field(配合 @FormUrlEncoded);提交结构化 JSON 用 @Body;两者对应不同 Content-Type 与编码方式,不能在同一请求混用。

概念解释

@Field 是扁平键值对,由表单编码器拼装;@Body 是整个对象交给序列化框架编码成 JSON。接口契约决定选型:服务端接收表单就用 Field,接收 JSON 就用 Body。混用会导致请求体格式与 Content-Type 不一致。

原理流程

表单:@FormUrlEncoded + @Field/@FieldMap
JSON:@Body 对象 + JSON Converter

代码或图示

@FormUrlEncoded
@POST("token")
suspend fun token(@Field("grant_type") type: String): Token

@POST("profile")
suspend fun updateProfile(@Body req: ProfileRequest): Profile

常见误区

  • 一个方法里既有 @Field 又有 @Body,体编码冲突。
  • 用 @Body 传 Map 却期待表单编码。

追问

  • 表单也能发嵌套结构吗?答:表单是扁平键值对,嵌套需约定字段名编码;复杂结构优先 JSON。
  • 登录令牌换发通常用哪种?答:常见表单 application/x-www-form-urlencoded,以服务端契约为准。

07.1.1.9.2-012 注解解析发生在什么时候:调用时还是接口加载时?

一句话结论

方法注解在首次调用该方法时解析并缓存(懒加载),后续调用复用解析结果;不是 create 接口时一次性解析全部方法。

概念解释

Retrofit 为每个方法生成并缓存 ServiceMethod,首次调用承担解析成本,之后只做参数绑定与请求构建。这意味着未被调用的方法不产生解析开销;接口方法签名错误通常在首次调用该方法时才暴露。

原理流程

首次调用 method
  → 解析注解/返回类型/参数 → 构建并缓存 ServiceMethod
后续调用 → 复用缓存 → 绑定参数执行

代码或图示

create(Api) 不解析方法
method() 首次调用 → 解析 + 缓存

常见误区

  • 以为接口创建时就校验所有方法签名;错误可能延迟到首次调用。
  • 高频调用方法仍担心重复解析;解析结果已缓存。

追问

  • 解析成本体现在哪?答:注解读取、类型推断、Converter/CallAdapter 查找,首次调用可观察到小幅耗时。
  • 如何提前暴露签名错误?答:启动后对关键接口做一次空调用校验,或在测试环境加载全部接口方法。

07.1.1.9.2-013 接口方法的返回类型如何被解析成 Call 类型?

一句话结论

Retrofit 读取方法返回类型(含泛型),交由 CallAdapter.Factory 匹配能否适配;适配成功把原始 Call<T> 转成声明类型(Call<T>、T、Response<T>、suspend 结果等)。

概念解释

返回类型决定 CallAdapter 选择:原生 Call<T> 用默认适配;suspend 方法由协程适配处理;自定义类型需要注册对应工厂。泛型参数 <T> 同时决定响应 Converter 反序列化的目标类型。类型不被任何工厂适配时抛解析异常。

原理流程

方法返回 Type
  → 遍历 CallAdapter.Factory 匹配
  → 匹配成功:adapt(原始 Call) → 声明类型
  → 无匹配:抛异常

代码或图示

interface Api {
    @GET("a") fun a(): Call<A>
    @GET("b") suspend fun b(): B
}

常见误区

  • 返回类型泛型缺失(如裸 Call),Converter 拿不到目标类型。
  • 注册了 Converter 却没注册对应 CallAdapter,返回类型无法适配。

追问

  • Response<T> 由谁适配?答:默认 CallAdapter 支持,响应包装为 Response<T> 以暴露状态码与错误体。
  • Flow 返回类型需要什么?答:需注册支持 Flow 的 CallAdapter 工厂,具体依赖以版本生态为准(待确认)。

07.1.1.9.2-014 泛型返回类型在代理层如何保留与解析?

一句话结论

Java/Kotlin 反射能拿到方法的泛型返回类型(Type,含 ParameterizedType),Retrofit 据此知道 List<User> 的元素类型并传给 Converter;类型擦除导致的裸类型会丢失泛型参数。

概念解释

Converter 反序列化需要知道完整目标类型,例如 Response<List<Item>>。Retrofit 把方法返回的 Type 传递给工厂生成适配;若返回裸 List 或 Response,元素类型不可推断,转换会失败或退化为通用结构。

原理流程

方法返回 Call<Response<List<Item>>>
  → Type 含 ParameterizedType 链
  → CallAdapter 提取 T = Response<List<Item>>
  → Converter 按 List<Item> 反序列化

代码或图示

@GET("items")
suspend fun items(): Response<List<Item>>

常见误区

  • 用 List<*> 或裸类型作为返回,元素类型丢失。
  • 自定义泛型包装层未保留完整 Type,Converter 推断失败。

追问

  • 协程 suspend 返回如何保留泛型?答:suspend 函数的返回类型在反射中可见,适配器按其解析,不依赖挂起函数签名本身。
  • 类型实化(reified)能帮上忙吗?答:Retrofit 接口方法按反射类型解析;reified 泛型工具多用于自定义适配层。

07.1.1.9.2-015 方法上的注解与参数注解如何组合成 Request?

一句话结论

方法注解提供 HTTP 方法、路径、静态头与编码形式;参数注解把实参绑定到路径、查询、头、体或部分;两者在 ServiceMethod 解析后协同组装出完整 Request。

概念解释

解析阶段把方法注解与每个参数的注解对应到参数处理器;调用时实参填入处理器,处理器按规则修改 URL、头或体。注解组合必须自洽:方法编码与体注解匹配,参数位置与占位符对应。

原理流程

方法注解:method/path/headers/encoding
参数注解:@Path/@Query/@Header/@Body/@Part...
调用 → 参数处理器填充 → Request.Builder 组装

代码或图示

@Headers("X-Trace: 1")
@POST("users/{id}/avatar")
suspend fun avatar(
    @Path("id") id: String,
    @Header("X-Size") size: Long,
    @Part file: MultipartBody.Part
)

常见误区

  • 参数缺少注解,Retrofit 不知道如何绑定该实参。
  • @Path 名与占位符不一致,解析失败。

追问

  • 注解冲突检测在哪一步?答:ServiceMethod 解析阶段(首次调用),非法组合抛 IllegalArgumentException 类异常。
  • 非注解参数允许存在吗?答:不允许,所有参数都需可被注解处理器绑定。

07.1.1.9.2-016 Retrofit 接口可以继承或组合吗?

一句话结论

接口可继承父接口,方法与注解沿继承链保留;多接口组合通常通过多模块分别 create 后在业务层聚合,Retrofit 不自动合并多个接口定义。

概念解释

继承接口时子接口继承父方法注解与签名;公共方法可抽到基础接口。组合场景下,一个 Retrofit 实例可创建多个 Service 接口实例,对外由统一 API 门面聚合。注意继承带来的注解覆盖与泛型约束要清晰。

原理流程

BaseApi(公共方法)→ UserApi : BaseApi → Retrofit.create(UserApi::class)
多 Service:create(UserApi) + create(OrderApi) → 门面聚合

代码或图示

interface BaseApi {
    @GET("ping") suspend fun ping(): Ack
}
interface UserApi : BaseApi {
    @GET("user") suspend fun user(): User
}

常见误区

  • 期待 Retrofit 把多个接口的方法合并成一个代理对象。
  • 父接口方法返回类型泛型被子类抹掉,导致适配失败。

追问

  • 接口默认方法会被代理执行吗?答:动态代理拦截抽象方法;默认方法行为按代理实现处理,避免在接口默认方法里写网络逻辑。
  • 模块化如何拆接口?答:按业务域分 Service 接口,共享 baseUrl 与 Converter/CallAdapter 配置。

07.1.1.9.2-017 同一个接口多个方法共用 baseUrl 时如何管理?

一句话结论

baseUrl 在 Retrofit.Builder 上统一配置,接口方法只写相对路径;多环境(开发/预发/生产)通过切换构建配置或运行时配置替换 baseUrl,避免硬编码进接口注解。

概念解释

baseUrl 决定默认域名与路径前缀,方法相对路径与之拼接。环境差异由构建变量或配置中心注入,接口定义保持环境无关。多域名接口用 @Url 单独指定,但要评估证书与路由隔离。

原理流程

构建配置 → baseUrl
Retrofit.Builder().baseUrl(url)
方法 @GET("path") → url + path

代码或图示

val retrofit = Retrofit.Builder()
    .baseUrl(BuildConfig.API_BASE_URL)
    .build()

常见误区

  • baseUrl 末尾漏 /,相对路径拼接丢失层级。
  • 把环境域名写死在方法注解里,切换环境要改代码。

追问

  • baseUrl 能运行时切换吗?答:可重建 Retrofit 实例或用动态 @Url;已创建的接口实例绑定旧配置。
  • 多网关域名如何组织?答:主网关走 baseUrl,特殊网关用 @Url 或独立 Retrofit 实例。

07.1.1.9.2-018 注解使用错误(如 GET 带 @Body)会在什么时候暴露?

一句话结论

非法注解组合在方法解析阶段抛异常,通常是首次调用该方法时;异常属于配置/编程错误,应在开发与测试阶段暴露,而不是线上触发。

概念解释

解析校验包括:HTTP 方法与体注解是否匹配、占位符与 @Path 是否对应、返回类型是否有适配工厂。这类错误不是网络失败,而是接口定义错误。由于解析懒加载,单测应覆盖各方法首次调用,避免线上冷启动到某页面才崩溃。

原理流程

首次调用非法方法
  → ServiceMethod 解析 → 注解/类型校验失败
  → 抛 IllegalArgumentException(类型以实现为准)

代码或图示

// 非法:GET 带 Body
@GET("search")
suspend fun bad(@Body query: Query): Result

常见误区

  • 只测成功接口,未覆盖冷门方法,签名错误带到线上。
  • 把注解校验异常当网络异常上报,错误分类失真。

追问

  • 能否启动期全量校验接口?答:可在测试/调试环境反射遍历接口方法触发解析;生产是否全量校验按启动耗时权衡。
  • 异常消息能定位到方法吗?答:异常通常携带方法签名信息,便于定位接口定义。

07.1.1.9.2-019 Converter.Factory 负责什么职责?

一句话结论

Converter.Factory 决定如何把请求对象编码为 RequestBody、把响应体解码为目标类型;按入参类型与返回类型匹配,是序列化框架接入 Retrofit 的扩展点。

概念解释

工厂提供两个转换入口:requestBodyConverter 处理 @Body 等出站编码,responseBodyConverter 处理入站解码。框架自带 JSON 工厂、字符串/原始类型工厂等;自定义编码(表单之外的协议、加密体)通过实现工厂接入。

原理流程

出站:对象 → requestBodyConverter → RequestBody
入站:ResponseBody → responseBodyConverter → T

代码或图示

interface Converter<F, T> {
    fun convert(value: F): T?
}

常见误区

  • 把序列化逻辑写进 CallAdapter;编码解码归 Converter。
  • 工厂不区分请求/响应方向,复用错误的转换逻辑。

追问

  • 工厂如何知道目标类型?答:解析方法时把完整 Type 传给工厂,工厂据此选择序列化器。
  • 多个工厂匹配顺序?答:按注册顺序遍历,第一个支持该类型的工厂生效。

07.1.1.9.2-020 CallAdapter.Factory 负责什么职责?

一句话结论

CallAdapter.Factory 决定如何把原始 Call<T> 适配成接口声明的返回类型(Call、suspend 结果、Response<T>、Flow 或自定义包装),不参与报文序列化。

概念解释

CallAdapter 管「返回形态」:线程调度、协桥接、取消映射、结果包装;Converter 管「内容转换」。两者正交。注册顺序决定类型匹配优先级,自定义返回类型需配套工厂。

原理流程

原始 Call<T>
  → CallAdapter.adapt(call)
  → 返回声明类型(suspend 结果 / Response / Flow / 自定义)

代码或图示

CallAdapter.Factory.get(Type) → 支持则返回 CallAdapter
adapt(Call<R>): 产出 R

常见误区

  • 用 Converter 处理返回类型包装;返回形态应由 CallAdapter 负责。
  • 自定义包装类型没注册工厂,方法解析即失败。

追问

  • 默认 CallAdapter 支持哪些类型?答:Call<T> 与 Response<T> 内建支持;suspend 与其他类型靠对应适配器。
  • CallAdapter 能切换线程吗?答:可在适配层调度,但 suspend 协程的线程切换由协程机制与适配器配合完成。

07.1.1.9.2-021 Converter 与 CallAdapter 的执行顺序是什么?

一句话结论

先有原始 Call 执行交换拿到 ResponseBody,CallAdapter 决定返回形态;Converter 在 Call 内部完成请求编码与响应解码。对外顺序可理解为:参数编码 → 执行 → 响应解码 → 类型适配。

概念解释

调用链:方法解析选 Converter 编码请求体;OkHttp 执行;响应由 Converter 解码为实体;CallAdapter 把结果包成声明类型。Converter 作用于报文内容,CallAdapter 作用于返回包装,两者在不同阶段介入。

原理流程

@Body 对象 → Converter 编码 → Request
  → Call 执行 → ResponseBody
  → Converter 解码 → T
  → CallAdapter 包装 → 声明返回类型

代码或图示

Factory 链:Converter(内容) + CallAdapter(形态) 并列注册,阶段分离

常见误区

  • 认为 CallAdapter 先于 Converter 处理响应;实际解码在内容层完成。
  • 在 CallAdapter 里直接读响应体,绕过 Converter 导致流被提前消费。

追问

  • 解码异常在哪一层暴露?答:Converter 抛异常,沿 Call 失败路径传播,由 CallAdapter 映射为对应返回/异常。
  • 自定义工厂如何同时处理编码与解码?答:一个 Factory 可同时实现两个入口。

07.1.1.9.2-022 如何添加自定义 Converter 处理特殊类型?

一句话结论

实现 Converter.Factory,覆写请求/响应转换方法,对目标类型返回自定义 Converter,在 Retrofit 构建时按顺序 addConverterFactory 注册。

概念解释

典型场景:自定义协议报文、特殊日期格式、加密体、通用包装解包。工厂先判断类型是否支持,不支持返回 null 让后续工厂处理。转换逻辑要处理异常并给出明确错误类型,便于上层分类。

原理流程

addConverterFactory(customFactory)
  → responseBodyConverter(type): 支持则返回 Converter
  → convert(ResponseBody): 解码为目标类型

代码或图示

class PlainTextFactory : Converter.Factory() {
    override fun responseBodyConverter(
        type: Type, annotations: Array<Annotation>, retrofit: Retrofit
    ): Converter<ResponseBody, *>? {
        if (type == String::class.java) return Converter { it.string() }
        return null
    }
}

常见误区

  • 工厂对不支持的类型抛异常而不是返回 null,阻断后续工厂。
  • 自定义 Converter 不关闭/消费响应体,连接无法复用。

追问

  • 自定义 Converter 能访问 Retrofit 配置吗?答:工厂方法收到 Retrofit 实例,可取全局配置与其他工厂。
  • 解包统一外层包装放 Converter 还是业务层?答:通用结构解包适合 Converter/适配层;业务码判断在业务层更清晰。

07.1.1.9.2-023 GsonConverterFactory / kotlinx-serialization ConverterFactory 如何接入?

一句话结论

在 Retrofit.Builder 上 addConverterFactory(...) 注册对应工厂:Gson 传 Gson 实例,kotlinx.serialization 传 Json 实例;工厂按类型选择序列化器完成编解码。

概念解释

接入步骤:引入序列化依赖与 Retrofit 适配工厂依赖,构造共享的 Json/Gson 实例配置好规则,注册工厂。工厂顺序影响类型匹配:通用原始类型工厂与 JSON 工厂按序搭配。具体依赖坐标以当前版本为准(待确认)。

原理流程

Retrofit.Builder()
  .addConverterFactory(Json.asConverterFactory(JsonConfiguration))
  .baseUrl(...)
  .build()

代码或图示

val json = Json { ignoreUnknownKeys = true }
val retrofit = Retrofit.Builder()
    .baseUrl(baseUrl)
    .addConverterFactory(json.asConverterFactory("application/json".toMediaType()))
    .build()

常见误区

  • 只加序列化核心库,漏了 Retrofit 适配工厂依赖。
  • 每个接口方法新建 Json 实例,配置不统一且重复开销。

追问

  • 工厂顺序有讲究吗?答:有,先注册的工厂优先匹配;通常把 JSON 工厂放在处理原始类型的工厂之后或之前按需要确定。
  • 同一客户端能混用两种序列化框架吗?答:可按类型由不同工厂处理,但维护成本高,需明确分工。

07.1.1.9.2-024 多个 Converter.Factory 如何按类型选择?

一句话结论

Retrofit 按注册顺序遍历工厂,对目标类型询问 responseBodyConverter/requestBodyConverter,第一个返回非 null Converter 的工厂胜出;返回 null 表示不支持,继续下一个。

概念解释

注册顺序即优先级。常见组合:处理 ResponseBody/字符串等原始类型的工厂与 JSON 工厂搭配。若两个工厂都声称支持同一类型,先注册者生效。自定义工厂必须对不支持类型返回 null,否则阻断后续。

原理流程

类型 T
  → 工厂1.support(T)? 否 → null
  → 工厂2.support(T)? 是 → 采用

代码或图示

Retrofit.Builder()
    .addConverterFactory(ScalarFactory)     // 原始类型
    .addConverterFactory(jsonFactory)       // JSON 对象

常见误区

  • 把通用 JSON 工厂放在原始类型工厂之前,String 返回被当 JSON 解析。
  • 自定义工厂对所有类型都返回 Converter,覆盖了框架默认行为。

追问

  • 如何调试工厂匹配结果?答:在工厂 responseBodyConverter 打点记录类型与选择结果,单测覆盖各返回类型。
  • 同一类型能在不同接口用不同框架吗?答:类型相同则按注册顺序固定命中,需用不同包装类型区分。

07.1.1.9.2-025 CallAdapter 如何把 Call 适配成 suspend/Flow/自定义类型?

一句话结论

CallAdapter 在 adapt 中拿到原始 Call,按目标类型做桥接:suspend 场景挂起协程等待结果并映射取消,Flow 场景把结果转成流发射,自定义包装则封装成领域结果类型。

概念解释

适配层是返回类型与底层 Call 之间的翻译层。suspend 适配内部把异步回调桥接为挂起返回;Flow 适配管理流的订阅与取消;自定义 Result<T> 包装在适配层统一捕获异常。适配器要正确处理取消传播与资源释放。

原理流程

原始 Call<T>
  → suspend 适配器:挂起等待 → 返回 T / 抛异常
  → Flow 适配器:订阅 Call 结果 → emit
  → 自定义适配器:包装为 Result<T>

代码或图示

suspend fun <T> Call<T>.await(): T {
    // 内部 enqueue,回调恢复挂起;取消映射 call.cancel()
}

常见误区

  • 自定义适配器不处理协程取消,Call 泄漏继续跑。
  • 把异常包装吞掉,上层无法区分取消与失败。

追问

  • suspend 方法为什么不需要显式 Call?答:适配器在编译/运行层把挂起返回桥接到 Call,业务接口只声明 suspend 结果。
  • Flow 适配器如何支持多次发射?答:取决于接口语义;单次请求通常适配为单值或一次发射,持续数据流需配合其他数据源。

07.1.1.9.2-026 如何为自定义返回类型写 CallAdapter.Factory?

一句话结论

实现 CallAdapter.Factory,在 get 中判断返回类型是否为自定义包装(如 Result<T>),返回 CallAdapter;其 adapt 接收原始 Call 并包装为目标类型,处理异常与线程调度。

概念解释

工厂先解析泛型参数提取内部类型 T,再决定能否适配。适配器把 Call<T> 转成 Result<T>:成功包装数据,失败包装错误。注意保留泛型 Type 传递给 Converter,避免类型擦除。

原理流程

get(returnType): 解析 Result<T> → 匹配 → 返回 CallAdapter
adapt(call): 执行/订阅 call → 包装 Result

代码或图示

class ResultAdapterFactory : CallAdapter.Factory() {
    override fun get(type: Type, annotations: Array<Annotation>, retrofit: Retrofit) =
        when (getRawType(type)) {
            Result::class.java -> ResultAdapter<Any>(getParameterUpperBound(0, type as ParameterizedType))
            else -> null
        }
}

常见误区

  • 只判断原始类型不解析泛型参数,Converter 拿不到内部类型。
  • 适配器在错误分支未释放响应体或取消 Call。

追问

  • 自定义包装与 suspend 能共存吗?答:suspend 由专用适配器处理;自定义包装通常用于非挂起返回或配合上层协程。
  • 适配器能访问 Converter 结果吗?答:Call 执行后已是解码结果;适配器拿到的是适配前 Call,内容转换在 Call 内部完成。

07.1.1.9.2-027 Converter 抛异常会在哪一层被捕获?

一句话结论

Converter 在请求编码或响应解码时抛出的异常,沿 Call 失败路径传播:同步 execute 直接抛出,异步 enqueue 回调 onFailure,suspend 方法作为异常抛出给协程调用方。

概念解释

解码失败(JSON 结构不符、类型不匹配)属于转换异常,不是服务端业务错误。异常类型由序列化框架决定,上层应分类为「解析错误」与网络/业务错误区分。编码失败(请求对象非法)在出站阶段即抛出。

原理流程

解码异常 → Call 失败路径
  → execute: 抛出
  → enqueue: onFailure
  → suspend: 协程抛异常

代码或图示

try {
    val user = api.getUser()
} catch (e: SerializationException) {
    report("parse_error", e)
}

常见误区

  • 把解析异常上报成服务端 5xx,误导后端排查。
  • Converter 吞掉异常返回默认空对象,掩盖接口契约问题。

追问

  • 解码异常能在拦截器层看到吗?答:拦截器看到的是 Response 流;解码发生在其后,拦截器捕获不到转换异常。
  • 如何在 Converter 层保留原始报文用于排查?答:可在转换失败时附原始体摘要到异常,注意脱敏与体积。

07.1.1.9.2-028 响应体为空时 Converter 如何处理?

一句话结论

空体接口应返回 Unit/Void/Response<Unit> 或 ResponseBody;声明非空实体类型时 Converter 解析空体会失败。需按接口契约选择返回类型并在适配层容忍空体。

概念解释

204/205 或无体成功响应没有可解码内容。返回实体类型时解码空串会抛解析异常;常见做法:无体操作返回 Response<Unit> 或 Call<Unit>,在适配器/业务层判断状态码成功即可。注意 Response.body() 在空体时为 null。

原理流程

空体成功
  → 返回 Unit/Void:适配器不强制解码
  → 返回实体:Converter 解析空串 → 异常

代码或图示

@DELETE("user/{id}")
suspend fun deleteUser(@Path("id") id: String): Response<Unit>

常见误区

  • 删除/退出类接口声明返回实体,空体触发解析崩溃。
  • 把 204 当错误码处理。

追问

  • Void 与 Unit 在适配上有差异吗?答:Kotlin 常用 Unit;Void 兼容 Java 调用,具体适配行为以版本为准(待确认)。
  • 空体但带错误信息怎么读?答:非 2xx 时从 errorBody() 读取错误报文。

07.1.1.9.2-029 自定义 Converter 与 OkHttp 拦截器处理体有何分工?

一句话结论

拦截器在协议层处理原始报文(头、压缩、缓存、日志),Converter 在业务层把报文编码/解码为领域对象;体的格式转换归 Converter,传输横切归拦截器。

概念解释

拦截器看到的是 ResponseBody 流,适合做压缩、加解密、日志采样;Converter 面向类型与字段,负责 JSON/对象映射。混在拦截器里做字段解析会重复消费流并绕过序列化框架。加解密可放在拦截器改体,字段解析放 Converter。

原理流程

拦截器:原始字节/头横切(压缩、加密、日志)
Converter:字节 ↔ 对象(JSON 映射、校验)

代码或图示

请求:对象 → Converter 编码 → 拦截器可加密体
响应:拦截器可解密 → Converter 解码为对象

常见误区

  • 拦截器里手工解析 JSON 取字段,再把流交给 Converter 导致空体。
  • 把统一外层解包写进拦截器,拦截器重复消费响应体。

追问

  • 统一加密放哪层?答:加密请求体/解密响应体适合拦截器或专用 Converter;字段级脱敏在日志层。
  • 拦截器改写体后 Converter 还能解码吗?答:能,只要新体保留可解码格式与正确 Content-Type。

07.1.1.9.2-030 Retrofit 如何选择最合适的 Converter 工厂?

一句话结论

按注册顺序对目标类型逐个询问工厂,首个支持该类型的工厂被选用;「最合适」由工厂自身的类型判断决定,Retrofit 不做类型评分或最优匹配。

概念解释

没有多工厂竞争时的自动择优机制:先注册先得。因此工厂类型判断要精确,只声明支持的类型。调试时可在工厂入口打印类型,确认命中的是预期工厂。

原理流程

for factory in registeredFactories:
    c = factory.responseBodyConverter(type, ...)
    if c != null: 选用并停止

代码或图示

顺序:Scalar 工厂 → JSON 工厂 → 自定义工厂
类型匹配:String 命中 Scalar;DTO 命中 JSON

常见误区

  • 后注册的工厂期待覆盖先注册的;顺序相反。
  • 工厂类型判断过宽,抢占本应由其他工厂处理的类型。

追问

  • 运行时能调整工厂顺序吗?答:工厂在 Retrofit 构建期确定;调整需重建实例。
  • 类型匹配失败的表现?答:无工厂支持时抛解析异常,方法调用即失败。

07.1.1.9.2-031 返回 ResponseBody 与返回实体类型在转换上有何差异?

一句话结论

返回 ResponseBody 时跳过实体 Converter 解码,由业务层直接读流;返回实体类型时由 Converter 按类型解码。前者保留原始报文但需自行关流,后者类型安全但丢失原始字节。

概念解释

ResponseBody 是原始流类型,通常用于下载、透传或自行解析;实体类型走 JSON 解码得到强类型对象。直接返回流时要在使用后关闭,避免连接不归还。需要同时留档原始报文与解码对象时,在 Converter/适配层缓冲副本。

原理流程

ResponseBody:无实体解码,业务读流 → 关闭
实体 T:Converter 解码 → 强类型对象

代码或图示

@GET("file")
suspend fun download(): ResponseBody

@GET("user")
suspend fun user(): User

常见误区

  • 返回 ResponseBody 读完不关闭,连接泄漏。
  • 用 ResponseBody 接收 JSON 后再多次读取,流已消费为空。

追问

  • 下载进度怎么拿?答:在 source() 读取流时按已读字节统计,或包装 RequestBody/响应流。
  • 原始报文如何留档?答:缓冲副本采样记录,注意体积与脱敏,不能全量落盘。

07.1.1.9.2-032 Converter 工厂的 requestBodyConverter/responseBodyConverter 分别何时调用?

一句话结论

requestBodyConverter 在出站绑定 @Body 参数时调用,把对象编码为 RequestBody;responseBodyConverter 在入站解码响应时调用,把 ResponseBody 转为返回实体类型。

概念解释

两个入口方向相反、时机不同。请求编码发生在 Call 构建期;响应解码发生在拿到响应之后。工厂可只实现一个方向(如只处理响应解码)。类型参数分别来自请求对象类型与方法返回类型。

原理流程

出站:@Body 类型 → requestBodyConverter → RequestBody
入站:响应类型 → responseBodyConverter → T

代码或图示

override fun requestBodyConverter(type: Type, ...): Converter<*, RequestBody>?
override fun responseBodyConverter(type: Type, ...): Converter<ResponseBody, *>?

常见误区

  • 把响应解码逻辑写到请求入口,方向用反。
  • 只实现响应入口却期待 @Body 也被编码,出站落到默认处理。

追问

  • 两个入口能用同一序列化器吗?答:可以,共享配置但方向独立;自定义类型编解码可能不对称。
  • 工厂如何区分请求与响应注解?答:入口参数携带注解数组,可按字段/方法注解定制。

07.1.1.9.2-033 如何在 Converter 层做字段脱敏或包装?

一句话结论

出站可在编码前对对象字段裁剪/打标,入站可在解码后统一解包外层结构或补充缺省字段;字段级脱敏更适合日志层,报文层包装由 Converter/适配层处理。

概念解释

Converter 面向类型,适合做结构级转换:解包 {code, data, message} 外层、补默认值、过滤敏感字段。真正的日志脱敏不应污染业务模型,应在日志输出层按字段名掩码。包装解包要保证失败分支能拿到错误体。

原理流程

入站:原始 JSON → 解包外层 → 提取 data → 映射实体
出站:实体 → 字段裁剪 → 编码
日志:输出时按敏感键脱敏

代码或图示

// 解包示例:外层 Envelope<T>,成功取 data

常见误区

  • 在模型层塞脱敏后的假数据,污染真实业务状态。
  • 解包时忽略错误分支,code 非成功也强行返回 data。

追问

  • 统一外层放 Converter 还是 Repository?答:通用契约解包可放适配层;业务码判定与错误映射在 Repository/上层更清晰。
  • 字段重命名在哪做?答:序列化注解在模型层声明,Converter 按注解映射。

07.1.1.9.2-034 切换序列化框架需要改业务接口吗?

一句话结论

接口方法签名与 @Body/返回类型保持不变时,切换框架只改注册的 Converter.Factory 与模型注解;模型若依赖旧框架注解,需迁移到新框架的注解与配置。

概念解释

Retrofit 与 Converter 解耦:工厂替换后编解码规则随之改变。业务接口定义不直接绑定框架;但数据模型类上的序列化注解(@SerializedName 与 @SerialName)属于框架相关,迁移时要逐类改造。跨框架过渡期可按类型分工厂处理。

原理流程

旧工厂(Gson) → 新工厂(kotlinx)
模型注解迁移:@SerializedName → @SerialName
接口签名:不变

代码或图示

data class User(@SerialName("user_name") val name: String)

常见误区

  • 只换工厂不迁移模型注解,字段映射失效返回默认值或解析失败。
  • 新旧框架注解同时保留,混淆与行为不确定。

追问

  • 切换后如何回归?答:用 MockWebServer 固定报文,对比两种框架解析结果,覆盖缺字段/未知字段/多态场景。
  • 能渐进迁移吗?答:可按模块/类型逐步换工厂,过渡期注意模型不能同时依赖两套注解语义。

07.1.1.9.2-035 suspend 接口方法在 Retrofit 内部如何执行?

一句话结论

suspend 方法由专用 CallAdapter 桥接:内部把原始 Call 按异步方式提交,挂起当前协程等待回调,成功返回实体、失败抛异常;协程取消时映射为 Call 取消。

概念解释

业务侧看到的是挂起函数,不接触 Call 对象。适配器在内部 enqueue,回调恢复挂起协程;不阻塞调用线程。异常在协程内传播,由调用方 try/catch 处理。响应解码仍由 Converter 完成。

原理流程

suspend fun api(): T
  → 适配器内部 newCall().enqueue()
  → 挂起协程
  → onResponse: 解码 → 恢复协程返回 T
  → onFailure: 恢复协程抛异常

代码或图示

interface Api {
    @GET("user")
    suspend fun getUser(): User
}

常见误区

  • 以为 suspend 接口在主线程阻塞等待;实际内部异步桥接。
  • 不处理异常,协程崩溃传播到页面作用域。

追问

  • suspend 接口能拿原始 Response 吗?答:返回 Response<T> 即可,适配器同样支持包装响应。
  • 取消后回调还会更新 UI 吗?答:取消映射为失败,协程已取消,不应再向已取消作用域发 UI 更新。

07.1.1.9.2-036 suspend 函数取消如何映射到 Call 取消?

一句话结论

协程被取消时,suspend 适配器在 awaitCancellation 侧监听取消信号,调用底层 Call.cancel(),使在途请求中断;取消作为 CancellationException 在协程内传播。

概念解释

协程取消是协作式的:适配器在挂起点注册取消回调,协程取消时触发 Call 取消。底层 Call 在可中断点停止执行,回调以取消异常返回。业务层应把主动取消与真实失败区分开,不把取消当错误上报。

原理流程

协程 cancel()
  → 适配器收到取消信号
  → call.cancel()
  → 底层中断 → onFailure(取消)
  → 协程抛 CancellationException

代码或图示

viewModelScope.launch {
    try { api.getUser() } catch (e: CancellationException) { /* 正常取消 */ }
}

常见误区

  • 取消后仍把异常计入崩溃率/失败率。
  • 适配器未监听取消,Call 在后台继续占用连接与线程。

追问

  • 取消能中断正在读取的响应体吗?答:在可中断点停止;已进入流读取的部分按实现释放,连接归池或关闭。
  • 如何识别取消异常?答:判断 CancellationException 类型或 Call 取消标记,具体异常链以适配器实现为准(待确认)。

07.1.1.9.2-037 Response 与直接返回 T 有什么区别?

一句话结论

直接返回 T 时,非 2xx 会被当作失败抛出/走错误分支;返回 Response<T> 保留完整响应包装,可读取状态码、头与错误体,业务自行判断成败。

概念解释

Response<T> 是适配层包装:body() 存成功解码实体,errorBody() 存非成功报文,code()/headers() 暴露协议信息。需要处理 401、403、422 等可预期错误时用 Response<T>;只关心成功实体时直接返回 T 更简洁。

原理流程

返回 T:解码成功给实体;非 2xx/解码失败 → 异常
返回 Response<T>:包装 code/headers/body/errorBody,上层分支处理

代码或图示

@GET("user")
suspend fun getUser(): Response<User>

val resp = api.getUser()
if (resp.isSuccessful) { resp.body() } else { resp.errorBody() }

常见误区

  • 返回 Response<T> 却不判断 isSuccessful,把错误体当成功实体读。
  • 直接返回 T 又想读状态码,信息已丢失。

追问

  • Response.body() 成功时一定非空吗?答:成功但空体可能为 null,需判空。
  • 错误体也要反序列化吗?答:是,errorBody() 是原始流,需用对应 Converter 或手动读取。

07.1.1.9.2-038 如何通过 Response 读取状态码与响应头?

一句话结论

Response.code()/message() 读状态码与描述,Response.headers() 遍历响应头,isSuccessful 判断 2xx;头信息在包装层保留,不随 body 解码丢失。

概念解释

包装响应在解码实体之外保留协议元数据。常用于读取分页头、追踪头、令牌刷新头与调试信息。头值多值用对应方法遍历;注意头名大小写不敏感。读取错误体前先判断状态码,避免把成功体当错误体读。

原理流程

resp.code() / resp.message()
resp.headers("X-Page")
resp.isSuccessful

代码或图示

val resp = api.list()
val page = resp.headers["X-Page"]
if (resp.isSuccessful) { /* body */ }

常见误区

  • 成功路径上再去读 errorBody();成功时错误体通常为空。
  • 头名按大小写精确匹配;HTTP 头名大小写不敏感。

追问

  • 响应头里的新令牌如何更新?答:在成功/特定状态分支读取头并写入本地凭证存储。
  • 头信息能跨层传递到 Repository 吗?答:Response<T> 透传到上层即可;只返回 T 则头已丢弃。

07.1.1.9.2-039 错误分支:HTTP 非 2xx 时直接返回 T 会发生什么?

一句话结论

直接返回 T 时,非 2xx 响应不会被解码为实体,而是走失败路径抛异常(HTTP 错误类异常或包装异常);错误报文留在 errorBody,直接返回 T 的接口拿不到。

概念解释

默认适配把 2xx 视为成功解码 body();非 2xx 视为失败,错误体不自动转成 T。若业务需要处理 422 校验错误等可预期失败,应返回 Response<T> 读取错误体。异常类型由适配器实现决定(待确认具体类名)。

原理流程

非 2xx
  → 返回 T:失败路径,抛 HTTP 错误异常,errorBody 未被业务读取
  → 返回 Response<T>:包装错误,上层读 errorBody

代码或图示

// 直接返回 T:422 不会变成 User,而是失败
@POST("login") suspend fun login(@Body req: LoginReq): Token

常见误区

  • 期待非 2xx 也返回实体对象填充错误字段。
  • 不读错误体,无法定位服务端返回的校验原因。

追问

  • 适配器能把 4xx 也解码成实体吗?答:需自定义 CallAdapter/Converter 读取 errorBody 并映射,默认行为不这样做。
  • HTTP 错误异常包含状态码吗?答:默认异常通常携带响应码与消息,具体字段以版本为准(待确认)。

07.1.1.9.2-040 如何解析错误响应体(errorBody)?

一句话结论

拿到 Response<T> 后,非成功时用错误体 Converter 把 errorBody() 解码为错误模型;errorBody() 是一次性流,读取后关闭,错误模型包含业务错误码与提示。

概念解释

错误报文结构常与成功实体不同,需单独定义 ErrorResponse 模型。可用 Retrofit 实例的 responseBodyConverter 手动解码错误体,或在统一适配层处理。读取错误体注意 Content-Type 与空体情况。

原理流程

!resp.isSuccessful
  → errBody = resp.errorBody()
  → 用错误 Converter 解码为 ErrorResponse
  → 映射为领域错误

代码或图示

val err = retrofit.responseBodyConverter<ErrorBody>(
    ErrorBody::class.java, annotations
).convert(resp.errorBody()!!)

常见误区

  • 错误体反复读取;流只消费一次。
  • 成功模型当错误模型解码,字段对不上抛解析异常。

追问

  • 错误体为空怎么办?答:按状态码构造默认错误,不强行解码。
  • 统一错误模型在哪层解析?答:可在适配层或 Repository 层;解析结果映射为领域错误供 UI 消费。

07.1.1.9.2-041 suspend 方法抛异常的类型有哪些?

一句话结论

大致分三类:网络层异常(超时、连接、DNS、SSL 等 IOException)、HTTP 错误(非 2xx 由适配器包装)、解析异常(序列化框架抛序列化/格式异常);协程取消单独识别。

概念解释

分类决定重试与上报策略:网络瞬时故障可重试;HTTP 错误按状态码处理;解析错误多为契约问题需上报;取消不视为失败。异常可能被适配层包装,需穿透 cause 找到原始类型。

原理流程

IOException 子类:超时/连接/DNS/SSL
HTTP 错误:非 2xx 包装异常
SerializationException:结构/类型不符
CancellationException:主动取消

代码或图示

catch (e: CancellationException) { throw e }
catch (e: IOException) { /* 网络 */ }
catch (e: SerializationException) { /* 解析 */ }

常见误区

  • 只 catch 最外层异常,丢失 cause 中的真实网络类型。
  • 把解析异常当网络错误重试,无意义放大请求。

追问

  • 异常包装层级如何排查?答:沿 cause 链追溯原始异常,上报时保留类型链与消息摘要。
  • 4xx 属于哪类?答:HTTP 错误,服务端明确应答,通常不自动重试。

07.1.1.9.2-042 业务码成功但 HTTP 200 时如何统一判断?

一句话结论

HTTP 200 只表示传输成功,业务成败看响应体内的业务码;统一在数据层把业务码成功映射为数据,非成功映射为业务错误并携带提示与可选数据。

概念解释

常见契约是外层 { code, message, data }:HTTP 200 但 code 非成功仍属业务失败。判断逻辑集中在 Repository/适配层,避免每个页面重复判断。业务码与 HTTP 码分层记录,便于区分服务端故障与业务拒绝。

原理流程

HTTP 200 → 解码 Envelope
  → code 成功:返回 data
  → code 非成功:抛/包装 BusinessError(code, message)

代码或图示

data class Envelope<T>(val code: Int, val message: String?, val data: T?)

常见误区

  • 以 HTTP 200 作为业务成功唯一标准。
  • 业务失败时仍把 data 透传给 UI,展示脏数据。

追问

  • 业务码统一放模型还是拦截器?答:结构解包可在 Converter/适配层,业务码判定在数据层更易测试。
  • 特殊业务码(如需登录)如何处理?答:映射为固定领域错误,上层触发登录流程。

07.1.1.9.2-043 接口返回 nullable 实体时如何处理空体?

一句话结论

可空返回类型配合空体判断:成功但无数据时 body 为 null,业务层显式处理空态;非空类型遇到空体应视为契约异常,不要用默认值掩盖。

概念解释

Kotlin 可空性在接口签名上表达:User? 允许无数据;User 非空则响应必须有可解码实体。空体与显式空字段不同:空体是没有报文,空字段是报文中值为 null。模型字段可空性要与服务端契约对齐。

原理流程

空体成功 → body = null(可空类型)
非空类型遇空体 → 解码/适配异常

代码或图示

@GET("profile")
suspend fun profile(): Profile? // 可能无数据

常见误区

  • 服务端偶尔返回空体却声明非空类型,偶发解析崩溃。
  • 把字段缺失当成字段为 null,可空性判断混淆。

追问

  • 如何发现可空性与契约不符?答:Mock 报文与线上采样核对,解析异常按字段上报。
  • 缺省值与 null 怎么选?答:有合理默认值用默认值;真正可选用可空字段。

07.1.1.9.2-044 suspend 与 Call 混用在同一接口可以吗?

一句话结论

可以:同一 Service 接口中部分方法声明 suspend 返回,部分保留 Call<T>;各方法由对应 CallAdapter 独立适配,互不影响。

概念解释

适配器按方法返回类型分别匹配:suspend 走协程适配,Call<T> 走默认适配。混用便于渐进迁移:旧模块保留 Call,新接口用 suspend。但团队约定应统一风格,避免上层两套异步模型并存。

原理流程

方法 A:suspend fun a(): A  → 协程适配器
方法 B:fun b(): Call<B>    → 默认适配器

代码或图示

interface Api {
    @GET("a") suspend fun a(): A
    @GET("b") fun b(): Call<B>
}

常见误区

  • Call 方法忘记 enqueue/execute,请求未发出。
  • 混用导致上层回调风格与取消管理两套逻辑。

追问

  • 混用会影响 Converter 选择吗?答:不影响,Converter 按实体类型匹配。
  • 建议新代码用哪种?答:协程项目统一 suspend,Call 仅在兼容旧代码时保留。

07.1.1.9.2-045 协程取消后响应体还会被读取吗?

一句话结论

取消后适配器停止等待并取消 Call,未读取的响应体不再由业务消费;底层流在 Call 结束/取消时按实现释放,业务不应再访问已取消响应的 body。

概念解释

取消发生在响应到达前后结果不同:取消时尚未响应,请求中断;取消时响应头已到,体可能未读完。已取消的协程不继续解码。业务层在取消分支不读 body、不更新 UI。连接释放由客户端与适配器配合完成。

原理流程

取消 → call.cancel()
  → 未响应:中断建连/等待
  → 已到头部:停止读体,释放流
  → 协程以取消异常结束

代码或图示

catch (e: CancellationException) {
    // 不再读取 resp.body,不更新界面
    throw e
}

常见误区

  • 取消后仍在回调里解析 body,访问已释放流。
  • 适配器取消 Call 但未关闭已读到的体,造成连接泄漏。

追问

  • 取消能保证体完全读完再关吗?答:不保证,取消即中断;需要完整收尾的操作不应挂在可取消作用域。
  • 如何确认释放行为?答:结合 EventListener 连接释放事件与真机内存/连接数观察(待确认版本细节)。

07.1.1.9.2-046 如何在接口层返回 Result/Either 风格类型?

一句话结论

注册自定义 CallAdapter 把 Call<T> 适配为 Result<T>/Either<Err, T>:成功包装数据,失败包装错误类型;上层用密封结果类型分支处理,避免每层 try/catch。

概念解释

结果类型把成功与失败纳入返回值类型系统,编译器强制分支处理。适配层负责捕获网络/HTTP/解析异常并映射为错误侧;取消一般重新抛出不纳入结果。模型上定义密封 Result 与领域错误层级。

原理流程

Call<T> → 适配器
  → 成功:Result.Success(data)
  → 失败:Result.Failure(domainError)
  → 取消:抛 CancellationException

代码或图示

sealed interface Result<out T> {
    data class Success<T>(val data: T) : Result<T>
    data class Failure(val error: AppError) : Result<Nothing>
}

常见误区

  • 适配层吞掉取消异常包成 Failure,破坏协程取消语义。
  • 错误类型过粗,上层无法区分可重试与不可重试错误。

追问

  • Result 包装与 Response 如何选?答:需要读状态码/错误体用 Response<T>;纯领域结果用 Result 包装。
  • 适配层做错误映射还是 Repository 做?答:HTTP/网络分类可在适配层,领域语义映射在 Repository 层。

07.1.1.9.2-047 Response.body() 为 null 的常见原因?

一句话结论

常见原因:非 2xx 成功判定(body 仅成功时填充)、空体响应、解码后实体为 null、响应本身无数据;需结合状态码与错误体判断是哪一种。

概念解释

body() 只在 isSuccessful 且有可解码实体时非空;非成功时实体为 null,报文在 errorBody()。空体 2xx 也可能 body 为 null。模型字段 null 与 body 整体 null 是两层问题。

原理流程

非 2xx → body = null,errorBody 有值
2xx 空体 → body = null
2xx 有体但 data 字段为 null → body 非空,内部字段 null

代码或图示

val resp = api.getUser()
val user = resp.body() // 先判 isSuccessful 再取

常见误区

  • 不判 isSuccessful 直接 body()!!,非成功时崩溃。
  • 把 body 为 null 当成网络失败;可能只是空体成功。

追问

  • body 为 null 但 isSuccessful 怎么处理?答:按空态业务处理,必要时上报契约异常。
  • 如何区分空体与解析 null?答:结合 Content-Length/响应头与错误日志判断。

07.1.1.9.2-048 超时与取消在 suspend 链路上如何传播?

一句话结论

OkHttp 超时触发后 Call 失败,suspend 适配器把异常恢复给挂起协程;协程取消则反向取消 Call。两者都沿协程作用域向上传播,作用域取消后子协程与在途请求一并终止。

概念解释

超时是底层套接字/Call 失败,异常进入协程;取消是上层主动中断,映射为 Call 取消。传播路径:Call 失败 → 适配器恢复协程抛异常 → 作用域处理;作用域取消 → 子协程取消 → Call 取消。区分超时(可重试网络问题)与取消(主动行为)。

原理流程

超时 → onFailure(超时异常) → 协程抛超时异常
作用域取消 → 子协程取消 → call.cancel() → 取消异常

代码或图示

viewModelScope.launch {
    try { api.getUser() } catch (e: IOException) { /* 超时等网络 */ }
}

常见误区

  • 超时异常被当成业务失败弹错误框。
  • 作用域销毁后请求未取消,后台继续跑并回调已销毁页面。

追问

  • 超时后还能重试吗?答:仅对幂等接口、按退避策略重试;非幂等写接口谨慎。
  • 链路中多个协程取消顺序?答:父作用域取消向下传播,子协程依次取消,在途 Call 随之取消。

07.1.1.9.2-049 kotlinx.serialization 的核心模型是什么?

一句话结论

核心是由编译器插件为 @Serializable 类生成的序列化器(KSerializer),编码/解码按结构化描述(SerialDescriptor)在 Encoder/Decoder 与对象之间转换;不依赖反射读取字段。

概念解释

与反射框架运行时扫描字段不同,kotlinx.serialization 在编译期生成序列化逻辑:描述符列出字段名、类型与序号,序列化器按描述读写。JSON 格式由 Json 实例提供,模型与格式解耦,可换其他编码格式。

原理流程

@Serializable 类 → 编译器生成 KSerializer + SerialDescriptor
Json.encodeToString(serializer, obj)
Json.decodeFromString(serializer, str)

代码或图示

@Serializable
data class User(val name: String, val age: Int)

常见误区

  • 以为运行时靠反射读字段;核心产物是编译期生成的序列化器。
  • 普通类不加插件/标注就期望自动序列化。

追问

  • 序列化器生成在哪个阶段?答:Kotlin 编译器插件在编译期生成伴随序列化器,具体产物类名以实现为准(待确认)。
  • 模型与格式如何解耦?答:序列化器不绑定 JSON,可复用于其他格式编码。

07.1.1.9.2-050 @Serializable 标注与编译器插件做了什么?

一句话结论

@Serializable 标记类需要可序列化,编译器插件为其生成配套序列化器;插件还处理内置类型、集合与可空类型的编解码,手动编写序列化器用于特殊类型。

概念解释

插件在编译期根据主构造参数生成描述与读写逻辑;类属性需在主构造函数声明才能被自动序列化。嵌套 @Serializable 类型递归使用各自序列化器。无参构造、可变集合等边界行为按框架规则处理。

原理流程

@Serializable data class P(val a: A, val b: String)
  → 生成 P.serializer()
  → 嵌套 A 用 A 的序列化器

代码或图示

@Serializable
data class Article(val title: String, val tags: List<String>)

常见误区

  • 把不参与构造的内部属性纳入序列化预期;插件只处理构造参数。
  • 忘记应用序列化编译器插件,生成代码缺失导致编译错误。

追问

  • 编译器插件怎么配置?答:在模块构建脚本中应用 kotlinx.serialization 插件,具体坐标与写法以当前版本文档为准(待确认)。
  • 枚举/密封类可序列化吗?答:支持,各有对应规则与注解要求。

07.1.1.9.2-051 Json 配置有哪些常用项?

一句话结论

常用配置:ignoreUnknownKeys 忽略未知字段、coerceInputValues 把越界/非法枚举回退默认、isLenient 宽松解析、encodeDefaults 是否编码默认值、ignoreUnknownKeys 与命名策略等;通过 Json { ... } 构造共享实例。

概念解释

配置决定解析容错与输出形态:线上响应常多返回字段,ignoreUnknownKeys 避免解析失败;枚举/数值越界用 coerceInputValues 容错。宽松模式接受非严格 JSON。配置应全局统一,避免不同接口行为不一致。具体配置项名称与默认值以 1.7.x 文档为准(待确认)。

原理流程

val json = Json {
    ignoreUnknownKeys = true
    coerceInputValues = true
    encodeDefaults = false
}

代码或图示

容错:未知字段忽略;非法值回退默认
输出:默认值字段是否写出由 encodeDefaults 控制

常见误区

  • 线上关闭 ignoreUnknownKeys,服务端新增字段即解析崩溃。
  • 每个请求新建 Json 实例,配置不一致且重复开销。

追问

  • isLenient 什么时候开?答:接收非严格报文时;严格契约场景建议关闭以便暴露格式问题。
  • 配置能按接口覆盖吗?答:全局共享为主;特例可构造独立 Json 实例配合 Converter。

07.1.1.9.2-052 未知字段默认会怎样处理?如何配置忽略?

一句话结论

默认遇到模型未声明的字段会抛未知字段异常;设置 ignoreUnknownKeys = true 后忽略多余字段,保证服务端加字段不破坏客户端解析。

概念解释

向前兼容的关键配置:服务端迭代新增响应字段,老版本模型没有对应属性。开启忽略后解析跳过未知键;但要注意被忽略字段可能是业务需要的新数据,只是当前版本未建模。请求方向的多余字段不受此配置影响。

原理流程

JSON 含额外字段
  → ignoreUnknownKeys=false:抛 SerializationException
  → true:跳过未知键,按模型字段解码

代码或图示

val json = Json { ignoreUnknownKeys = true }

常见误区

  • 关闭忽略又不做版本兼容,线上一发新字段就崩溃。
  • 忽略未知字段后不关注服务端契约演进,漏掉应建模的新数据。

追问

  • 未知字段能记录日志排查吗?答:默认自动忽略不保留;需要审计需自定义解码器收集键名。
  • 未知嵌套对象也会被忽略吗?答:按对应层级规则处理,父对象被忽略时整体跳过。

07.1.1.9.2-053 缺失字段与默认值如何处理?

一句话结论

JSON 缺少模型字段时:字段有默认值则使用默认值(配合配置),无可空默认的必填字段抛缺失异常;可空字段缺省为 null 的行为取决于配置与字段声明。

概念解释

反序列化缺字段时,框架按构造参数默认值填充;没有默认值的非空类型必须在报文中出现。coerceInputValues 主要处理非法值回退默认,不等同于缺字段容错。请求编码时默认值字段是否写出由 encodeDefaults 控制。

原理流程

缺字段
  → 有默认值:用默认值
  → 无默认值 + 非空:抛缺失异常
  → 可空:null(按声明与配置)

代码或图示

@Serializable
data class Config(val timeout: Int = 10, val remark: String? = null)

常见误区

  • 非空必填字段指望框架给零值;缺省仍会报错。
  • 混淆「缺字段」与「字段为 null」,可空性设计不清。

追问

  • 数值缺失能给默认 0 吗?答:需在模型上写默认值;框架不自动把缺省补零。
  • 向后兼容新增必填字段怎么办?答:模型给默认值,避免老报文缺字段崩溃。

07.1.1.9.2-054 字段名与 JSON key 不一致用什么注解?

一句话结论

用 @SerialName("json_key") 标注模型属性,指定序列化与反序列化对应的 JSON 键名;不标注时默认使用属性原名。

概念解释

命名风格差异(驼峰属性与下划线报文)通过注解映射。@SerialName 同时作用于双向:编码写出指定键,解码读取指定键。枚举值与类鉴别字段也用该注解。多个属性不能映射同一 JSON 键。

原理流程

属性 user_name ↔ @SerialName("user_name")
编码:写出 user_name
解码:读取 user_name

代码或图示

@Serializable
data class User(@SerialName("user_name") val userName: String)

常见误区

  • 只在反序列化方向生效的错觉;注解双向生效。
  • 命名映射分散在属性上却不检查一致性,改报文时漏改。

追问

  • 有全局命名策略转换吗?答:框架支持的命名策略配置以版本文档为准(待确认);不确定时用显式注解。
  • 字段重命名后旧报文兼容吗?答:旧键无注解映射会缺失,需保留兼容映射或过渡版本。

07.1.1.9.2-055 @SerialName 在序列化与反序列化时如何生效?

一句话结论

注解值作为该属性在编码输出与解码输入中的键名;序列化器生成时把注解值写入描述符,编解码两侧都按该键名工作。

概念解释

与字段别名不同,@SerialName 是单值映射,不是多别名兼容。若历史报文用过不同键名,需要自定义解码逻辑或保留过渡字段。枚举常量同理:注解值为报文里的字面值。

原理流程

描述符中属性名 = @SerialName 值
encode:用该值写键
decode:按该值读键

代码或图示

@Serializable
enum class Role { @SerialName("admin") ADMIN }

常见误区

  • 期待一个属性同时接受多个 JSON 键;单注解只映射一个。
  • 编码后属性名与预期不符,检查注解是否写反方向。

追问

  • 多别名兼容怎么做?答:自定义序列化器或过渡期保留多个字段映射,按框架能力实现。
  • 注解能标在类上吗?答:类名注解用于多态鉴别等场景,属性注解用于字段名映射。

07.1.1.9.2-056 可空类型与缺失值在反序列化时的区别?

一句话结论

可空类型字段在报文显式为 null 时解码为 null;字段完全缺失时,有默认值用默认值,无默认值的可空属性行为按配置与实现处理;非空类型缺失则报错。

概念解释

null 是报文里存在的值,缺失是键不存在。两者路径不同:显式 null 走可空赋值;缺失走默认值逻辑。建模时要区分「服务端可能不下发」与「下发但为空」,对应默认值与可空性设计。

原理流程

"field": null  → 可空字段 = null
字段不存在     → 默认值 / 缺失处理
非空缺失       → 异常

代码或图示

@Serializable
data class Info(val label: String? = null)

常见误区

  • 以为可空字段缺失自动为 null 而不写默认值;行为需按版本确认(待确认)。
  • 把 null 与缺失混在同一分支判断,空态处理不一致。

追问

  • 如何兼容老版本缺字段?答:给可空/必填字段补默认值,避免缺失异常。
  • 显式 null 能触发默认值吗?答:不能,显式 null 覆盖默认值赋为 null。

07.1.1.9.2-057 列表、Map、嵌套对象如何序列化?

一句话结论

List<T>、Map<String, V> 与嵌套 @Serializable 对象由生成序列化器递归处理;元素/值类型需可序列化,集合空值与嵌套可空性按元素类型规则解码。

概念解释

集合直接作为属性类型声明即可,框架处理数组/对象映射;嵌套对象使用自身序列化器。Map 的键通常为字符串,复杂键需自定义。列表元素类型缺失或类型不符会在元素层级抛异常。

原理流程

List<Item>   → JSON 数组
Map<String, X> → JSON 对象
嵌套 Order → 递归用 Order 序列化器

代码或图示

@Serializable
data class Order(val items: List<Item>, val extras: Map<String, String>)

常见误区

  • 元素类型未标注可序列化,编译期即报错或运行缺序列化器。
  • 集合里混入未知类型,解码失败定位到元素层级。

追问

  • 列表为 null 与空列表如何区分?答:可空 List<T>? 区分 null 与 [];契约上明确使用哪种。
  • Map 值类型不匹配会怎样?答:解码到对应值时抛类型异常。

07.1.1.9.2-058 多态序列化如何注册子类与鉴别字段?

一句话结论

密封类/接口多态通过鉴别字段(如 type)区分子类,用 SerialName 标注子类鉴别名,或在 SerializersModule 中注册子类映射;解码时按鉴别值选择对应子类序列化器。

概念解释

开放多态需要注册模块告诉框架每个鉴别名对应哪个子类;密封类可由插件自动识别子类。鉴别字段名在类级配置。解码先读鉴别字段,再选子类器解码其余字段。子类字段与基类字段按结构组装。

原理流程

JSON { "type": "a", ... }
  → 按 type 查子类序列化器
  → 解码子类字段

代码或图示

@Serializable
sealed class Card {
    @SerialName("text") @Serializable data class Text(val text: String) : Card()
}

常见误区

  • 开放接口未注册子类,解码时找不到鉴别对应器。
  • 鉴别值与 @SerialName 不一致,子类匹配失败。

追问

  • 鉴别字段名怎么改?答:多态配置中指定类鉴别描述符字段名,具体 API 以版本为准(待确认)。
  • 未知子类类型如何兜底?答:配置容错或返回未知类型模型,避免直接崩溃。

07.1.1.9.2-059 sealed class 作为响应类型如何反序列化?

一句话结论

密封类响应按鉴别字段映射到具体子类,子类均标注可序列化;插件可自动收集密封子类,解码结果为密封类型引用,上层按子类分支处理。

概念解释

密封类的有限子类集合在编译期确定,多态解析比开放接口简单。响应外层用密封类型声明,内部按 type 区分卡片/消息等形态。新增子类需同步更新模型与上层分支。鉴别名缺失或不匹配会解码失败。

原理流程

@Serializable sealed class Msg
  → TextMsg / ImageMsg 子类
响应 Msg → 鉴别字段 → 具体子类实例

代码或图示

@Serializable
sealed class Msg {
    @SerialName("text") data class Text(val body: String) : Msg()
    @SerialName("image") data class Image(val url: String) : Msg()
}

常见误区

  • 密封子类漏标 @Serializable,自动收集缺失。
  • 上层 when 分支未覆盖新子类,编译/运行遗漏处理。

追问

  • 密封类能用于请求体吗?答:可以,编码同样按鉴别字段输出;子类选择在业务侧确定。
  • 未知版本下发新子类怎么办?答:加兜底子类或容错解析,避免老版本崩溃。

07.1.1.9.2-060 @SerialName 与枚举序列化有什么坑?

一句话结论

枚举用 @SerialName 映射报文字面值;未匹配的枚举值默认抛异常,可配合 coerceInputValues 与默认枚举兜底。注意枚举名与报文值大小写、别名差异。

概念解释

枚举序列化把常量映射为字符串;注解值是报文字面值。服务端新增枚举值时老客户端解码失败,需容错策略:未知值回退到约定默认项或密封类/字符串模型。枚举不能有多个常量映射同一报文值。

原理流程

报文 "admin" → @SerialName("admin") ADMIN
未匹配值 → 异常(或 coerce 回退默认)

代码或图示

@Serializable
enum class Status {
    @SerialName("on") ON,
    @SerialName("off") OFF,
    UNKNOWN
}

常见误区

  • 直接用枚举名做报文值,大小写/命名风格不一致导致解码失败。
  • 服务端新增枚举值未做兼容,老版本崩溃。

追问

  • 枚举未知值如何兜底?答:配置 coerce 并提供默认项;或模型用字符串 + 业务层映射。
  • 枚举编码输出的是注解值还是常量名?答:输出 @SerialName 值,无注解时为常量名。

07.1.1.9.2-061 自定义序列化器(KSerializer)如何编写?

一句话结论

实现 KSerializer<T>,提供 SerialDescriptor 与 serialize/deserialize 方法,手动从编码器写字段、从解码器读字段;复杂类型可委托内置序列化器。

概念解释

默认生成器覆盖不了的类型(特殊格式、兼容旧字段、组合模型)手写序列化器。描述符声明字段名与类型;读写按字段顺序与标记操作。自定义器可注册到模块供对应类型使用。编写时处理缺失与非法值,给出明确异常。

原理流程

override val descriptor: SerialDescriptor
serialize(encoder, value): 结构写字段
deserialize(decoder): 读字段 → 构造对象

代码或图示

object LongAsStringSerializer : KSerializer<Long> {
    override val descriptor = PrimitiveSerialDescriptor("LongStr", PrimitiveKind.STRING)
    override fun serialize(encoder: Encoder, value: Long) = encoder.encodeString(value.toString())
    override fun deserialize(decoder: Decoder): Long = decoder.decodeString().toLong()
}

常见误区

  • 描述符字段名/类型与读写不一致,编解码错位。
  • 自定义器不处理异常值,非法报文导致崩溃信息不清。

追问

  • 如何给单个属性挂自定义器?答:属性用 @Serializable(with = XSerializer::class) 指定。
  • 自定义器能复用内置集合器吗?答:可委托对应类型的内置序列化器组合实现。

07.1.1.9.2-062 序列化器如何处理日期/时间等自定义类型?

一句话结论

时间类型通过自定义 KSerializer 在对象与字符串/时间戳之间转换,属性上用 @Serializable(with = ...) 挂载;或注册模块统一处理,保证编解码格式与服务端约定一致。

概念解释

标准库时间类型不直接序列化为 JSON 原生值,需约定格式(ISO 字符串或 epoch 毫秒)。自定义器双向转换并处理解析失败。日期格式、时区、毫秒/秒单位要与服务端对齐;解析失败应映射为可定位的解析异常。

原理流程

LocalDateTime ↔ 报文字符串/时间戳
自定义器:格式化输出 / 解析输入

代码或图示

@Serializable(with = TimestampSerializer::class)
val createdAt: LocalDateTime

常见误区

  • 时区不统一,时间显示偏移。
  • 毫秒与秒单位混用,时间解析成错误日期。

追问

  • 有现成时间序列化方案吗?答:生态中存在标准库时间适配模块,具体坐标与版本以官方/社区为准(待确认)。
  • 解析失败如何上报?答:在自定义器抛出携带字段与原始值的异常,便于契约排查。

07.1.1.9.2-063 JsonElement 与解码动态结构怎么用?

一句话结论

结构不确定时先解码为 JsonElement(对象/数组/字面量),按键与类型动态读取,再映射到模型;适合混合报文、动态字段与兼容层解析。

概念解释

JsonElement 是 JSON 结构的通用表示:JsonObject 取键,JsonArray 遍历,JsonPrimitive 取字面量。动态解析灵活但失去类型安全,关键结构仍应落到强类型模型。可先动态解包外层,再对稳定内层解码为具体类型。

原理流程

decodeFromString<JsonElement>(raw)
  → JsonObject/JsonArray 判断结构
  → 取键读值 → 映射模型

代码或图示

val root = Json.decodeFromString<JsonObject>(raw)
val name = root["name"]?.jsonPrimitive?.content

常见误区

  • 全链路动态读 JsonObject,字段拼写错误无编译约束。
  • 类型判断缺失,把数组当对象取值抛异常。

追问

  • 动态结构能直接交给 Retrofit 返回吗?答:可声明返回 JsonElement/JsonObject,由 Converter 解码后业务解析。
  • 动态解析性能如何?答:比强类型生成器略高开销,稳定结构应建模。

07.1.1.9.2-064 反序列化失败抛什么异常,如何定位字段?

一句话结论

失败抛序列化异常(类型不匹配、缺失字段、未知字段等),异常消息通常携带字段路径与类型信息;定位时结合原始报文片段与模型定义,区分契约问题与本地模型问题。

概念解释

异常类别包括结构不符、类型不匹配、缺失必填、枚举/多态未匹配。消息中的路径指向出错字段;线上排查需保留脱敏后的原始报文摘要。解析失败属客户端/契约问题,上报时附模型版本与报文样例。

原理流程

解码 → 字段类型/缺失/枚举校验失败
  → SerializationException(含字段路径)
  → 上报:异常类型、字段、报文摘要、模型版本

代码或图示

异常消息示例:字段 user.name 期望 String,实际为数字(具体格式以实现为准)

常见误区

  • 只上报异常类名不带字段路径,无法定位模型问题。
  • 解析失败后重复重试,问题不会因重试消失。

追问

  • 线上如何拿到失败报文?答:在 Converter/错误分支采样保留脱敏体,受体积与隐私约束。
  • 字段路径在嵌套/集合中如何体现?答:异常路径会带层级与索引,具体格式以框架实现为准(待确认)。

07.1.1.9.2-065 性能上 kotlinx.serialization 相比反射框架有什么优势?

一句话结论

编译期生成序列化器避免运行时反射查找字段与构造对象,编解码路径固定,启动期无反射扫描开销;在移动端弱反射受限环境下更稳定,序列化速度与可预测性更好。

概念解释

反射框架运行时读取字段、构造实例,受混淆与内部构造限制影响;kotlinx.serialization 生成直接调用的读写代码,类型信息在编译期确定。优势主要体现在免去反射开销与混淆兼容,实际性能仍需按接口体量实测。

原理流程

反射:运行时扫描字段 → 反射读写
kotlinx:编译期生成器 → 直接字段读写

代码或图示

无运行时字段反射;序列化器随类编译产物生成

常见误区

  • 认为生成序列化器零成本;首次类加载仍有产物类开销,只是免去反射。
  • 只看序列化速度忽略模型设计与报文大小。

追问

  • 混淆会影响生成器吗?答:生成代码按编译期信息工作,但序列化器产物本身需保留在混淆规则中。
  • 实测对比怎么做?答:固定报文批量编解码,对比耗时、内存与崩溃率,按线上接口体量取分位数据。

07.1.1.9.2-066 序列化产物(序列化器类)在混淆时要注意什么?

一句话结论

R8/混淆后需保留生成的序列化器类与描述符引用,避免序列化器被裁剪或混淆导致编解码找不到器;模型与序列化器的 keep 规则按框架要求配置。

概念解释

kotlinx.serialization 生成的配套类在编译产物中,混淆收缩可能误删;反射/服务定位查找序列化器的路径也需保留。具体 keep 规则以框架官方混淆说明为准(待确认当前版本规则)。模型字段名若被混淆,而报文键靠 @SerialName 映射则不受影响。

原理流程

编译生成 XxxSerializer
  → 混淆期 keep 序列化器与描述符引用
  → 运行时按类取得序列化器

代码或图示

keep 规则:保留序列化器类、 Companion/serializer() 入口(具体规则见官方文档)

常见误区

  • 只 keep 数据类不 keep 生成序列化器,release 包解码失败。
  • 字段被混淆且无 @SerialName,编码键名错乱。

追问

  • 混淆后字段名还能作为 JSON 键吗?答:无注解时依赖属性名,混淆会改名;报文键应显式 @SerialName。
  • 如何验证混淆包序列化正常?答:release 构建下用 MockWebServer 跑解码回归用例。

07.1.1.9.2-067 如何复用全局 Json 实例配置?

一句话结论

构造一个共享 Json 单例(统一忽略未知键、容错、默认值策略),传入 Retrofit 序列化工厂;各接口复用同一配置,避免分散定义导致行为不一致。

概念解释

Json 实例无状态可共享,配置集中管理便于统一调整。特例接口需要不同容错策略时再独立构造实例。全局实例配合依赖注入提供给网络层,测试可替换配置。

原理流程

val Json = Json { ignoreUnknownKeys = true; ... }
Retrofit.Builder().addConverterFactory(Json.asConverterFactory(...))

代码或图示

object Serial {
    val json = Json { ignoreUnknownKeys = true; coerceInputValues = true }
}

常见误区

  • 在工厂方法里每次 Json {} 新建,配置漂移。
  • 全局开宽松解析掩盖契约问题,调试期难发现格式错误。

追问

  • 不同模块能有不同 Json 配置吗?答:可构造多实例按工厂/接口区分,但需明确边界。
  • 全局配置变更如何回归?答:固定报文单测覆盖容错、默认值、枚举场景。

07.1.1.9.2-068 顶层基本类型与包装类型序列化注意什么?

一句话结论

基本类型(字符串、数值、布尔)可直接编解码;包装集合/对象按元素类型处理。顶层标量解码时报文必须是对应字面量,类型不符抛异常。

概念解释

返回 String/Int 等顶层类型由标量序列化器处理;嵌套在对象内的标量按字段类型解码。注意数值范围、整数/浮点混用、字符串数字是否自动转换由配置与实现决定。模型字段类型要与报文一致。

原理流程

顶层 String ↔ JSON 字符串
顶层 Int    ↔ JSON 数字
类型不符 → 解码异常

代码或图示

@GET("version")
suspend fun version(): String

常见误区

  • 报文数字写成字符串,模型声明数值类型,解码失败。
  • 大数超过数值类型范围未用字符串/长整型。

追问

  • 字符串数字能自动转数值吗?答:宽松转换行为按框架配置,不依赖隐式转换更稳妥。
  • 顶层集合怎么声明?答:直接 List<T> 作为返回类型,元素类型需可序列化。

07.1.1.9.2-069 编码(encodeDefaults)对默认值字段的影响?

一句话结论

encodeDefaults 控制值等于默认值的字段是否在编码输出中写出:关闭时省略默认值字段,开启时即使等于默认值也写出;反序列化不受该开关影响。

概念解释

请求报文体积敏感时,省略默认值字段可减小体;但接收方若依赖字段存在需注意。该配置只影响出站编码,入站缺字段仍按默认值规则处理。改动该开关会改变请求报文结构,需与服务端契约确认。

原理流程

encodeDefaults=false:默认值字段不写出
encodeDefaults=true:默认值字段也写出
解码:缺字段用默认值,与开关无关

代码或图示

val json = Json { encodeDefaults = false }

常见误区

  • 以为关闭后缺字段解码会失败;入站规则独立。
  • 服务端要求所有字段必传,却省略默认值导致请求缺参。

追问

  • 嵌套对象的默认值字段也遵循该开关吗?答:按同一编码配置递归处理。
  • 如何强制某个默认字段写出?答:看框架是否支持字段级覆盖,具体能力以版本为准(待确认)。

07.1.1.9.2-070 多模块共享序列化模型如何组织?

一句话结论

把可序列化 DTO 放到独立共享模块,模型只含数据与序列化注解,不依赖 Android/网络层;各业务模块与网络层依赖该模块,保证请求/响应结构单一来源。

概念解释

模型与接口分离:共享模块放 @Serializable 数据类,网络模块定义 Retrofit 接口并引用模型。避免各模块重复定义相似 DTO 造成映射漂移。公共枚举、密封多态类型集中维护。模型变更需同步契约与各端。

原理流程

common-model 模块:DTO + 序列化注解
  → network 模块:Retrofit 接口引用 DTO
  → 业务模块:消费 DTO

代码或图示

:model  → :network → :app
DTO 单一来源,不跨模块重复声明

常见误区

  • 网络层模型直接暴露给 UI,耦合展示结构。
  • 各端各自拷贝字段定义,命名与可空性逐渐漂移。

追问

  • DTO 与领域模型要不要分开?答:复杂项目建议 DTO 映射为领域模型;简单项目可复用,按团队约定。
  • 共享模型升级如何兼容?答:字段新增给默认值,废弃字段保留过渡,按版本演进。

07.1.1.9.2-071 kotlinx.serialization、Moshi、Gson 三者对比如何选型?

一句话结论

kotlinx.serialization 编译期生成、Kotlin 友好、无反射;Moshi 可代码生成或反射,适配成熟;Gson 纯反射、兼容老项目但 Kotlin 可空性与混淆问题较多。Kotlin 新项目优先 kotlinx.serialization。

概念解释

选型维度:反射依赖、可空类型支持、默认值处理、混淆兼容、性能、生态成熟度与团队熟悉度。Gson 历史最久但对 Kotlin 非空类型可能赋值 null;Moshi 结合 Kotlin 代码生成可避免部分反射问题;kotlinx 与语言工具链集成最紧。具体能力差异随版本演进,以当前版本实测为准(待确认)。

原理流程

反射路线:运行时扫描字段(Gson,部分 Moshi)
生成路线:编译期序列化器(kotlinx,Moshi codegen)

代码或图示

对比项:可空安全 / 默认值 / 混淆 / 性能 / 多态 / 生态

常见误区

  • 只按生态老新选型,忽略 Kotlin 可空性在反射框架下的运行时风险。
  • 混用两套框架解析同一模型,注解与行为冲突。

追问

  • 已有 Gson 项目要迁移吗?答:无痛点可维持;新模块优先新框架,按模块渐进切换。
  • 框架切换的回归重点?答:缺字段、未知字段、枚举、多态、默认值与可空场景。

07.1.1.9.2-072 Gson 反射机制在 Kotlin 下有什么坑?

一句话结论

Gson 运行时反射构造对象,无法识别 Kotlin 非空约束,可能给非空字段赋 null;可变集合与构造默认值处理也有局限,混淆后反射字段访问需额外 keep。

概念解释

Gson 按 Java 反射工作,不感知 Kotlin 类型系统:非空字段在报文缺失/null 时可能被填 null,触发后续 NPE;反射构造绕过主构造逻辑。混淆裁剪字段、泛型擦除也会影响映射。这些坑在编译期不暴露,运行时才出问题。

原理流程

反射读字段 → 构造实例 → 反射赋值
非空字段收到 null:编译期无感知,运行时 NPE

代码或图示

data class User(val name: String) // 报文缺 name 时反射框架行为有风险

常见误区

  • 相信模型非空就一定非空;反射框架可能绕过约束。
  • release 混淆后未 keep 模型字段,映射丢失。

追问

  • Gson 能配合 Kotlin 反射适配吗?答:有扩展方案弥补可空性,但额外复杂度;新项目评估收益后决定。
  • 老项目排查 Gson NPE 看什么?答:核对缺失字段、null 报文与模型可空性,结合崩溃栈定位字段。

07.1.1.9.2-073 Moshi 的代码生成与 Kotlin 支持有何特点?

一句话结论

Moshi 支持 Kotlin 代码生成(kotlin-codegen)在编译期生成适配器,减少反射;也可反射适配。对 Kotlin 默认值、可空性的支持程度随版本演进,需核对当前版本能力(待确认)。

概念解释

Moshi 适配器把 JSON 与对象互转,codegen 路线编译期生成,反射路线运行时读取。与 kotlinx 相比,Moshi 在 Java 生态兼容上积累较久;Kotlin 默认值、可空性的具体行为以其文档为准。选型时同样要做缺字段/枚举/多态回归。

原理流程

注解处理 → 生成 JsonAdapter
Moshi 按类型选适配器 → 解码/编码

代码或图示

Moshi + Kotlin codegen:编译期适配器;反射模式:运行时适配

常见误区

  • 以为 codegen 完全等同编译期类型安全;默认值与可空边界仍需实测。
  • 引入 codegen 处理器但模块未配置注解处理,适配器未生成。

追问

  • Moshi 与 kotlinx 能在同一项目并存吗?答:可按类型分工厂,但维护两套模型注解成本高,建议统一。
  • 默认值支持如何确认?答:查当前版本 release notes 并用缺字段报文用例验证(待确认)。

07.1.1.9.2-074 序列化框架对默认值、不可变类型的支持差异?

一句话结论

编译期生成框架能按构造默认值处理缺字段;反射框架对不可变构造与默认值的支持受构造方式限制。选型时重点验证:缺字段回退默认、非空不可变类型构造、集合不可变映射。

概念解释

数据类不可变属性在解码时需通过构造器赋值;反射框架若只能无参构造再赋值,与 val 属性模型冲突。默认值填充、可空回退、集合只读/可变映射是三者差异高频区。这些行为在跨框架迁移时最容易出问题。

原理流程

不可变 val → 必须构造时传入
缺字段 → 默认值填充(框架支持与否)
集合 → List/可变 List 映射规则

代码或图示

data class Settings(val dark: Boolean = false, val items: List<String> = emptyList())

常见误区

  • 迁移框架后默认值不生效,缺字段触发异常。
  • 不可变属性被反射框架尝试二次赋值,行为异常。

追问

  • 如何做框架兼容验证?答:固定报文集覆盖缺省、null、空集合、非法枚举,逐框架对比结果。
  • 不可变模型解码失败怎么改?答:检查框架是否支持构造器注入,或调整模型为可变兼容结构。

07.1.1.9.2-075 统一错误模型如何划分 HTTP 码、业务码、网络异常?

一句话结论

错误分三层:网络异常(未拿到响应:超时/连接/DNS/SSL/取消)、HTTP 错误(拿到响应非 2xx)、业务错误(HTTP 200 但业务码非成功);每层映射为统一领域错误类型,携带可分类的原因。

概念解释

分层保证重试与提示策略正确:网络瞬时故障可重试;HTTP 错误按码处理;业务错误按业务码走流程。统一错误模型包含类型、码、消息、可选数据与上下文。映射在数据层完成,UI 只消费领域错误。

原理流程

onFailure(IOException) → NetworkError(原因)
Response 非 2xx → HttpError(code, errorBody)
Envelope code 非成功 → BusinessError(bizCode, message)

代码或图示

sealed interface AppError {
    data class Network(val cause: IOException) : AppError
    data class Http(val code: Int, val msg: String?) : AppError
    data class Business(val bizCode: Int, val msg: String?) : AppError
}

常见误区

  • 三层错误混为一个「未知错误」,无法选择重试或提示。
  • 把业务错误上报成服务端故障。

追问

  • 解析异常归到哪层?答:单独 ContractError,不属于网络或业务,按契约问题上报。
  • 错误模型需要带原始报文吗?答:采样携带脱敏摘要,不全量存敏感体。

07.1.1.9.2-076 401/403/404/5xx 分别如何映射到业务错误?

一句话结论

401 未认证触发登录/刷新流程,403 已认证但无权限,404 资源不存在,5xx 服务端临时故障可谨慎重试;各类映射为对应领域错误,提示与重试策略不同。

概念解释

401 通常令牌失效,走刷新或重新登录;403 权限不足,不重试;404 客户端资源地址问题;5xx 服务端故障,幂等接口可有限重试。映射时保留 HTTP 码便于排查。状态码语义以 HTTP 规范为准,业务自定义码在 body 内另判。

原理流程

401 → 未认证 → 刷新令牌/登录
403 → 无权限 → 提示无权限
404 → 资源不存在
5xx → 服务端错误 → 有限重试/降级

代码或图示

when (resp.code) {
    401 -> handleUnauthorized()
    403 -> showForbidden()
    in 500..599 -> retryIfIdempotent()
}

常见误区

  • 401 与 403 混为「登录失效」;两者认证状态不同。
  • 5xx 无脑重试全部接口,非幂等写接口造成重复提交。

追问

  • 422 校验失败怎么处理?答:读错误体字段级提示,展示表单错误,不重试。
  • 自定义状态码如何映射?答:在错误模型中保留原始码,业务层按约定归类。

07.1.1.9.2-077 网络异常(超时/断网/DNS)如何包装成统一错误?

一句话结论

捕获 IOException 后按异常子类型分类:超时、连接拒绝、未知主机(DNS)、SSL、取消;包装为统一 NetworkError,保留原始 cause 与分类枚举,供重试判断与上报。

概念解释

网络异常没有 HTTP 响应,分类靠异常类型与消息。断网在请求前即可预判;超时区分 connect/read/write/call 阶段。取消单独识别不纳入失败统计。包装时不丢原始异常链,上报保留类型与阶段。

原理流程

IOException
  → SocketTimeoutException → Timeout(阶段)
  → UnknownHostException → DnsFailure
  → SSL 相关 → SslFailure
  → 其他 → ConnectFailure

代码或图示

fun IOException.toNetworkError(): NetworkError = when (this) {
    is SocketTimeoutException -> NetworkError.Timeout(this)
    is UnknownHostException -> NetworkError.Dns(this)
    else -> NetworkError.Connect(this)
}

常见误区

  • 只保留异常消息字符串,丢失类型无法程序化分类。
  • 把取消异常归为网络失败计入崩溃/错误率。

追问

  • 阶段信息从哪拿?答:EventListener 阶段事件或异常来源,超时类型可区分局部/整体超时。
  • 断网如何前置判断?答:结合系统网络状态回调,请求失败再兜底分类。

07.1.1.9.2-078 业务码非成功时如何携带错误信息与数据?

一句话结论

业务错误模型携带业务码、提示消息、可选的错误字段明细与附加数据;成功数据与错误数据分开放置,UI 按错误类型读取提示,表单类错误可带字段级信息。

概念解释

外层 envelope 的 message 给通用提示,字段级错误(表单校验)放在明细列表。错误数据结构与成功模型独立,避免 UI 混用。业务码映射到可识别的领域错误,原始码保留用于排查。

原理流程

Envelope(code, message, data, errors?)
  → code 非成功 → BusinessError(code, message, fieldErrors)

代码或图示

data class FieldError(val field: String, val message: String)
data class BusinessError(val code: Int, val message: String?, val fields: List<FieldError>?)

常见误区

  • 错误时仍把 data 透传,UI 展示旧/脏数据。
  • 字段错误与全局提示混在一个 message 里,无法定位表单项。

追问

  • 业务码与 HTTP 码都要存吗?答:是,分层保留;上报时同时记录两者便于区分问题层。
  • 错误提示文案谁负责?答:服务端消息可直接展示或做兜底映射,多语言策略按团队约定。

07.1.1.9.2-079 错误模型在 Repository/ViewModel 层如何消费?

一句话结论

Repository 把接口结果映射为领域 Result/状态流,ViewModel 消费结果分发 UI 状态(成功数据、错误提示、加载态);错误类型在数据层已分类,UI 不直接解析 HTTP/JSON 细节。

概念解释

分层消费:网络层出领域错误,Repository 做缓存与业务判定,ViewModel 转成 UI 状态。错误展示按类型选择 toast/弹窗/空态/重试。取消与加载状态单独管理,不混入错误。

原理流程

Api Result → Repository 映射 DomainResult
  → ViewModel 更新 UiState(Loading/Success/Data/Error)

代码或图示

sealed interface UiState<out T> {
    object Loading : UiState<Nothing>
    data class Success<T>(val data: T) : UiState<T>
    data class Fail(val error: AppError) : UiState<Nothing>
}

常见误区

  • ViewModel 直接读 Retrofit Response 与业务码,分层泄漏。
  • 错误只弹一次提示,状态流重建后丢失错误信息。

追问

  • 错误状态在页面重建后如何保留?答:状态持有在 ViewModel/Store,重建时恢复最近错误态。
  • 可重试错误在 UI 层如何触发?答:ViewModel 暴露重试方法,重新走 Repository 调用链。

07.1.1.9.2-080 如何避免把解析异常误报成服务端错误?

一句话结论

上报与分类时按异常类型分流:序列化/解码异常标记为契约/客户端问题,不进入服务端错误率;同时保留报文采样供核对模型与服务端契约。

概念解释

解析失败可能是模型过时、报文结构变化或脏数据,与服务端 5xx 性质不同。分类错误会误导后端值班。Converter/适配层捕获解码异常,打上 parse_error 标签并附模型版本与字段路径;服务端错误仅统计 HTTP 5xx 与业务服务端码。

原理流程

解码异常 → ContractError 标签
  → 上报:模型版本、字段路径、报文摘要
HTTP 5xx/服务端业务码 → ServerError 标签

代码或图示

catch (e: SerializationException) {
    report.tag("parse_error").extra("model", modelVersion)
}

常见误区

  • 统一 catch Exception 后都报「服务端异常」。
  • 解析异常不带报文样例,无法判断是模型还是数据问题。

追问

  • 模型版本怎么带到上报?答:构建版本与模型契约版本一起作为公共字段。
  • 解析异常要重试吗?答:不重试结构问题;重新拉取也不会改变结构。

07.1.1.9.2-081 灰度接口返回结构变化如何兼容?

一句话结论

按版本与灰度标识做兼容解析:模型保留缺省与可空,容错未知字段,关键结构变化用密封类型/动态解析过渡;新旧结构都有单测覆盖,灰度期监控解析失败率。

概念解释

灰度期间新旧报文可能并存。兼容手段:未知字段忽略、字段默认值、可空兜底、多态鉴别结构、双模型过渡解析。不能为兼容放宽到掩盖所有错误,解析失败仍要可观测。版本切换后再清理过渡模型。

原理流程

新结构灰度下发
  → 旧模型容错解析 → 兼容过渡
  → 监控 parse_error 与字段缺失
  → 全量后更新模型,移除过渡逻辑

代码或图示

Json { ignoreUnknownKeys = true; coerceInputValues = true }

常见误区

  • 老版本客户端遇到新结构直接崩溃;缺少容错配置。
  • 过渡模型长期不清理,结构堆积混乱。

追问

  • 结构不兼容大改怎么过渡?答:服务端版本协商或双字段并行,客户端按版本解析,逐步迁移。
  • 灰度包如何验证?答:MockWebServer 构造新旧两份报文,回归解析用例。

07.1.1.9.2-082 错误上报应包含哪些上下文信息?

一句话结论

至少包含接口路径、HTTP 码/业务码、异常类型与阶段、耗时、网络类型、机型/系统版本、App 版本、trace id;敏感字段脱敏,报文摘要采样保留。

概念解释

上下文用于定位是网络、服务端、契约还是客户端问题。公共字段(版本、机型、网络)随所有上报携带;请求级字段按接口补充。错误堆栈保留 cause 链。隐私字段(令牌、手机号、地址)不得进入上报。

原理流程

错误事件:path / code / bizCode / errorType / stage / costMs
  + device / os / appVersion / networkType / traceId
  + 脱敏报文摘要(采样)

代码或图示

上报字段:不包含 Authorization、Cookie、身份证等敏感值

常见误区

  • 上报完整请求/响应体,泄露用户数据。
  • 只报异常消息不带路径与版本,无法定位影响范围。

追问

  • 采样策略怎么定?答:错误全量上报,成功报文按比例采样;敏感内容先脱敏。
  • trace id 从哪来?答:请求头透传,客户端生成或服务端下发,两端串联。

07.1.1.9.2-083 MockWebServer 如何模拟接口响应?

一句话结论

启动 MockWebServer,把 Retrofit baseUrl 指向本地端口,按队列或规则 enqueue 预设响应(状态码、头、体),接口调用即返回模拟报文,用于脱离后端的单元测试。

概念解释

MockWebServer 在本地起 HTTP 服务,按入队顺序或调度规则返回响应。测试可固定报文断言解析结果,也可动态按请求返回不同响应。测试结束关闭服务,避免端口占用。依赖与服务端契约解耦,前端可并行开发。

原理流程

server.start() → baseUrl = server.url("/")
  → enqueue(MockResponse(...))
  → api.method() → 收到模拟响应

代码或图示

val server = MockWebServer()
server.enqueue(MockResponse().setBody("""{"name":"Ann"}""").setResponseCode(200))

常见误区

  • 测试间共享队列未清空,响应串到下个用例。
  • baseUrl 未指向 mock 端口,请求打到真实环境。

追问

  • MockWebServer 支持 HTTPS 吗?答:可配置 TLS 与证书,具体配置方式以库文档为准(待确认)。
  • 响应延迟怎么模拟?答:MockResponse 设置延迟,或调度规则控制。

07.1.1.9.2-084 如何用 MockWebServer 做契约测试与断言请求?

一句话结论

从 MockWebServer 取出实际发出的 RecordedRequest,断言方法、路径、查询参数、头与请求体;响应侧固定报文断言解析结果,双向校验接口契约。

概念解释

契约测试既校验「我们发出的请求符合约定」,也校验「约定报文能被正确解析」。takeRequest() 拿到录制请求,读取路径与头;请求体可解码核对字段。响应报文按服务端样例构造,断言模型字段。

原理流程

调用接口 → server.takeRequest()
  → 断言 method/path/headers/body
  → 断言返回模型字段与预设报文一致

代码或图示

val req = server.takeRequest()
assertEquals("GET", req.method)
assertEquals("/user", req.path)

常见误区

  • 只断言响应解析,不校验请求是否按契约发出。
  • 请求体读多次导致流为空;录制请求体读取一次即可。

追问

  • 如何断言 JSON 请求体?答:读取 body 字符串后用 JSON 解析核对字段,不做整串全等避免格式漂移。
  • 多请求顺序怎么断言?答:按 takeRequest 顺序逐个校验,记录调用次序。

07.1.1.9.2-085 如何模拟延迟、错误码与断连场景?

一句话结论

延迟用 MockResponse 设置 body delay;错误码直接设置状态码与错误体;断连/失败用调度规则抛出异常或返回关闭连接的响应,覆盖超时与失败分支。

概念解释

测试不只覆盖成功路径:延迟验证超时与加载态,4xx/5xx 验证错误分支,断连验证网络异常处理。MockWebServer 的调度器可按请求动态返回不同响应。超时用例需配合较短超时配置,避免测试等待过久。

原理流程

延迟:setBodyDelay(...)
错误:setResponseCode(422).setBody(errJson)
断连:调度返回失败/连接关闭响应

代码或图示

server.enqueue(MockResponse().setResponseCode(500).setBody("{}"))

常见误区

  • 失败分支无测试,线上错误处理路径裸露。
  • 延迟用例不缩短超时,单测执行过长。

追问

  • 能模拟超时断连吗?答:通过延迟超过超时阈值或调度抛异常实现,具体 API 以库版本为准(待确认)。
  • 弱网带宽/丢包怎么模拟?答:MockWebServer 侧重协议响应;链路弱网用设备/代理工具模拟。

07.1.1.9.2-086 契约测试校验哪些内容(路径、方法、头、体)?

一句话结论

请求侧校验方法、路径、查询参数、必填头、请求体字段;响应侧校验状态码、关键字段类型与取值、错误结构;契约变更时测试先行暴露不一致。

概念解释

契约测试锁定前后端约定:路径与方法不能漂移,鉴权/追踪头必须带上,体字段名与类型一致。响应样例取自真实接口文档或线上采样。测试失败要么是客户端实现错,要么是契约变了,需同步模型与用例。

原理流程

请求契约:method + path + query + headers + body schema
响应契约:status + body schema + error schema

代码或图示

断言:POST /orders;Header Authorization;body.userId 非空
响应:code=0,data.id 为字符串

常见误区

  • 契约测试只验证「不崩溃」,不核对字段值与类型。
  • 响应样例手写与真实接口脱节,契约漂移未发现。

追问

  • 契约测试属于单测还是集成测试?答:本地 MockWebServer 跑的是隔离契约测试;对接真实环境的联调另算。
  • 契约文档如何同步?答:字段变更先改模型与用例,再对齐后端实现。

07.1.1.9.2-087 单元测试中如何替换 Retrofit 接口实现?

一句话结论

测试可手写接口 Fake 实现类返回固定结果,或用 MockWebServer 驱动真实 Retrofit 链路;Repository 依赖接口抽象,测试注入 Fake 替代真实网络。

概念解释

面向接口编程使数据层可替换:业务依赖 ApiService 接口,单测提供 Fake 实现控制成功/失败/空态。验证序列化与请求格式时用 MockWebServer 走真实适配器;纯业务逻辑用 Fake 更轻量。两种方式按测试目标选择。

原理流程

生产:Retrofit.create(ApiService)
测试:FakeApiService() : ApiService(固定返回/抛错)
或:MockWebServer + 真实 Retrofit

代码或图示

class FakeApi : ApiService {
    override suspend fun getUser(): User = User("Ann")
}

常见误区

  • Repository 直接依赖 Retrofit 具体实现,无法替换测试。
  • Fake 不模拟错误分支,业务错误处理无覆盖。

追问

  • Fake 要实现全部方法吗?答:接口方法多可用基类抛未实现,测试用到的方法覆写。
  • Mock 框架能模拟接口吗?答:可用 Mock 库桩化方法,但返回模型仍需构造;具体工具按项目约定。

07.1.1.9.2-088 弱网与超时治理在接口层如何落地?

一句话结论

接口层配合分级超时、幂等重试与退避、请求合并与缓存;弱网下控制在途并发,非关键请求延迟或降级,指标按弱网环境单独观测成功率与耗时。

概念解释

弱网治理不是单一超时设置:超时按阶段分级,重试仅限幂等且退避,重复请求合并,静态数据走缓存。接口层对外暴露明确错误类型,上层据此决定提示与重试。测试用弱网模拟与 Mock 延迟覆盖慢响应。

原理流程

分级超时 + 幂等退避重试
  → 重复请求合并 + 本地缓存兜底
  → 非关键接口延迟/降级
  → 弱网分维度指标监控

代码或图示

关键接口:较短超时 + 有限重试
非关键:延迟加载 + 缓存优先

常见误区

  • 弱网下统一拉长超时,请求长期占用线程与连接。
  • 不区分弱网与服务端故障,错误提示与重试一刀切。

追问

  • 弱网指标怎么采集?答:按网络类型分组统计成功率、耗时分位、超时率与重试率。
  • 接口层能判断当前网络好坏吗?答:网络状态由系统回调提供,接口层消费上层传入的环境信息。

07.1.1.9.2-089 重试与退避应放在 Retrofit 层还是上层?

一句话结论

连接级瞬时重试可由 OkHttp 客户端开关处理;业务重试(含退避、抖动、幂等判断、次数上限)放在 Repository/上层,用新 Call 发起,避免在适配层写复杂重试逻辑。

概念解释

Retrofit/适配器层职责是转换与适配,重试策略涉及业务幂等性、退避节奏与用户可见性,适合上层控制。把重试埋在拦截器或适配器里会隐藏调用次数,难以统计与取消。连接失败自动重试只覆盖底层瞬时故障。

原理流程

底层:retryOnConnectionFailure(连接故障重建)
上层:失败分类 → 幂等判断 → 指数退避 + 抖动 → 新 Call 重试

代码或图示

suspend fun <T> withRetry(retries: Int, block: suspend () -> T): T { /* 退避循环 */ }

常见误区

  • 在拦截器里循环重试,重试次数与取消不可控。
  • 非幂等 POST 也走自动重试,造成重复写入。

追问

  • 退避间隔怎么定?答:指数增长加随机抖动,上限封顶;按接口重要性与服务端容量调整。
  • 重试期间 UI 状态怎么显示?答:上层控制加载态,区分首次加载与后台重试。

07.1.1.9.2-090 接口日志在生产环境如何控制级别与脱敏?

一句话结论

生产默认只记录路径、码、耗时等元数据,报文级别日志仅调试包开启;敏感头与字段按规则掩码,日志量采样控制,避免泄露与性能损耗。

概念解释

日志级别分级:NONE/BASIC/HEADERS/BODY 对应不同信息量。生产关闭 BODY,调试包按需开启。脱敏覆盖 Authorization、Cookie、手机号、身份证、地址等。日志拦截器在工作线程执行,批量与 IO 要轻量,避免拖慢网络。

原理流程

调试包:HEADERS/BODY(脱敏后)
生产包:BASIC 元数据 + 采样
敏感键:掩码替换

代码或图示

if (BuildConfig.DEBUG) client.addNetworkInterceptor(loggingInterceptor)

常见误区

  • 生产包保留 BODY 日志,泄露令牌与用户数据。
  • 日志同步写磁盘阻塞网络线程。

追问

  • 脱敏规则在哪维护?答:集中键名规则表,拦截器统一应用,避免各处各写一套。
  • 线上问题如何看报文?答:按 trace id 采样上报脱敏摘要,不靠本地全量日志。

07.1.1.9.2-091 抓包安全:令牌与敏感字段如何避免泄露?

一句话结论

令牌等凭证走加密连接且不在 URL 查询参数与日志中出现;本地日志、崩溃上报、Mock 样例都脱敏;证书固定与网络安全配置降低被中间人观测的风险。

概念解释

泄露渠道包括:明文 URL 参数、日志打印、崩溃堆栈中的请求串、抓包代理、截图缓存。凭证放 Header,避免出现在路径/查询串;日志与上报掩码;调试代理不残留到正式包。敏感响应字段同样不落日志。

原理流程

令牌 → Authorization Header(加密通道)
日志/上报 → 掩码
调试代理 → 仅调试构建

代码或图示

禁止:?token=xxx;推荐:Header Authorization

常见误区

  • 令牌拼在 URL 里,被日志、历史记录与代理日志留存。
  • 崩溃堆栈带上完整请求 URL,敏感参数外泄。

追问

  • 抓包能看到 HTTPS 内容吗?答:TLS 终止代理持证书可解密;正式环境应限制代理并评估固定策略。
  • 敏感响应如何处理?答:不写本地日志与缓存,必要时加密存储。

07.1.1.9.2-092 响应体日志为什么不能全量打印?

一句话结论

全量体日志占用线程与内存、拖慢网络、泄露用户数据,大报文还可能撑爆日志缓冲;只应在调试环境按接口采样打印摘要或截断内容。

概念解释

响应体是一次性流,全量读取会消费原始流影响上层;日志拦截器需复制缓冲副本。生产环境体内容敏感且体积大,全量打印既不安全也影响性能。线上排障靠 trace id 与服务端日志串联,不靠本地全量体。

原理流程

BODY 日志:缓冲复制体 → 打印
风险:内存峰值 + 泄漏 + IO 开销
生产:只打码/大小/摘要

代码或图示

日志体长度截断;大文件/图片接口跳过体日志

常见误区

  • 列表/详情接口全量打 JSON,日志膨胀且含隐私。
  • 读取体打日志后未替换流,上层拿到空体。

追问

  • 调试要看完整报文怎么办?答:调试包对特定接口开启,使用前关闭,不进正式构建。
  • 体大小怎么记录?答:记录 Content-Length 或实际字节数,不打印内容。

07.1.1.9.2-093 如何记录接口 trace id 串联客户端与服务端日志?

一句话结论

出站请求生成或透传 X-Trace-Id 头,客户端日志、错误上报与服务端日志按同一 id 关联;id 随本次请求贯穿拦截器、上报与崩溃上下文。

概念解释

trace id 让单次请求在两端可追踪:客户端生成唯一 id 放请求头,服务端记录到自己的日志;客户端上报错误时带上同一 id。关联信息还可包含接口路径、耗时与状态。id 不携带用户敏感信息。

原理流程

请求生成 traceId → 加入 Header
  → 客户端日志/上报记录 traceId
  → 服务端日志按 traceId 串联

代码或图示

val traceId = UUID.randomUUID().toString()
Request.Builder().header("X-Trace-Id", traceId)

常见误区

  • 客户端与服务端各用各的请求标识,无法对齐。
  • 重试请求更换 trace id,链路断档;重试应复用同一 id 或关联父 id。

追问

  • id 放请求还是响应?答:客户端生成放请求头;服务端也可回传,客户端记录响应侧 id。
  • 链路跨多个接口怎么串?答:页面/业务会话维度生成父 id,接口 id 挂在其下。

07.1.1.9.2-094 Retrofit 接口版本化与多环境 baseUrl 如何管理?

一句话结论

baseUrl 按构建环境注入(dev/staging/prod),接口路径在方法注解中保持环境无关;多版本 API 用路径段或独立 Retrofit 实例区分,版本号不硬编码进业务代码。

概念解释

环境差异由构建配置/配置中心提供,Retrofit 实例按环境构建。API 版本(如 /v1/)可作为 baseUrl 路径段;废弃版本过渡期间并存。域名切换通过重建实例或动态 @Url,注意证书与连接隔离。

原理流程

BuildConfig.API_BASE_URL → Retrofit.baseUrl
版本段:baseUrl 含 /v1/,或独立 client

代码或图示

Retrofit.Builder().baseUrl(BuildConfig.API_BASE_URL)

常见误区

  • 方法注解写死完整域名,切环境要改接口代码。
  • 多版本混用同一 baseUrl,路径互相覆盖。

追问

  • 运行时切换环境怎么做?答:重建网络层实例并替换注入引用;存量在途请求按旧实例跑完。
  • 灰度域名怎么接入?答:按配置选择域名,配合 @Url 或独立实例,校验证书白名单。

07.1.1.9.2-095 接口签名/加密放在 Converter 还是拦截器?

一句话结论

传输层加解密与签名验签适合拦截器处理原始报文;字段编码/模型转换归 Converter。请求体加密在编码之后、出站之前,响应解密在进入解码之前,顺序要固定。

概念解释

签名通常依赖报文内容、时间戳与随机数,在拦截器统一计算头更集中;加解密可在拦截器替换 body。Converter 负责对象 ↔ 明文 JSON。顺序:对象编码 → 拦截器加密/签名 → 出站;响应:拦截器解密 → Converter 解码。字段级加密另论。

原理流程

出站:对象 → Converter 编码 → 拦截器加密 + 签名头
入站:拦截器验签 + 解密 → Converter 解码

代码或图示

拦截器:读明文 body → 加密新 body + 签名头

常见误区

  • 先加密再让 Converter 编码,格式错乱。
  • 签名计算包含了会被代理/网关改动的头,验签失败。

追问

  • 签名串怎么构造?答:按约定拼接方法、路径、参数、时间戳、随机数与密钥摘要,具体规则与服务端对齐。
  • 加密密钥放哪?答:不在代码硬编码密钥;按安全方案管理,密钥存储见安全章节。

07.1.1.9.2-096 大报文上传/下载在 Retrofit 层如何处理?

一句话结论

上传用流式 RequestBody 提供文件字节并计算进度,下载返回 ResponseBody 流式写盘;不要把大文件整体读进内存,超时按分段/间隔设置。

概念解释

大报文走流式而非全量缓冲:上传 writeTo 分批写入,下载 source() 分批读取落盘。进度在写入/读取流中统计。Multipart 文件部分指定文件名与类型。大文件超时按数据到达间隔配置,失败支持断点续传(服务端支持 Range)。

原理流程

上传:文件 → 流式 RequestBody → 边写边报进度
下载:ResponseBody 流 → 分批写盘 → 进度/断点

代码或图示

@Multipart
@POST("upload")
suspend fun upload(@Part file: MultipartBody.Part): Result

常见误区

  • file.readBytes() 全量进内存,大文件 OOM。
  • 下载响应体不关闭,连接与文件句柄泄漏。

追问

  • 上传进度如何回调?答:自定义 RequestBody 包装原始体,在 writeTo 按已写字节比例回调。
  • 断点续传怎么实现?答:记录已传偏移,Range 请求续传,需服务端支持分片。

07.1.1.9.2-097 接口缓存策略在 Retrofit 层如何声明?

一句话结论

Retrofit 接口本身不直接配缓存,缓存策略由底层 OkHttp Cache 与请求/响应头控制;需要离线兜底时在请求头声明缓存偏好,或业务层自建内存/磁盘缓存。

概念解释

HTTP 缓存复用 OkHttp 磁盘缓存机制,Retrofit 只负责构造请求与解码。静态只读接口适合走网络缓存;动态数据由业务层缓存结果。缓存键与失效策略按接口特性设计,注意登录态数据隔离。

原理流程

Retrofit 请求 → OkHttp Cache 按 Cache-Control 命中/回源
业务缓存:Repository 内存/磁盘缓存解码结果

代码或图示

@Headers("Cache-Control: max-age=60")
@GET("config") suspend fun config(): Config

常见误区

  • 以为 Retrofit 有独立结果缓存层;默认无业务结果缓存。
  • 把需实时刷新的接口交给 HTTP 强缓存,数据过期。

追问

  • 业务缓存与 HTTP 缓存如何配合?答:HTTP 缓存报文层,业务缓存解码结果;一致性按数据时效设计。
  • 退出登录如何清缓存?答:清理业务缓存与 OkHttp 磁盘缓存中该用户条目。

07.1.1.9.2-098 如何监控接口成功率与耗时分位?

一句话结论

按接口路径上报成功率、HTTP/业务码分布与耗时的 P50/P90/P99,分网络类型与版本维度;失败样本附分类与 trace id,区分网络、HTTP、业务、解析错误。

概念解释

平均值掩盖长尾,耗时要看分位。成功率分母是全部调用(含失败),按错误类型拆分。监控发现劣化后下钻阶段耗时(DNS/握手/首字节/体传输)。版本对比与灰度期间单独看指标。

原理流程

每次调用 → 上报 path / code / bizCode / costMs / errorType / networkType
聚合:成功率、分位耗时、错误分布

代码或图示

指标:success_rate、cost_p50/p90/p99、timeout_rate、parse_error_rate

常见误区

  • 只报成功请求耗时,失败样本缺失。
  • 平均耗时达标但 P99 很差,长尾用户体验未被发现。

追问

  • 分位在客户端怎么算?答:采样上报原始耗时,服务端聚合分位;本地不做全量统计。
  • 接口口径如何对齐?答:路径归一化(去掉路径参数)作为聚合键,避免 id 打散指标。

07.1.1.9.2-099 接口层常见崩溃来源有哪些(空体、类型不匹配、并发)?

一句话结论

常见来源:空体/非空模型不匹配、JSON 类型与声明不符、集合/枚举解析失败、响应体未关闭、并发回调访问已销毁页面、取消后仍读体;多为契约与生命周期问题。

概念解释

崩溃可分解析类(模型与报文不符)、资源类(流未关闭、连接泄漏)、生命周期类(回调晚于页面销毁)、并发类(多线程访问状态)。防御手段:可空性对齐契约、错误分类、作用域取消管理、单测覆盖异常报文。

原理流程

解析崩溃:类型/缺失/枚举不符
资源崩溃:流未关闭
生命周期崩溃:回调访问销毁 View

代码或图示

防御:判空 + 错误分类 + 作用域取消 + 流关闭

常见误区

  • 全量 !! 断言,空体/ null 直接 NPE。
  • 回调不检查页面/作用域状态就更新 UI。

追问

  • 线上如何定位解析崩溃?答:崩溃栈定位模型字段,结合上报报文摘要核对契约。
  • 并发回调线程问题怎么防?答:状态更新切回主线程/统一调度,协程作用域绑定页面生命周期。

07.1.1.9.2-100 设计一套可维护的 Retrofit 网络层结构要考虑哪些点?

一句话结论

清晰分层:模型与接口分离、统一客户端配置与工厂、错误模型与适配层集中、拦截器职责单一、配置按环境注入、指标与日志可观测、测试可替换;接口定义与业务消费解耦。

概念解释

可维护性要点:模型独立模块、Retrofit/OkHttp 构建集中、Converter/CallAdapter 顺序明确、鉴权与横切拦截器分层、错误模型统一映射、环境配置外置、Mock 契约测试覆盖、版本演进有兼容策略。新增接口不改动公共链路,公共策略变更不散落各接口。

原理流程

model 模块 → network 模块(Api/Retrofit/拦截器/错误映射) → repository → ui
公共配置集中;接口按业务域拆分

代码或图示

分层:DTO 模型 / Service 接口 / 网络配置 / 错误适配 / Repository

常见误区

  • 拦截器里写业务判断,横切与业务耦合。
  • 接口与模型散落各页面模块,重复定义难以维护。

追问

  • 网络层如何做模块化?答:按业务域分 Service 接口,公共客户端与错误模型下沉共享模块。
  • 新增一个接口要改哪些地方?答:加 DTO、加 Service 方法、Repository 暴露方法;公共链路不动。

参考来源

待整理清单

  • [ ] 核对项目实际 Retrofit 版本下 suspend 适配、Response<T> 支持与自定义 CallAdapter 的准确 API 与异常类型。
  • [ ] 确认 kotlinx.serialization 1.7.x 的 Json 配置项名称、默认值与 coerceInputValues 的适用边界。
  • [ ] 核对序列化器产物在 R8 下的官方 keep 规则与混淆包解码回归结果。
  • [ ] 验证多态鉴别字段配置 API、枚举未知值兜底行为与密封类自动收集的当前版本表现。
  • [ ] 补充 MockWebServer 在项目测试模块中的依赖坐标、HTTPS 模拟方式与延迟/断连用例写法。
  • [ ] 整理线上错误分类映射表(HTTP 码、业务码、网络异常、解析异常)与各分类的重试/提示策略。