原生移动开发 / 系统课时
接口定义与数据序列化
接口定义与数据序列化
这一节把一份 JSON 接口契约落成 Android 可使用的类型:先用 DTO 精确描述传输字段,再用 Retrofit 声明请求,最后用 kotlinx.serialization 完成 JSON 与 Kotlin 对象之间的双向转换。
学习目标
- 能根据接口 JSON 定义可序列化的 DTO,并处理字段名差异与可选字段
- 能用 Retrofit 注解声明请求方法、路径参数与返回类型
- 能配置 JSON 转换器,并用本地样例验证序列化和反序列化结果
让 DTO 贴合传输格式
DTO 只负责描述“线上传输的数据长什么样”,不要急着把页面状态、格式化文本或业务计算塞进去。假设接口返回如下 JSON,其中 trace_id 是客户端暂时不关心的新字段:
{"article_id":42,"title":"协程入门","body":"从 suspend 开始","trace_id":"<ID>"}对应 DTO 可以这样定义。@SerialName 用来处理 JSON 字段名与 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 适配器。
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 配置允许服务端新增客户端暂时不用的字段,降低接口向后兼容时的解析风险。
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 的行为。
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)
}预期输出:
42|协程入门
{"article_id":42,"title":"协程入门","body":"从 suspend 开始"}trace_id 在反序列化时被忽略,因此重新编码时不会凭空保留。若客户端必须回传某个字段,就应把它明确建模到 DTO 中,而不是依赖“未知字段自动透传”。接口定义、DTO 与转换器三者对齐后,网络层才能稳定地把原始 JSON 变成类型安全的数据。