原生移动开发 / 系统课时

接口定义与数据序列化

接口定义与数据序列化

这一节把一份 JSON 接口契约落成 Android 可使用的类型:先用 DTO 精确描述传输字段,再用 Retrofit 声明请求,最后用 kotlinx.serialization 完成 JSON 与 Kotlin 对象之间的双向转换。

学习目标

  • 能根据接口 JSON 定义可序列化的 DTO,并处理字段名差异与可选字段
  • 能用 Retrofit 注解声明请求方法、路径参数与返回类型
  • 能配置 JSON 转换器,并用本地样例验证序列化和反序列化结果

让 DTO 贴合传输格式

DTO 只负责描述“线上传输的数据长什么样”,不要急着把页面状态、格式化文本或业务计算塞进去。假设接口返回如下 JSON,其中 trace_id 是客户端暂时不关心的新字段:

json
{"article_id":42,"title":"协程入门","body":"从 suspend 开始","trace_id":"<ID>"}

对应 DTO 可以这样定义。@SerialName 用来处理 JSON 字段名与 Kotlin 命名不一致的情况;可能缺失的字段应提供默认值或声明为可空类型,否则服务端少返回字段时会反序列化失败。

kotlin
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable

@Serializable
data class ArticleDto(
    @SerialName("article_id")
    val id: Long,
    val title: String,
    val body: String = ""
)

这是数据结构片段,不会产生控制台输出。真正验证它是否匹配接口,应至少测试一次“正常字段”“缺失可选字段”和“新增未知字段”三类响应。

定义 Retrofit API 接口

Retrofit 用注解把 Kotlin 函数映射为 HTTP 请求。路径参数必须同时出现在 URL 模板和 @Path 参数中;使用协程时直接把函数声明为 suspend,不需要额外的 Deferred 适配器。

kotlin
import retrofit2.http.GET
import retrofit2.http.Path

interface ArticleApi {
    @GET("articles/{id}")
    suspend fun getArticle(@Path("id") id: Long): ArticleDto
}

这是片段示例,依赖 Retrofit 实例提供真实 baseUrl 和转换器。若接口需要查询参数、请求体或请求头,再分别使用 @Query、@Body、@Header 等注解,不要把这些值手工拼进 URL 字符串。

配置 JSON 转换器

模块需要启用 Kotlin serialization 插件,并引入 Retrofit、converter-kotlinx-serialization 与 kotlinx-serialization-json。下面的 Retrofit 配置允许服务端新增客户端暂时不用的字段,降低接口向后兼容时的解析风险。

kotlin
import kotlinx.serialization.json.Json
import okhttp3.MediaType.Companion.toMediaType
import retrofit2.Retrofit
import retrofit2.converter.kotlinx.serialization.asConverterFactory

val json = Json {
    ignoreUnknownKeys = true
}

val articleApi: ArticleApi = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(
        json.asConverterFactory("application/json".toMediaType())
    )
    .build()
    .create(ArticleApi::class.java)

这是配置片段,https://api.example.com/ 只是示例地址,不代表可调用服务;Retrofit 的 baseUrl 必须以 / 结尾。配置生效后,ArticleApi 返回体会自动交给同一个 Json 实例解析。

验证序列化边界

在真正连后端前,可以先用一个本地 main 验证 DTO 与 JSON 的映射。这个测试特意保留未知字段,确认 ignoreUnknownKeys = true 的行为。

kotlin
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json

@Serializable
data class ArticleDto(
    @SerialName("article_id")
    val id: Long,
    val title: String,
    val body: String = ""
)

fun main() {
    val json = Json { ignoreUnknownKeys = true }
    val payload =
        """{"article_id":42,"title":"协程入门","body":"从 suspend 开始","trace_id":"<ID>"}"""

    val dto = json.decodeFromString<ArticleDto>(payload)
    println("${dto.id}|${dto.title}")

    val encoded = json.encodeToString(dto)
    println(encoded)
}

预期输出:

text
42|协程入门
{"article_id":42,"title":"协程入门","body":"从 suspend 开始"}

trace_id 在反序列化时被忽略,因此重新编码时不会凭空保留。若客户端必须回传某个字段,就应把它明确建模到 DTO 中,而不是依赖“未知字段自动透传”。接口定义、DTO 与转换器三者对齐后,网络层才能稳定地把原始 JSON 变成类型安全的数据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接口定义与数据序列化

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通