JSON 转 Kotlin 数据类 — kotlinx.serialization、Gson 或 Moshi

真实使用场景

• 接 Retrofit 响应时不再手写 model

  你在 Android app 里用 Retrofit + Moshi 调一个第三方 REST API, 响应 有 25 多个字段, 是 snake_case。curl 一次, 把 JSON 粘进来, 根名设为 `OrderResponse`, 选 Moshi。每个 `created_at` 这样的 key 都会加 `@Json(name = ...)`, 让转换器绑得上, 嵌套对象抽成自己的类, 可选字段 变成 `T?`。把输出放进 `OrderResponse.kt`, 声明 `@GET("orders") suspend fun orders(): OrderResponse`, 你就拿到一个 完全类型化的结果, 而不是一个要你一个字段一个字段强转的 `Map<String, Any?>`。

• 给 Ktor 服务写 kotlinx.serialization 模型

  你在写一个 Ktor 后端, 想给新 endpoint 弄一个请求和响应 model。粘进 请求 body 样例, 根名 `CreateOrderRequest`, 保持 kotlinx.serialization。 你拿到一个 `@Serializable data class`, 改名的字段上带 `@SerialName`, 以及它需要的精确 import。打开默认值, 这样缺失的 key 能干净地解码而 不是抛异常, 当 payload 里哪天冒出一个新的可选字段时, 这个 model 是 向前兼容的。

• 看清 webhook 里到底哪些字段是可选的

  某第三方的 webhook 有时带 `cancelled_at`, 有时不带。把几次 payload 记下来, 作为 JSON 数组粘进来, 数组折叠的检测会标出 `cancelled_at` 在某些元素里缺失, 于是它变成 `String?`, 而不是一个反序列化时会崩 的非空字段。在 handler 里做个 `?.let { }`, 现在就能干净地区分 "已取消"和"仍有效", 不用再猜某个默认值是不是代表字段没发。

• 把 Java DTO 迁成地道的 Kotlin data class

  你在把一个 Android 模块从 Java 移到 Kotlin, 一个 Gson 绑定的 POJO 要变成 data class。抓一个有代表性的 JSON 响应粘进来, 选 Gson, 你会 拿到带 `@SerializedName` 注解的 `val` 属性, 都在一个 `data class` 里, 没有 getter、没有 `equals`/`hashCode` 样板, 还白送 `copy()`。 新类的行数只有 Java 原版的一小部分, 读起来跟它建模的 JSON 一模一样。

• 把 Map<String, Any?> 换成真正的类型

  老 Kotlin 代码是 `val data: Map<String, Any?> = parse(body)`, 然后用 `data["id"] as String` 这样的强转一层层挖, 丢掉了所有编译期检查, 还招来运行时的 `ClassCastException`。抓一个有代表性的响应粘进来, 生成 data class, 替换掉这个 map。现在 `Int`、`Long`、`Double` 在每个 字段上都推断好了, 可空性是显式的, 改个 key 名编译期就会报错, 而不是 上线后才出问题。

常见踩坑

• 粘一个对象进来然后期待某些字段可空。单个对象没有“key 缺失”信号, 所以除非值本身就是 null, 否则每个字段都是非空的。可空推断只在“多个对象组成的数组”里生效 (有的元素带某个 key、有的不带)。想从一个样本探索可选性, 把它包成 `[{...}]`。

• 把金额或需要精确小数的字段留成 `Double`。工具对任何带小数的数字都推断成 `Double`, 但 `Double` 是二进制浮点, 会把 0.1 或货币总额这类值表示错。金额请在生成后改成 `BigDecimal`。JSON 不带“这个数字需要精确十进制精度”的任何信号。

• 忘了 kotlinx.serialization 的 Gradle 插件和运行时。`@Serializable` 注解既要 `org.jetbrains.kotlin.plugin.serialization` Gradle 插件, 也要 `kotlinx-serialization-json` 依赖; 没有插件代码编译不过。如果你只想要朴素的类, 改选“无”注解风格。

• 删掉 @SerialName / @Json / @SerializedName 注解还指望绑定照常工作。这个注解正是把 `site_admin` (线上) 映射到 `siteAdmin` (属性) 的东西。删了它, 序列化库会去找一个根本不存在的 `siteAdmin` key, 字段就留成 null 或者解码失败。要么留着注解, 要么配一个全局命名策略。

隐私说明