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

04.8.4.1 kotlinx.serialization 与 kotlinx-datetime

所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.8 Kotlin / 04.8.4 常用库与序列化

本节要解决的问题

本节覆盖 kotlinx.serialization 编译器插件机制、@Serializable 与自定义 Serializer、字段注解、默认值与必填规则、sealed 多态序列化、Json 配置项、与 Retrofit/Ktor 集成、性能与混淆规则,以及 kotlinx-datetime 的 Instant/LocalDate/TimeZone 模型、时区常见坑与和 java.time 的互操作。版本基线:kotlinx.serialization 1.7.x、kotlinx-datetime 0.6.x、Kotlin 2.x。

04.8.4.1-001 kotlinx.serialization 是什么,与反射式序列化框架有何不同?

一句话结论

kotlinx.serialization 是 JetBrains 的跨平台序列化框架,通过编译器插件在编译期为标注类型生成序列化器,运行时不靠反射读字段;支持 JVM/JS/Native 等多平台,序列化/反序列化在生成的 Serializer 代码上完成。

概念解释

  • 编译期生成:每个可序列化类型对应一个 serializer。
  • 跨平台:不依赖 JVM 反射能力。
  • 核心类型:@Serializable、KSerializer、Json、Encoder/Decoder。

原理流程

  1. 插件识别 @Serializable 标注的类。
  2. 编译期生成序列化器(结构、字段、编解码逻辑)。
  3. 运行时 Json 格式按生成器读写对象。
  4. 嵌套类型递归使用各自生成的 serializer。

代码或图示

@Serializable
data class User(val id: Long, val name: String)

常见误区

  • 以为它和 Jackson 一样运行时反射:kotlinx 主要走编译期生成代码。
  • 以为不加插件也能序列化:缺少编译器插件,生成器与编译入口都不存在。

追问

  • 跨平台意义是什么?答:Native/JS 没有 JVM 反射,编译期生成器是跨平台基础。
  • 序列化器在哪里取?答:User.serializer() 或 serializer<User>()。

04.8.4.1-002 一个类被 @Serializable 标注后发生了什么?

一句话结论

注解触发编译器插件为该类生成配套的 KSerializer:负责遍历属性、编码到编码器/从解码器读取;主构造参数需要可序列化,嵌套类型同样要有 serializer;生成器随类一同编译进产物。

概念解释

  • 生成器绑定类的主构造属性。
  • 属性类型必须可序列化或有自定义 serializer。
  • 伴生对象生成 .serializer() 工厂方法。

原理流程

  1. 插件分析主构造参数与类型。
  2. 为每个属性解析对应 serializer。
  3. 生成 serialize/deserialize 实现。
  4. 运行时格式(Json)调用生成器读写。

代码或图示

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

常见误区

  • 类里有不可序列化类型却不处理:编译期报缺少 serializer。
  • 把 @Serializable 当运行时开关:它是给插件的编译指令。

追问

  • 私有/派生属性会被序列化吗?答:默认只序列化主构造属性,派生字段需按注解规则处理。
  • 枚举类如何标注?答:枚举可直接序列化,默认按名称编码。

04.8.4.1-003 编译器插件在构建脚本里如何接入?

一句话结论

需要在构建脚本应用 kotlinx.serialization 编译器插件并声明序列化库依赖;Kotlin 2.x 可使用 plugins DSL 声明插件 id,旧版本用 legacy apply 方式;插件版本与 Kotlin 版本配套,依赖坐标与插件写法以项目构建配置为准(待确认)。

概念解释

  • 插件参与编译期生成代码。
  • 运行时库提供 Json 等格式实现。
  • 插件版本与 Kotlin 编译器版本配套。

原理流程

  1. 构建脚本声明 serialization 插件。
  2. 编译时插件处理 @Serializable 类。
  3. 依赖引入运行时序列化库。
  4. 生成器链接到 Json 格式实现。

代码或图示

// Gradle plugins 片段示意;实际坐标与版本以项目构建文件为准
// id "org.jetbrains.kotlin.plugin.serialization"
// implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.x")

常见误区

  • 只加运行时依赖不加插件:编译期不生成 serializer。
  • 插件版本与 Kotlin 版本不配套:编译报错或行为异常。

追问

  • 多平台项目插件怎么配?答:在公共源码集应用插件,各平台共享生成器能力。
  • 插件坐标在哪查?答:官方文档与项目现有 build 脚本,不凭记忆写版本号。

04.8.4.1-004 序列化与反序列化的基本 API 怎么用?

一句话结论

Json.encodeToString(value) 把对象编码为字符串,Json.decodeFromString<T>(string) 解码为对象;可显式传入 serializer,或利用反射式 serializer<T>() 辅助获取;编码失败抛序列化异常,解码时校验字段与类型。

概念解释

  • encode:对象 → 字符串/原始格式。
  • decode:字符串 → 对象。
  • 泛型 reified 辅助简化调用。

原理流程

  1. 选择 Json 实例(可配选项)。
  2. encodeToString 调用生成器写出属性。
  3. decodeFromString 读字段并调用构造。
  4. 类型不匹配/缺失字段按配置抛异常或用默认值。

代码或图示

val json = Json.encodeToString(User(1, "Ann"))
val user = Json.decodeFromString<User>(json)

常见误区

  • decode 目标类型没有 serializer:编译期/运行时报缺少序列化器。
  • 直接把任意字符串当合法 JSON:解码异常需捕获处理。

追问

  • 序列化到字节数组用什么?答:对应 BinaryFormat 或 Json 输出工具,具体 API 以库版本为准。
  • 集合如何序列化?答:标准集合类型由框架提供内置 serializer,元素类型需可序列化。

04.8.4.1-005 哪些类型可以被 kotlinx.serialization 序列化?

一句话结论

标注 @Serializable 的 data class/类、枚举、标准基本类型、字符串、标准集合(List/Map/Set 等)、以及有 serializer 的自定义类型都支持;未标注且无自定义 serializer 的类型、函数引用、线程/连接等运行时对象不能直接序列化。

概念解释

  • 支持类型:基础类型、枚举、集合、可标注类。
  • 组合:嵌套可序列化类型递归。
  • 不支持:运行时资源、lambda、非结构化对象。

原理流程

  1. 解析目标类型的 serializer。
  2. 基础类型由内置编码器处理。
  3. 集合按元素类型递归编解码。
  4. 缺失 serializer 时编译报错或需自定义。

代码或图示

@Serializable
data class Report(
    val tags: List<String>,
    val metadata: Map<String, String>
)

常见误区

  • 把包含 Date/流/连接的对象直接序列化:需映射为可传输值类型。
  • 内部可变类未标注:嵌套序列化失败。

追问

  • 第三方库类型怎么办?答:写自定义 serializer 或映射到本地 DTO。
  • 泛型类能序列化吗?答:可以,泛型参数需可序列化,序列化器随参数类型解析。

04.8.4.1-006 @SerialName 注解的作用是什么?

一句话结论

@SerialName("name") 覆盖属性在序列化格式中的字段名,解决 Kotlin 属性名与外部 JSON 字段名不一致(如下划线命名、缩写)的问题;不改变 Kotlin 属性本身的名称,只影响编解码时的键名。

概念解释

  • 字段映射:属性 ↔ 外部键。
  • 常用于 snake_case JSON 与 camelCase 属性对应。
  • 每个属性可单独覆盖。

原理流程

  1. 生成器读取属性上的 @SerialName。
  2. 编码时用注解名写出键。
  3. 解码时按注解名读取字段。
  4. 未标注则使用属性本名。

代码或图示

@Serializable
data class User(
    @SerialName("user_id") val userId: Long,
    val name: String
)

常见误区

  • 以为注解改了属性名:Kotlin 侧仍叫原属性名。
  • 解码时 JSON 键与注解名不匹配:字段缺失按配置处理。

追问

  • 全局命名策略怎么配?答:Json 配置 namingStrategy(支持项以版本为准,待确认),单字段仍可用注解覆盖。
  • 枚举值能改名吗?答:枚举常量可用 @SerialName 映射外部字符串。

04.8.4.1-007 @Transient 与默认忽略规则有何区别?

一句话结论

@Transient 标注的属性不参与序列化,解码时该属性必须有默认值;对比无注解的主构造属性默认都参与编解码;transient 属性不能从外部格式恢复,依赖类内默认值或派生逻辑。

概念解释

  • 排除字段:不写出、不读取。
  • 必须有默认值:否则反序列化无法构造。
  • 适合临时缓存、派生运行时状态。

原理流程

  1. 生成器跳过 @Transient 属性。
  2. 编码输出中不含该字段。
  3. 解码时使用属性默认值。
  4. 无默认值的 transient 属性构造失败。

代码或图示

@Serializable
data class CacheEntry(
    val key: String,
    @Transient val loadedAt: Long = 0L
)

常见误区

  • transient 属性不设默认值:反序列化构造报错。
  • 把需要持久化的运行时状态误标 transient:丢失数据。

追问

  • 派生只读属性会被序列化吗?答:默认只处理主构造属性;类体属性需按插件规则与注解处理(细节待确认)。
  • 排除字段还有其他方式吗?答:自定义 serializer 中跳过该属性。

04.8.4.1-008 自定义 Serializer 在什么场景下需要?

一句话结论

当类型不能直接标注(第三方类、平台类型、格式特殊)或字段编解码规则特殊(日期格式、数值映射、嵌套结构拍平)时,实现 KSerializer<T> 或用 @Serializable(with=...) 绑定;普通 data class 优先依赖生成器。

概念解释

  • 第三方类型:无源码加注解。
  • 格式定制:编码成非默认结构。
  • 绑定方式:类注解或属性注解指定 serializer。

原理流程

  1. 定义对象实现 KSerializer,含 descriptor、serialize、deserialize。
  2. 在类/属性上用 @Serializable(with = XSerializer::class) 绑定。
  3. 编码器/解码器调用自定义逻辑。
  4. 嵌套类型复用该 serializer。

代码或图示

@Serializable(with = LocalDateSerializer::class)
data class ExternalDate(val value: String)

常见误区

  • 能标注的简单类也手写 serializer:重复造轮子,维护成本高。
  • 自定义 descriptor 字段名与实际编解码不一致:解码错乱。

追问

  • 序列化器能复用给多个类吗?答:通用结构可复用,字段映射在 descriptor 中声明。
  • 上下文多态 serializer 是什么?答:配合多态格式按类型标记选择序列化器,见多态题。

04.8.4.1-009 @Serializable(with = ...) 如何绑定到类或属性?

一句话结论

类级 @Serializable(with = Serializer::class) 为整个类指定自定义序列化器;属性级注解只覆盖该属性的序列化器;绑定后生成器/框架在对应位置使用指定 serializer,属性类型与 serializer 必须匹配。

概念解释

  • 类级:替代默认生成器。
  • 属性级:局部覆盖嵌套类型的编解码。
  • 优先级:属性绑定优先于类绑定。

原理流程

  1. 编译器/运行时解析注解指定的 serializer。
  2. 类绑定:整个对象走自定义 serialize/deserialize。
  3. 属性绑定:该属性读写时使用指定 serializer。
  4. descriptor 提供字段结构给格式层。

代码或图示

@Serializable
data class Event(
    @Serializable(with = InstantLongSerializer::class)
    val at: Instant
)

常见误区

  • serializer 泛型类型不匹配:编译/运行类型错误。
  • 类级自定义后仍期待生成默认字段逻辑:需自己实现完整编解码。

追问

  • 同一类型在不同位置能用不同 serializer 吗?答:属性级绑定可局部覆盖,类级是全局默认。
  • 自定义 serializer 如何注册到多态?答:配合 SerializersModule 与多态类标注。

04.8.4.1-010 反序列化时字段缺失会发生什么?

一句话结论

默认情况下必填属性缺失会抛序列化异常;属性有默认值时缺失则使用默认值;@Transient 属性同样依赖默认值;是否宽松处理缺失字段还受 Json 配置(如 coerceInputValues 等)影响,具体行为以版本配置为准(待确认)。

概念解释

  • 必填无默认值:缺失即失败。
  • 有默认值:缺失回退默认。
  • 配置项影响容错程度。

原理流程

  1. 解码器读取 JSON 字段集合。
  2. 逐个属性匹配键。
  3. 缺失且无默认值 → 抛异常。
  4. 有默认值则使用默认值构造对象。

代码或图示

@Serializable
data class Config(val host: String, val port: Int = 8080)
// JSON 不含 port 时使用 8080

常见误区

  • 以为缺字段都能静默跳过:无默认值的必填字段会失败。
  • 依赖默认值处理外部坏数据:应在业务层校验配置合法性。

追问

  • 多余字段默认怎么处理?答:受 ignoreUnknownKeys 配置控制,默认可能报错或忽略,见 Json 配置题。
  • 字段为 null 与缺失是一回事吗?答:不是,显式 null 与缺键在 explicitNulls 配置下行为不同。

04.8.4.1-011 属性默认值在序列化中如何参与?

一句话结论

默认值主要服务反序列化:输入缺失该字段时回退默认值;编码时默认值是否仍写出受配置控制(如 encodeDefaults);序列化不会为了「等于默认值」自动省略字段,除非开启对应配置。

概念解释

  • 解码回退:缺字段用默认值。
  • 编码写出:默认值默认仍按属性值编码。
  • 省略默认值需显式配置。

原理流程

  1. 解码:缺失 → 默认值;存在 → 输入值。
  2. 编码:遍历属性写出值。
  3. encodeDefaults 配置控制默认值是否参与编码。
  4. 配合忽略未知键容错输入侧。

代码或图示

@Serializable
data class Paging(val page: Int = 1, val size: Int = 20)

常见误区

  • 以为默认值字段不会出现在输出 JSON:默认仍写出,除非配置省略。
  • 解码后默认值被外部 null 覆盖:可空性与 explicitNulls 决定行为。

追问

  • encodeDefaults 默认值?答:以 Json 配置默认行为为准(待确认),显式开启/关闭。
  • 默认值是可变集合时注意什么?答:共享默认集合引用需评估可变共享风险。

04.8.4.1-012 可空属性与 explicitNulls 配置如何影响 JSON 输出?

一句话结论

可空属性允许输入 null;explicitNulls 控制编码时是否显式写出 null 字段、解码时如何处理 null 与缺键:开启时 null 作为显式值参与编码,关闭时 null 属性可省略;配置改变 JSON 字段的 null 表达,需与外部接口约定一致。

概念解释

  • 可空类型:String? 允许 null。
  • explicitNulls:null 是否显式编码。
  • 缺键与 null 语义在配置下区分。

原理流程

  1. 编码可空属性:按 explicitNulls 决定写出 null 还是省略。
  2. 解码:显式 null 赋 null;缺键按默认值/可空规则处理。
  3. 配置影响生成 JSON 的字段存在性。
  4. 与后端字段约定对齐避免解析差异。

代码或图示

val json = Json { explicitNulls = false }

常见误区

  • 前后端对 null 与缺键理解不一致:字段缺失被错认为 null 或反之。
  • 关闭 explicitNulls 后依赖 null 字段存在:下游解析不到键。

追问

  • 不可空属性收到 null 会怎样?答:解码类型不匹配抛异常,coerceInputValues 可能提供容错(见配置题)。
  • explicitNulls 默认值?答:以当前版本 Json 默认配置为准(待确认)。

04.8.4.1-013 sealed 类层次为什么需要多态序列化?

一句话结论

sealed/继承层次在 JSON 中只存对象结构无法区分子类型,多态序列化需要类型标记(class discriminator)记录子类型信息,解码时按标记选择对应 serializer;否则反序列化无法还原正确子类。

概念解释

  • 多态:父类型引用指向不同子类。
  • 类型标记:JSON 中保留子类标识字段。
  • 解码器按标记分派 serializer。

原理流程

  1. 序列化父类型时写入类型标记 + 子类字段。
  2. 解码器读标记,查注册表找子类 serializer。
  3. 按子类结构解码。
  4. 未注册的子类标记解码失败。

代码或图示

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

常见误区

  • 不配置多态注册:解码不知道标记对应哪个类。
  • 子类未标注 @Serializable:多态生成器缺失。

追问

  • 类型标记字段默认叫什么?答:默认 discriminator 名称以库版本为准(常见为 "type",待确认),可配置改名。
  • sealed 与开放继承多态配置有何差别?答:sealed 子类封闭可枚举,开放层次需注册所有可序列化子类。

04.8.4.1-014 多态序列化的类型标记如何配置?

一句话结论

通过 Json 配置设置 class discriminator 字段名,子类用 @SerialName 或注册模块提供标记名;SerializersModule 注册父类型到子类的映射;标记名与后端协议约定一致,解码时按标记分派。

概念解释

  • discriminator:类型标识键名。
  • 子类标记:类名或 @SerialName 值。
  • 模块:多态映射注册表。

原理流程

  1. Json 配置 discriminator 字段名。
  2. SerializersModule 绑定父类与子类 serializer。
  3. 编码写标记 + 子类数据。
  4. 解码读标记查表还原子类。

代码或图示

val json = Json {
    classDiscriminator = "kind"
    serializersModule = module
}

常见误区

  • 标记名与后端不一致:解码识别不到子类。
  • 新增子类忘记注册:遇到该标记解码失败。

追问

  • 注册模块怎么构造?答:SerializersModule { polymorphic(Message::class) { subclass(Text::class); subclass(Image::class) } }。
  • sealed 类需要显式注册吗?答:编译器对 sealed 层次有自动支持程度,细节以版本文档为准(待确认)。

04.8.4.1-015 多态反序列化遇到未知子类标记怎么办?

一句话结论

未注册的类型标记默认解码失败抛异常;容错策略取决于配置与自定义解码器,可选择忽略为默认基类或错误上报;不能静默丢弃结构化数据,未知类型应记录并按业务降级处理。

概念解释

  • 标记无对应 serializer → 无法构造子类。
  • 严格模式失败,宽松模式需自定义处理。
  • 前后端版本演进可能出现新类型。

原理流程

  1. 解码器读标记值。
  2. 查模块映射,命中则解码子类。
  3. 未命中抛未知类异常。
  4. 业务层捕获并记录未知类型。

代码或图示

// 未知标记进入序列化异常,调用方捕获并降级

常见误区

  • 假设后端类型集合不变:新版本新增消息类型会打到旧客户端。
  • 吞掉未知类型异常:丢失消息且无日志。

追问

  • 如何向前兼容?答:保留未知原始 JSON,必要时自定义基类承载原始字段,升级后解析。
  • 多态错误属于编译期还是运行时?答:注册与标记匹配主要发生在解码运行时。

04.8.4.1-016 SerializersModule 解决什么问题?

一句话结论

SerializersModule 是序列化器注册表:提供类型到 serializer 的映射,用于多态子类注册、自定义类型绑定与上下文传递;Json 实例配置 module 后,编解码时按类型从中查找所需 serializer。

概念解释

  • 集中注册自定义/多态映射。
  • 模块可组合复用。
  • 嵌套与泛型类型按规则解析。

原理流程

  1. 构造模块,注册多态子类与自定义 serializer。
  2. Json 实例挂载该模块。
  3. 编解码遇到类型先查模块。
  4. 未找到再用默认生成器/内置支持。

代码或图示

val module = SerializersModule {
    polymorphic(Message::class) {
        subclass(Text::class)
        subclass(Image::class)
    }
}

常见误区

  • 多态映射不挂到 Json 模块:解码分派失败。
  • 模块在不同 Json 实例间混用:配置不一致导致解析差异。

追问

  • 模块能跨模块共享吗?答:可组合合并,公共映射放共享模块。
  • 上下文元素如何通过模块传递?答:模块可携带上下文 serializer 信息,具体 API 以版本为准(待确认)。

04.8.4.1-017 Json 配置 ignoreUnknownKeys 的作用与风险是什么?

一句话结论

ignoreUnknownKeys = true 解码时忽略 JSON 中目标类没有的字段,避免后端新增字段导致旧客户端解析失败;风险是多余字段被静默丢弃,关键契约变更得不到感知,应在兼容演进场景开启并保留日志校验。

概念解释

  • 输入容错:忽略未知键。
  • 默认严格:未知键可能报错(默认值以版本为准,待确认)。
  • 兼容旧客户端应对后端加字段。

原理流程

  1. 解码器遍历 JSON 键。
  2. 匹配类属性则读取。
  3. 未匹配且配置忽略则跳过。
  4. 未忽略则抛未知字段异常。

代码或图示

Json { ignoreUnknownKeys = true }

常见误区

  • 所有服务端接口都开忽略:字段拼写错误被静默吞掉。
  • 以为忽略未知键会忽略类型错误:类型不匹配仍会失败。

追问

  • 忽略未知键影响编码吗?答:只影响解码输入侧,编码仍只输出类属性。
  • 如何感知后端新增字段?答:调试期保留严格模式校验,兼容期开启忽略并记录原始报文。

04.8.4.1-018 coerceInputValues 在解码时做什么?

一句话结论

coerceInputValues = true 对无法合法映射到目标类型的输入(如非法枚举值、类型不兼容)按可容错策略回退默认值或默认状态,而不是直接抛异常;用于面对脏数据的宽松解析,但会掩盖输入错误,需评估业务可接受度。

概念解释

  • 输入容错:非法值回退默认。
  • 适用枚举、部分数值/可空场景。
  • 掩盖脏数据是主要风险。

原理流程

  1. 解码器读取输入值。
  2. 类型/合法性校验失败。
  3. 开启 coerce:回退默认值。
  4. 未开启:抛解码异常。

代码或图示

Json { coerceInputValues = true }

常见误区

  • 把脏数据当合法默认值入库:业务语义错误被掩盖。
  • 以为它能修复任意结构错误:只覆盖特定可强制转换场景。

追问

  • 哪些类型支持 coerce?答:枚举与部分内置类型,具体可强制集合以官方文档为准(待确认)。
  • 与 ignoreUnknownKeys 配合?答:一个忽略多余键,一个容错非法值,两者分别作用于不同错误。

04.8.4.1-019 isLenient 宽松解析影响哪些 JSON 规则?

一句话结论

isLenient 放宽 JSON 语法解析(如非标准引号、数值格式等宽松输入),用于兼容历史/非严格数据源;严格协议接口应关闭,避免接受不合规报文掩盖上游问题;支持的宽松范围以官方文档为准(待确认)。

概念解释

  • 严格 JSON:标准语法。
  • 宽松模式:容忍部分非标准写法。
  • 安全与规范取舍。

原理流程

  1. 解码器按模式解析 token。
  2. 宽松模式接受额外合法变体。
  3. 严格模式拒绝非标准语法。
  4. 解析结果映射到目标类型。

代码或图示

Json { isLenient = true }

常见误区

  • 公网接口默认开宽松:接受畸形输入,安全校验缺失。
  • 以为宽松模式能解析任意格式:仍限于 JSON 结构变体。

追问

  • 宽松模式影响编码输出吗?答:主要影响解码输入侧,编码仍输出标准 JSON。
  • 数值精度问题宽松能解决吗?答:不能,数值溢出/精度需类型层处理。

04.8.4.1-020 prettyPrint 与命名策略属于编码侧还是解码侧?

一句话结论

prettyPrint 控制输出 JSON 缩进格式化,属于编码侧;命名策略(属性名转换)同时影响编码键名与解码匹配;解码侧容错由 ignoreUnknownKeys/coerceInputValues/isLenient 等控制,配置项按方向区分。

概念解释

  • 编码:输出格式与键名。
  • 解码:输入容错与匹配。
  • Json 实例配置可同时作用于两侧对应项。

原理流程

  1. 编码:prettyPrint 决定缩进,命名策略转换键名。
  2. 解码:按命名策略匹配输入键。
  3. 容错配置处理未知键与非法值。
  4. 同一 Json 实例配置两侧行为。

代码或图示

Json {
    prettyPrint = true
    // namingStrategy 配置以版本支持为准
}

常见误区

  • 以为 prettyPrint 影响解析性能判断:它只影响输出格式,不改变数据模型。
  • 编码改名后解码端未配同名策略:键匹配失败。

追问

  • prettyPrint 对生产报文建议?答:生产输出可关闭缩进减小体积,调试开启。
  • 命名策略有哪些实现?答:snake_case 等内置/自定义策略,支持列表以版本文档为准(待确认)。

04.8.4.1-021 同一个 Json 实例为什么建议复用?

一句话结论

Json 实例持有配置、模块与序列化器缓存,复用可避免重复初始化配置与解析上下文;不同容错/命名需求可建不同实例;每次编码都新建 Json 会带来无谓开销,且配置分散容易不一致。

概念解释

  • 实例 = 配置 + 模块 + 缓存。
  • 复用降低初始化成本。
  • 不同协议需求分离实例。

原理流程

  1. 应用初始化配置好 Json 单例。
  2. 编解码统一引用该实例。
  3. 需要不同策略时新建专用实例。
  4. 模块注册与序列化器查找共享缓存。

代码或图示

val defaultJson = Json { ignoreUnknownKeys = true }

常见误区

  • 各处随手 Json { ... } 新建:配置漂移、重复初始化。
  • 把可变配置改来改去复用同一实例:不同调用方行为互相影响。

追问

  • Json 实例线程安全吗?答:设计为可并发复用,具体线程保证以官方文档为准(待确认)。
  • 实例缓存了什么?答:序列化器查找与模块映射,重复类型解析受益。

04.8.4.1-022 序列化 data class 时类体中的方法/字段会被处理吗?

一句话结论

默认只序列化主构造函数声明的属性;类体中的方法、派生属性、临时缓存字段不自动参与编解码,需要参与时通过注解或自定义 serializer 显式纳入;运行时方法行为不进入数据格式。

概念解释

  • 序列化对象是数据状态,不是行为。
  • 主构造属性是默认数据源。
  • 类体字段需显式配置。

原理流程

  1. 生成器分析主构造参数。
  2. 类体方法不生成编解码逻辑。
  3. 派生属性按需标注处理。
  4. 自定义 serializer 可选择纳入额外字段。

代码或图示

@Serializable
data class User(val name: String) {
    val displayName: String get() = "Hello $name" // 默认不序列化
}

常见误区

  • 把派生状态当持久化字段:解码后重算而非从输入恢复。
  • 类体可变缓存字段被意外纳入:状态不可跨进程恢复。

追问

  • 派生属性如何持久化?答:转为主构造属性或在自定义 serializer 中处理。
  • 兼容新增属性怎么做?答:加默认值,保证旧输入可解码。

04.8.4.1-023 与 Retrofit 集成时 kotlinx.serialization 怎么接入?

一句话结论

Retrofit 通过对应的 kotlinx.serialization Converter Factory 把响应体反序列化为标注类型、把请求体序列化;接口方法使用 Kotlin data class 作为参数/返回值,Converter 内部用配置好的 Json 实例处理编解码;具体 converter 坐标以项目依赖为准(待确认)。

概念解释

  • Converter Factory 桥接 Retrofit 与序列化库。
  • 数据模型是 @Serializable data class。
  • Json 容错配置在工厂创建时传入。

原理流程

  1. 创建带 Json 配置的 serialization converter。
  2. Retrofit.Builder 添加该 converter。
  3. 接口声明 DTO 类型。
  4. 响应字节流转 DTO,请求 DTO 转报文。

代码或图示

// 示意:工厂接入方式与依赖坐标以项目构建为准
// Retrofit.Builder().addConverterFactory(SerializationConverterFactory.create(json))

常见误区

  • DTO 漏标 @Serializable:converter 找不到 serializer。
  • 复用错误 Json 配置:忽略未知键/严格模式与后端约定不符。

追问

  • 协程挂起方法能直接返回 DTO 吗?答:Retrofit 支持 suspend 接口方法,converter 在后台线程完成解码。
  • 错误响应体如何解析?答:定义错误 DTO 或自定义 converter/拦截器处理错误报文。

04.8.4.1-024 与 Ktor 集成时序列化如何配置?

一句话结论

Ktor 内容协商(content negotiation)插件配置 kotlinx.serialization 为 JSON 转换器,注册 Json 实例与模块;请求/响应 DTO 使用可序列化类型,插件在端点自动编解码;Ktor 也可直接调用 Json 工具处理手动报文。

概念解释

  • 插件按 Content-Type 选择转换器。
  • Json 配置在插件块内声明。
  • 路由处理器收发 DTO 对象。

原理流程

  1. 安装 contentNegotiation 插件。
  2. 配置 JSON 转换器与 Json 实例。
  3. 客户端请求带 body,插件解码为 DTO。
  4. 响应 DTO 编码为 JSON 写出。

代码或图示

install(ContentNegotiation) {
    json(Json { ignoreUnknownKeys = true })
}

常见误区

  • DTO 未注册序列化器:插件解码失败。
  • 前后端 Content-Type 不匹配:转换器不被选中。

追问

  • Ktor 客户端如何配置?答:客户端同样安装内容协商并配置 JSON 转换器,写法与服务端对应。
  • 多格式(JSON/表单)如何共存?答:插件按格式注册多个转换器。

04.8.4.1-025 序列化模型与领域模型为什么常分层为 DTO?

一句话结论

DTO 专用于报文结构,保持可序列化、字段贴近外部协议;领域模型包含行为与内部状态,不直接暴露给序列化层;两层之间做映射,避免外部协议变化污染领域对象,也避免运行时状态被错误持久化。

概念解释

  • DTO:数据传输,可序列化。
  • Domain:业务行为与内部状态。
  • 映射层隔离协议变化。

原理流程

  1. 外部报文解码为 DTO。
  2. DTO 映射为领域对象。
  3. 领域操作后反向映射 DTO。
  4. 序列化注解只存在于 DTO 层。

代码或图示

@Serializable
data class UserDto(val id: Long, val name: String)

data class User(val id: UserId, val displayName: String)

常见误区

  • 领域类直接加序列化注解:运行时状态与协议耦合。
  • DTO 暴露可变集合引用给领域层:共享可变状态风险。

追问

  • 简单 CRUD 可以不分层吗?答:可以,但演进后协议变化会反噬模型;按复杂度权衡。
  • 映射放哪一层?答:仓库/API 层做 DTO ↔ Domain 转换。

04.8.4.1-026 序列化在混淆(R8/ProGuard)下需要保留什么?

一句话结论

kotlinx.serialization 走编译期生成器,但仍需按库文档配置混淆规则:保留生成的 serializer 类、@Serializable 标注的模型类及其无参/构造反射相关成员;第三方序列化库规则随官方 consumer ProGuard 规则引入,具体 keep 规则以库版本文档为准(待确认)。

概念解释

  • 生成器类可能被混淆重命名。
  • 反射/枚举/模块注册需保留入口。
  • 官方规则通常随 artifact 附带。

原理流程

  1. 引入库自带 consumer ProGuard 规则。
  2. 按文档补充模型类与 serializer keep。
  3. 混淆后打包验证解码正常。
  4. 多态注册的子类不能被裁剪。

代码或图示

# 规则示例以官方文档为准;不手写未经验证的 keep 通配

常见误区

  • 以为编译期生成完全不需要 keep:多态/反射入口仍可能被裁剪。
  • 混淆后只在调试包验证:Release 包解码崩溃难复现。

追问

  • 如何验证混淆后序列化?答:Release 构建跑接口解码冒烟测试,检查多态与枚举解析。
  • 规则在哪里查?答:kotlinx.serialization 官方文档与 artifact 内 proguard 配置。

04.8.4.1-027 序列化性能主要消耗在哪些环节?

一句话结论

性能开销包括:反射/模块查找(编译期生成器已降低)、字符串与集合编解码、对象构造、Json 文本解析与分配;优化方向是复用 Json 实例、避免中间 DTO 拷贝、选用二进制格式、控制大对象字段与集合分配;具体基准以实测为准,不凭记忆断言数字。

概念解释

  • 生成器相比反射减少运行时查找。
  • JSON 文本解析与对象分配是主要成本。
  • 高频接口关注对象复用与格式选择。

原理流程

  1. 编码遍历属性写 token。
  2. 解码读 token 构造对象。
  3. 中间集合/字符串产生分配。
  4. 压测定位热点字段与转换环节。

代码或图示

// 复用配置好的 Json 实例,避免每次新建

常见误区

  • 过早优化二进制格式:先确认 JSON 是否为瓶颈。
  • 忽略大列表逐元素分配:批量数据需关注内存与 GC。

追问

  • 有哪些非 JSON 格式?答:库提供二进制格式支持(如 ProtoBuf 等),具体可用格式以版本为准(待确认)。
  • 性能基准怎么测?答:JVM 微基准结合真实报文规模,对比编解码吞吐与分配。

04.8.4.1-028 解码大集合时内存与性能需要注意什么?

一句话结论

大集合解码会一次性构造全部元素与中间结构,内存随元素总量增长;流式/按需解析能力取决于格式与 API(具体支持以版本为准,待确认);接口设计应分页限制批量大小,避免单次反序列化超大列表造成堆压力与长停顿。

概念解释

  • 默认整体构造:全量对象进入内存。
  • 分页降低单次解码规模。
  • 元素不可变设计减少后续拷贝。

原理流程

  1. 报文读入后解析集合。
  2. 逐个元素构造 DTO 入列表。
  3. 列表整体返回上层。
  4. 大批量导致峰值内存与 GC 压力。

代码或图示

// 接口分页:page + size,控制单次集合规模

常见误区

  • 一次性加载全量历史列表:堆峰值与解码耗时双高。
  • 解码后再拷贝一遍列表:分配翻倍。

追问

  • 能否逐元素流解码 JSON?答:查库流式 API 支持,不确定处标注待确认。
  • 大字段如何裁剪?答:DTO 只保留接口需要的字段,避免携带冗余嵌套对象。

04.8.4.1-029 枚举序列化默认按什么编码,自定义如何做?

一句话结论

枚举默认按常量名称字符串编码;可用 @SerialName 为单个常量映射外部字符串;未知枚举值的容错受 coerceInputValues 等配置影响;枚举序列化不依赖枚举序号,避免序号重排导致错配。

概念解释

  • 名称编码:可读且稳定。
  • 序号编码脆弱:顺序调整会改变含义。
  • 注解做名称映射。

原理流程

  1. 编码写出枚举常量名(或注解名)。
  2. 解码按名称匹配枚举常量。
  3. 未匹配按配置抛异常或 coerce 回退。
  4. 序号不参与默认编解码。

代码或图示

@Serializable
enum class Status {
    @SerialName("ok") ACTIVE,
    @SerialName("disabled") INACTIVE
}

常见误区

  • 依赖枚举序号传输:插入/重排常量后序号错位。
  • 后端返回新枚举值旧端未容错:解码失败。

追问

  • 枚举可空与缺失如何处理?答:可空类型接受 null,缺失按默认值规则。
  • 枚举顺序变更影响序列化吗?答:名称编码下不影响,序号方案才脆弱。

04.8.4.1-030 自定义 serializer 的 descriptor 有什么作用?

一句话结论

SerialDescriptor 描述被序列化类型的结构:名称、元素个数、字段名与类型标记,供格式层(Json)组织输出与校验结构;serialize/deserialize 必须与 descriptor 声明的字段一致,否则编解码错位。

概念解释

  • descriptor 是结构元数据。
  • 字段名与顺序影响 JSON 键。
  • 多态/集合格式依赖 descriptor 分派。

原理流程

  1. 定义 descriptor 列出字段名与类型。
  2. serialize 按字段顺序写值。
  3. deserialize 按 descriptor 读值构造对象。
  4. 格式层依据 descriptor 生成/校验结构。

代码或图示

override val descriptor: SerialDescriptor =
    PrimitiveSerialDescriptor("ExternalDate", PrimitiveKind.STRING)

常见误区

  • descriptor 字段名与实际读写不一致:解码取不到值。
  • 集合/嵌套结构 descriptor 写错:格式层结构判断错误。

追问

  • 复合类型 descriptor 怎么构造?答:buildClassSerialDescriptor 声明元素,细节以 API 为准。
  • descriptor 名称冲突有影响吗?答:同名结构在模块注册时需注意区分。

04.8.4.1-031 序列化时如何处理第三方库类型?

一句话结论

第三方类型无法加源码注解时,写自定义 KSerializer 把它映射到可传输值(字符串/基础结构),通过属性注解或 SerializersModule 绑定;优先在 DTO 层用本地值类型表达,避免把第三方运行时对象暴露到序列化边界。

概念解释

  • 桥接:外部类型 ↔ 原生可编码类型。
  • 映射发生在边界层。
  • 自定义 serializer 负责双向转换。

原理流程

  1. 识别第三方类型的可传输字段。
  2. 实现 serializer 编码为基础结构。
  3. 解码反向构造第三方实例。
  4. 属性/模块绑定该 serializer。

代码或图示

// 例:把外部类型编码为其标识字符串,解码时重建/查表

常见误区

  • 直接把第三方可变对象塞进 DTO:无 serializer 且内部状态不稳定。
  • 解码时依赖外部单例重建:跨环境不可重现。

追问

  • 日期时间类型怎么处理?答:用字符串/时间戳表达,结合 kotlinx-datetime 自定义 serializer。
  • 集合内第三方类型怎么办?答:元素类型绑定自定义 serializer,集合由内置支持处理。

04.8.4.1-032 字段顺序在 JSON 序列化中有意义吗?

一句话结论

JSON 对象字段顺序语义上无关,但生成器按声明/descriptor 顺序输出;解码按键名匹配,不依赖顺序;调试与报文 diff 时顺序可能影响可读性,协议兼容不应依赖字段排列顺序。

概念解释

  • JSON 对象是键值集合,顺序不保证语义。
  • 输出顺序由代码结构决定。
  • 解码按键匹配,顺序无关。

原理流程

  1. 编码按 descriptor 属性顺序写键值。
  2. 解码器按键名查找。
  3. 输入顺序与输出顺序可不同。
  4. 兼容演进不依赖位置取值。

代码或图示

@Serializable
data class A(val b: Int, val a: String) // 输出顺序按声明

常见误区

  • 前端/下游按字段位置取值:应按键名解析。
  • 调整属性顺序以为会破坏协议:键名不变即可兼容。

追问

  • 数组元素顺序有意义吗?答:数组顺序有语义,集合元素顺序需保留;对象字段顺序无关。
  • 自定义 serializer 能控制输出顺序吗?答:按 descriptor 与 serialize 书写顺序决定。

04.8.4.1-033 反序列化构造对象时,协程/副作用能放在构造器里吗?

一句话结论

反序列化只应做纯数据构造,构造器与初始化逻辑不要发起网络、数据库或启动后台协程;解码在 converter/后台线程执行,副作用时机与线程不可控;需要初始化的派生状态在解码完成后由业务层显式执行。

概念解释

  • 解码是数据重建,不是业务初始化。
  • 构造器副作用难以测试与排错。
  • 线程上下文由转换器决定。

原理流程

  1. 解码器读字段调用构造。
  2. 构造器保持纯赋值。
  3. 返回 DTO 后业务层做初始化。
  4. 协程/IO 在受控作用域内启动。

代码或图示

@Serializable
data class Dto(val id: String) // 构造器无副作用

常见误区

  • 在 init 块里启动监听/连接:解码时机不可控。
  • 构造器读取线程局部上下文:解码线程与业务线程不同。

追问

  • 解码后需要校验怎么办?答:业务层调用校验方法,不放在隐式构造路径。
  • 嵌套 DTO 构造链也要保持纯:递归构造都不产生副作用。

04.8.4.1-034 前后端字段命名不一致,除了 @SerialName 还有什么方案?

一句话结论

逐字段用 @SerialName 显式映射;统一命名风格差异可用 Json namingStrategy 全局转换;映射规则复杂时在 DTO 层做字段转换;选择方案时考虑注解可读性、全局一致性与协议演进成本。

概念解释

  • 单字段覆盖:注解。
  • 全局风格:命名策略。
  • 复杂转换:DTO 映射层。

原理流程

  1. 评估差异范围:个别字段还是整体风格。
  2. 整体 snake_case 用策略统一。
  3. 个别特殊命名用注解覆盖。
  4. 非结构转换在映射层处理。

代码或图示

@SerialName("user_name") val userName: String

常见误区

  • 全局策略与字段注解混用冲突:注解优先,需核对最终键名。
  • 命名策略只配编码侧:解码端匹配键也要遵循同一策略。

追问

  • 命名策略支持哪些转换?答:以当前版本 Json 配置为准(待确认),不支持的用注解。
  • 缩写词(URL/ID)命名如何处理?答:注解固定键名最可控。

04.8.4.1-035 序列化异常通常分哪几类,业务层如何捕获?

一句话结论

常见异常包括:缺少 serializer、未知字段/类型标记、类型不匹配、非法枚举/数值、JSON 语法错误;业务层在解码边界捕获序列化异常,转换为错误状态或降级,区分报文错误与业务失败;不要让解码异常直接穿透到无兜底的根作用域。

概念解释

  • 编译期:缺 serializer 多为编译错误。
  • 运行时:报文结构/类型/语法问题。
  • 边界统一捕获与映射。

原理流程

  1. 解码调用进入转换器。
  2. 结构/类型/语法问题抛序列化异常。
  3. 边界 catch 记录原始报文与异常。
  4. 映射为业务错误状态上报。

代码或图示

val dto = runCatching { Json.decodeFromString<Dto>(body) }
    .getOrElse { /* 映射错误状态 */ }

常见误区

  • 解码异常直接崩溃页面/请求:缺少边界容错。
  • 只记录异常不保留原始报文:无法定位契约问题。

追问

  • 序列化异常是协程取消异常吗?答:不是,属于数据解析失败,不应按取消放行处理。
  • 错误 DTO 如何设计?答:单独错误报文模型,兼容非 2xx 响应体结构。

04.8.4.1-036 泛型类如何参与序列化?

一句话结论

泛型可序列化类的序列化器随泛型参数类型解析:字段引用泛型参数时,运行时从上下文获取对应参数 serializer;泛型实参必须可序列化,嵌套泛型集合按元素类型递归解析;缺参数 serializer 时编译或运行时报错。

概念解释

  • 泛型结构:容器类 + 元素类型。
  • 参数 serializer 由调用上下文提供。
  • 多态泛型需模块注册配合。

原理流程

  1. 泛型类标注 @Serializable。
  2. 生成器在泛型参数位置引用上下文 serializer。
  3. 解码时按实参类型查找参数序列化器。
  4. 元素/嵌套类型递归编解码。

代码或图示

@Serializable
data class ApiResponse<T>(val code: Int, val data: T)

常见误区

  • 泛型实参是不可序列化类型:编译期找不到 serializer。
  • 擦除后期望运行时自动推断任意类型:需显式提供 serializer 或 reified 辅助。

追问

  • 嵌套泛型 List<T> 支持吗?答:支持,集合内置 serializer 委托元素 T 的 serializer。
  • 泛型多态注册怎么做?答:SerializersModule 绑定泛型父类与子类映射。

04.8.4.1-037 List、Map、Set 等集合的序列化有哪些注意点?

一句话结论

标准集合由内置 serializer 处理,元素类型必须可序列化;Map 键通常要求基础类型或可序列化键;集合顺序:List 顺序保留,Set/Map 遍历顺序依实现;解码后得到的是普通集合实例,元素不可变性需自行保证。

概念解释

  • 元素可序列化是前提。
  • 集合结构由内置格式处理。
  • 可变元素跨边界共享需防护。

原理流程

  1. 集合 serializer 遍历元素。
  2. 每个元素委托自身 serializer 编码。
  3. 解码逐元素构造入集合。
  4. 集合类型与元素类型绑定解析。

代码或图示

@Serializable
data class Bundle(
    val tags: List<String>,
    val attrs: Map<String, String>
)

常见误区

  • 元素是第三方类型未配 serializer:集合解码失败。
  • 把可变元素集合直接外泄给其他协程:并发修改风险。

追问

  • 自定义集合类型能序列化吗?答:实现自定义 serializer 或映射为标准集合结构。
  • Map 键为枚举可以吗?答:支持情况以内置能力为准,复杂键建议转为字符串。

04.8.4.1-038 如何直接读取/操作 Json 原始树(JsonElement)?

一句话结论

kotlinx.serialization 提供 JsonElement 模型(JsonObject/JsonArray/JsonPrimitive),可把报文解析为原始树按键导航读取,再解码为目标类;适合动态结构、字段裁剪与兼容处理,比直接字符串操作安全,但相比直接解码多一层树构造开销。

概念解释

  • JsonElement:不可变 JSON 树节点。
  • JsonObject 按键访问,JsonArray 按索引。
  • 可在树层做字段判断后再映射 DTO。

原理流程

  1. Json.parseToJsonElement(string) 解析为树。
  2. 导航取子节点与原始值。
  3. 需要强类型时再 decodeFromJsonElement。
  4. 动态结构在树层容错处理。

代码或图示

val tree = Json.parseToJsonElement(body).jsonObject
val name = tree["name"]?.jsonPrimitive?.content

常见误区

  • 动态字段仍强解码整类:结构变化即失败,树层更灵活。
  • 树节点转可变对象后修改:JsonElement 设计为只读。

追问

  • 哪些扩展属性访问节点?答:jsonObject/jsonArray/jsonPrimitive 等扩展,以版本 API 为准(待确认)。
  • 树操作性能与直接解码对比?答:树构造有额外分配,强类型优先直接解码。

04.8.4.1-039 接口(开放类)多态与 sealed 多态在注册上有何差异?

一句话结论

sealed 层次子类封闭可枚举,编译器对层次有自动支持;开放接口/父类的实现类可以来自不同模块,必须在 SerializersModule 中显式注册所有允许反序列化的子类,否则解码遇到该子类标记失败;安全边界上开放层次要防止未知实现反序列化。

概念解释

  • sealed:有限子类集合。
  • open:实现可扩展,需白名单注册。
  • 注册 = 允许解码的子类白名单。

原理流程

  1. 定义父类型注解多态。
  2. sealed 子类按层次自动/辅助注册。
  3. open 父类在模块逐个 subclass 注册。
  4. 解码标记命中白名单才构造。

代码或图示

@Serializable
sealed class Shape
// open 层次:模块中注册 Circle、Square 等允许的子类

常见误区

  • open 父类不注册实现:外部报文带实现标记即失败。
  • 注册所有类导致反序列化面扩大:只注册可信子类。

追问

  • 多态标注加在父类还是子类?答:按库多态配置要求声明父类型多态,子类提供 serializer(细节以版本文档为准,待确认)。
  • 跨模块子类如何注册?答:公共模块聚合 SerializersModule 统一挂载。

04.8.4.1-040 协议版本演进新增/删除字段时如何保持兼容?

一句话结论

新增字段给默认值,旧客户端解码新报文时忽略未知键(ignoreUnknownKeys);删除字段前确认所有客户端不再依赖,旧报文缺失新字段时回退默认值;不要改变既有字段类型与含义,枚举新增值需旧端容错策略;兼容方向以双端版本矩阵验证。

概念解释

  • 向前兼容:旧端读新报文。
  • 向后兼容:新端读旧报文。
  • 默认值与忽略未知键是主要手段。

原理流程

  1. 新增可空/带默认值字段。
  2. 旧端忽略未知键不报错。
  3. 新端读旧报文缺失字段用默认值。
  4. 字段类型变更走新字段而非覆盖旧字段。

代码或图示

@Serializable
data class V2(val id: Long, val email: String? = null)

常见误区

  • 把必填字段改成可空却不评估旧数据:语义变化。
  • 直接改字段类型:旧报文解码类型不匹配。

追问

  • 字段重命名怎么做?答:@SerialName 保留旧键映射,或新旧字段过渡。
  • 枚举新增值旧端崩溃怎么办?答:coerce 容错或保留未知原始值,升级前评估。

04.8.4.1-041 序列化对象包含不可序列化的运行时依赖怎么办?

一句话结论

把运行时依赖(客户端、会话、线程池)与可传输数据分离:DTO 只保留可序列化值,依赖在业务层组装;确需临时携带的字段标 @Transient 并给默认值,不要把连接、回调、协程句柄写进报文模型。

概念解释

  • 可传输:值类型、集合、枚举、可标注类。
  • 不可传输:资源、引用、回调。
  • 分离数据与行为依赖。

原理流程

  1. 识别对象中的运行时资源字段。
  2. 移出 DTO 或标 transient。
  3. 解码后由仓库/服务层注入依赖。
  4. 序列化边界只出现值对象。

代码或图示

@Serializable
data class OrderDto(val orderId: String)
// 客户端依赖不进入 DTO

常见误区

  • 在 DTO 里持有 Repository 引用:无法序列化且生命周期耦合。
  • transient 字段无默认值:反序列化构造失败。

追问

  • 临时缓存状态要持久化吗?答:不需要则 transient;需要持久化则转为可传输字段。
  • 跨进程传递对象选什么?答:值对象经序列化传输,资源句柄不跨进程。

04.8.4.1-042 编码输出中 null 字段省略与显式写出如何取舍?

一句话结论

接口约定需要字段存在性区分「未设置」与「null」时显式写出 null;协议只关心值、想减小报文体积时配置省略 null;取舍取决于后端字段语义,不能仅凭体积决定;前后端必须对 null 与缺键的解释一致。

概念解释

  • 显式 null:字段存在,值为空。
  • 省略:字段不存在。
  • 语义差异影响合并与更新逻辑。

原理流程

  1. 与后端确认字段语义约定。
  2. explicitNulls 配置控制编码行为。
  3. 解码按可空性与默认值处理缺键。
  4. 报文样例纳入接口测试断言。

代码或图示

Json { explicitNulls = false } // null 属性省略

常见误区

  • 一端省略 null、另一端按缺键处理默认值:状态被错误覆盖。
  • 为减小体积省略必填可空字段:下游无法区分未传与清空。

追问

  • PATCH 局部更新适合哪种?答:未提供的字段不应出现在报文中,省略 null 更贴合部分更新语义。
  • 列表批量更新呢?答:按接口约定,明确 null 清空与缺键不更新的区别。

04.8.4.1-043 自定义 serializer 中如何处理可空属性?

一句话结论

自定义 serializer 需在 descriptor 与编解码中区分可空性:解码 null 时按可空类型返回 null,不可空类型收到 null 应抛异常;可空包装由格式层与 serializer 配合,自定义逻辑不要假设输入一定非空。

概念解释

  • 可空:允许 null 值经过编解码。
  • 不可空:null 是非法输入。
  • descriptor 表达字段是否可空。

原理流程

  1. descriptor 声明字段可空性。
  2. 编码:null 写出空值或按配置省略。
  3. 解码:读 null 判断目标可空性。
  4. 不可空遇 null 抛序列化异常。

代码或图示

// 自定义 decode 中先判断输入是否为 null,再决定构造值

常见误区

  • 自定义解码直接强转非空:null 输入触发 NPE 而非规范序列化异常。
  • descriptor 可空性写错:格式层 null 处理行为错乱。

追问

  • 内置类型可空谁处理?答:框架包装可空 serializer,自定义类需自行保证。
  • 可空默认值如何配合?答:缺键用默认值,显式 null 覆盖为 null。

04.8.4.1-044 kotlinx-datetime 是什么,解决 JVM 时间库的什么痛点?

一句话结论

kotlinx-datetime 是 Kotlin 跨平台日期时间库,提供 Instant、LocalDate、LocalDateTime、TimeZone 等不可变值类型与解析/算术能力,目标是在 JVM/JS/Native 共享同一套时间模型;JVM 上可与 java.time 互操作,不再依赖平台私有日期类型。

概念解释

  • 跨平台统一 API。
  • 值类型不可变、算术返回新实例。
  • 区分瞬时时刻、本地日期时间与时区。

原理流程

  1. 公共代码依赖 kotlinx-datetime 类型。
  2. 各平台实现同一套模型。
  3. JVM 边界可与 java.time 转换。
  4. 序列化时映射为字符串/时间戳。

代码或图示

val instant = Instant.parse("2026-11-19T08:00:00Z")

常见误区

  • 把它当 java.time 的完全替代品在 JVM 直接用:互操作仍需转换桥接。
  • 可变修改时间实例:库类型不可变,操作返回新值。

追问

  • 版本基线是多少?答:0.6.x,具体 API 以项目依赖版本为准(待确认)。
  • 与传统 Date/Calendar 相比?答:不可变、时区模型清晰、跨平台,替代旧可变日期 API。

04.8.4.1-045 Instant 表达的是什么时间概念?

一句话结论

Instant 是无时区的时间瞬时点,对应 UTC 时间线上的一刻,以秒/纳秒精度记录;不携带日历字段与展示时区,适合记录事件发生的绝对时刻、传输时间戳与时序比较。

概念解释

  • 瞬间:时间线坐标,与时区无关。
  • 精度:秒 + 纳秒(表示能力以版本实现为准)。
  • 比较:按时间线先后比较瞬时。

原理流程

  1. 从 UTC 字符串或 epoch 构造 Instant。
  2. 算术操作基于时间线偏移。
  3. 转换到本地类型时才附加时区。
  4. 序列化用 ISO 字符串或 epoch 数值。

代码或图示

val now = Clock.System.now()
val future = now.plus(1, DateTimeUnit.HOUR)

常见误区

  • 用 Instant 直接表达「当地日期」:缺少时区字段,展示需转 LocalDate。
  • 以为 Instant 带固定显示格式:它是值,格式化由格式化器处理。

追问

  • Instant 与 epoch 毫秒如何转换?答:toEpochMilliseconds/fromEpochMilliseconds,API 名称以版本为准(待确认)。
  • 不同时钟源如何获取?答:Clock.System 为系统时钟,测试可注入虚拟 Clock。

04.8.4.1-046 LocalDate、LocalTime、LocalDateTime 各自表达什么?

一句话结论

LocalDate 是日历日期(年月日),LocalTime 是日内时间(时分秒纳秒),LocalDateTime 是日期加时间的墙上时钟,三者都不含时区;它们描述「某地墙上看到的时间」,不能直接与绝对时刻互转,必须结合 TimeZone。

概念解释

  • LocalDate:无时间的日期。
  • LocalTime:无日期的日内时间。
  • LocalDateTime:本地墙上时钟,无时区归属。

原理流程

  1. 按日历字段构造本地类型。
  2. 算术在本地日历规则下进行。
  3. 附加时区后可转为 Instant。
  4. 跨时区比较先转 Instant。

代码或图示

val date = LocalDate(2026, 11, 19)
val time = LocalTime(8, 30)
val dateTime = LocalDateTime(date, time)

常见误区

  • 把 LocalDateTime 当瞬时存库:DST 切换时同一墙上时间可能对应两个 Instant。
  • 本地类型直接跨时区比较:结果无绝对意义。

追问

  • LocalDateTime 转 Instant 需要什么?答:dateTime.toInstant(zone) 提供 TimeZone。
  • 日期加减跨月/年规则?答:按日历算术处理,结果落在合法日期。

04.8.4.1-047 TimeZone 与 ZoneOffset 有何区别?

一句话结论

TimeZone 是时区规则对象(含 DST 历史与未来规则,如城市时区),ZoneOffset 是固定 UTC 偏移量;同一地区不同日期偏移可能因夏令时不同,固定偏移不反映规则变化;跨地区时间换算应优先用时区 ID 对应的 TimeZone。

概念解释

  • TimeZone:规则,按日期解析偏移。
  • ZoneOffset:固定差值。
  • 时区 ID 关联完整规则历史。

原理流程

  1. 通过时区 ID 获取 TimeZone。
  2. 某时刻查询该时区的偏移量。
  3. 固定 Offset 只表达单一差值。
  4. DST 切换日规则由 TimeZone 计算。

代码或图示

val zone = TimeZone.of("Asia/Shanghai")
val offset = ZoneOffset.ofHours(8)

常见误区

  • 用固定 +8 替代上海时区:忽略历史 DST 与规则变更。
  • 跨夏令时地区只存偏移:历史日期换算错误。

追问

  • 时区 ID 从哪里取?答:IANA 时区数据库标识,库按平台能力支持(细节待确认)。
  • 缺省时区怎么获取?答:Clock/系统默认时区 API,名称以版本为准。

04.8.4.1-048 为什么存储业务时间推荐用 Instant 而不是 LocalDateTime?

一句话结论

Instant 记录绝对时刻,跨时区、跨服务器一致且可正确排序;LocalDateTime 只是墙上时钟,脱离时区无法确定绝对瞬间,DST 与地区变化会导致歧义;持久化与传输优先 Instant(UTC),展示时再按用户时区转本地时间。

概念解释

  • 存储:绝对时刻无歧义。
  • 展示:本地墙上时间给用户看。
  • 服务器多时区部署尤其需要统一 UTC。

原理流程

  1. 事件发生时记录 Clock.System.now()(Instant)。
  2. 存储/传输 Instant 的 UTC 表示。
  3. 展示层按时区转 LocalDateTime。
  4. 排序与时序比较基于 Instant。

代码或图示

val eventTime: Instant = Clock.System.now()
val local = eventTime.toLocalDateTime(TimeZone.currentSystemDefault())

常见误区

  • 数据库存本地墙上时间且不带时区:迁地区/夏令时后时刻错乱。
  • 多台服务器各自本地时间排序:时钟与时区不一致。

追问

  • 业务日程(会议时间)存什么?答:同时存本地时间 + 时区 ID,重新计算 Instant 处理 DST 变更。
  • 日期仅「年月日」场景?答:LocalDate 足够,不涉及时刻。

04.8.4.1-049 Instant 与 LocalDateTime 之间如何换算?

一句话结论

Instant.toLocalDateTime(zone) 按指定时区把瞬时转为墙上时钟;LocalDateTime.toInstant(zone) 把本地时间按时区规则转回瞬时;换算必须显式提供时区,歧义时刻(DST 重叠/空缺)按库规则处理,具体行为以版本实现为准(待确认)。

概念解释

  • 瞬时 ↔ 本地:时区是桥梁。
  • 同一 Instant 在不同时区得到不同本地时间。
  • 本地时间在 DST 边界可能不唯一或不存在。

原理流程

  1. Instant + zone → 查询偏移 → 计算本地字段。
  2. LocalDateTime + zone → 按规则解析为 Instant。
  3. 边界日期应用 DST 规则。
  4. 结果类型分别承担展示与存储职责。

代码或图示

val instant: Instant = localDateTime.toInstant(zone)
val local: LocalDateTime = instant.toLocalDateTime(zone)

常见误区

  • 换算不传时区:编译/逻辑上无法确定绝对时刻。
  • DST 重叠时段直接假设唯一映射:可能存在偏移歧义。

追问

  • 歧义时间如何处理?答:查库对重叠/空缺本地时间的解析策略,必要时业务层明确规则。
  • 日期单独换算?答:Instant.toLocalDate(zone) 先定时区再取日历日。

04.8.4.1-050 时钟(Clock)抽象在测试中有什么作用?

一句话结论

Clock 抽象提供当前时刻来源,生产用 Clock.System,测试可注入固定/虚拟时钟控制时间,避免依赖真实系统时钟做定时、超时与时间相关断言;业务代码依赖 Clock 接口而非直接读系统时间,保证可测性。

概念解释

  • 时钟注入:时间来源可替换。
  • 固定时钟:测试用例确定 now。
  • 虚拟时钟:推进时间验证周期逻辑。

原理流程

  1. 依赖处接收 Clock 实例。
  2. 生产注入 System 时钟。
  3. 测试注入固定/可推进时钟。
  4. 断言时间计算不依赖真实等待。

代码或图示

class OrderService(private val clock: Clock = Clock.System) {
    fun now() = clock.now()
}

常见误区

  • 代码直接调用系统时间单例:测试无法控制时间。
  • 测试 Thread.sleep 等时间推进:慢且不稳定。

追问

  • 测试时钟实现有哪些?答:固定时刻/可推进实现,具体类型与 API 以 kotlinx-datetime 版本为准(待确认)。
  • 时钟能跨平台用吗?答:Clock 抽象是跨平台 API,测试实现按平台提供。

04.8.4.1-051 日期时间解析与格式化如何完成?

一句话结论

库提供 ISO 格式解析(如 Instant.parse、LocalDate.parse)与格式化器按模式输出字符串;自定义模式通过格式化器对象配置;解析失败抛日期时间异常,格式字符串与区域/时区设置需明确;具体格式化 API 名称以版本为准(待确认)。

概念解释

  • 解析:字符串 → 时间类型。
  • 格式化:时间类型 → 字符串。
  • ISO 标准格式与自定义模式分离。

原理流程

  1. 输入字符串按格式规则解析字段。
  2. 校验日历合法性后构造本地/瞬时类型。
  3. 输出时按模式取值拼字符串。
  4. 非法日期/格式抛异常。

代码或图示

val date = LocalDate.parse("2026-11-19")
val text = date.toString() // ISO 输出

常见误区

  • 手写字符串切分解析日期:月份/时区/闰年规则易错。
  • 格式化隐式依赖系统默认时区/区域:结果跨环境不一致。

追问

  • 自定义模式用什么类?答:查 kotlinx-datetime 格式化器 API(待确认具体类名)。
  • 解析容错宽松吗?答:默认严格,非法日期抛异常,不要静默修正。

04.8.4.1-052 日期时间算术(加减、区间)有哪些注意点?

一句话结论

时间类型不可变,加减返回新实例;瞬时算术按固定时长偏移,本地日历算术按日历单位(日/月/年)处理跨月与闰年;区间用于判断时刻是否落在范围内;混合时长与日历单位时注意 DST 对本地时间的影响。

概念解释

  • 固定时长:秒/分钟/小时偏移。
  • 日历单位:日/月/年,受日历规则影响。
  • 不可变:操作不修改原实例。

原理流程

  1. 选择单位:Duration 还是 DateTimeUnit。
  2. 算术返回新时间实例。
  3. 本地类型跨月按日历校正。
  4. 区间比较基于类型自身顺序。

代码或图示

val tomorrow = today.plus(1, DateTimeUnit.DAY)
val later = instant.plus(30, DateTimeUnit.MINUTE)

常见误区

  • 本地时间加一天忽略 DST:墙上时间可能偏移一小时。
  • 直接用字段手工加减月份:月末/闰年规则出错。

追问

  • 两个时刻差值怎么算?答:基于时间线求 Duration 或单位差,API 以版本为准。
  • 月末加一个月如何处理?答:库按日历规则校正到合法日期,需验证目标行为。

04.8.4.1-053 时区转换常见的坑有哪些?

一句话结论

常见坑:用固定偏移替代时区规则、把 LocalDateTime 当瞬时存储、忽略 DST 重叠与空缺、服务器默认时区与业务时区不一致、格式化未指定时区;正确做法是存 Instant,展示按用户时区转换,明确时区 ID 而非硬编码偏移。

概念解释

  • 规则 vs 偏移:DST 与历史变更。
  • 存储 vs 展示:瞬时与墙上时间分层。
  • 边界歧义:重叠/不存在的本地时间。

原理流程

  1. 存储统一 UTC Instant。
  2. 展示读取用户所在时区 ID。
  3. Instant 转本地时间渲染。
  4. 边界歧义按业务规则解析。

代码或图示

val local = instant.toLocalDateTime(TimeZone.of("Asia/Shanghai"))

常见误区

  • 后端按服务器默认时区转时间:部署地区变化结果不同。
  • 前端直接展示 LocalDateTime 字符串:缺时区上下文。

追问

  • DST 重叠时本地时间出现两次怎么办?答:业务定义首选偏移规则,库解析策略待确认。
  • 跨时区会议时间怎么存?答:存本地时间 + 时区 ID,参会者各自换算 Instant。

04.8.4.1-054 日期时间在序列化时推荐用什么格式?

一句话结论

Instant 推荐 ISO-8601 UTC 字符串(带时区标记)或 epoch 毫秒/秒数值;LocalDate 用 ISO 日期字符串;避免用平台私有日期类默认格式传输;为库类型写自定义 serializer,保证跨端解析一致,数值精度与时单位(秒/毫秒/纳秒)需与接口约定。

概念解释

  • 文本:可读、自带时区语义。
  • 数值:紧凑,但需约定单位与时区。
  • 自定义 serializer 绑定类型。

原理流程

  1. 选择传输格式:ISO 字符串或 epoch 数值。
  2. 自定义 serializer 编码/解码该格式。
  3. 跨端按同一约定解析。
  4. 精度损失在单位换算时确认。

代码或图示

// Instant 编码为 ISO 字符串示例;具体 serializer 实现按库类型 API

常见误区

  • 直接序列化库对象默认结构:跨端格式不稳定。
  • epoch 单位混用秒与毫秒:时间差千倍错误。

追问

  • kotlinx-datetime 类型有内置 serializer 吗?答:以库当前版本支持为准(待确认),未内置则手写。
  • 数值传输丢纳秒精度可接受吗?答:按业务精度要求选择毫秒/秒单位。

04.8.4.1-055 如何为 Instant/LocalDate 写 kotlinx.serialization 自定义 serializer?

一句话结论

实现 KSerializer<T>,descriptor 声明为字符串或原始数值类型,serialize 把时间类型转为约定格式字符串/epoch 值,deserialize 解析回时间类型;通过 @Serializable(with=...) 绑定到属性或类;解析失败抛序列化异常,保留原始输入便于排查。

概念解释

  • 双向转换:类型 ↔ 传输值。
  • descriptor 匹配传输格式。
  • 绑定方式类级或属性级。

原理流程

  1. 定义 serializer 对象,指定 descriptor 为 STRING/LONG。
  2. serialize 调 toInstant/parse 等方法编码。
  3. deserialize 读原始值并 parse 构造。
  4. 注解绑定到对应字段。

代码或图示

object InstantIsoSerializer : KSerializer<Instant> {
    // descriptor、serialize、deserialize 按库 API 实现
}

常见误区

  • 解析不校验非法日期:构造出不一致状态。
  • 编码格式与解码约定不一致:跨端解析失败。

追问

  • serializer 能复用给可空类型吗?答:框架包装可空,自定义实现非空逻辑。
  • 多个时间格式怎么兼容?答:解码器按约定尝试格式,失败抛明确异常。

04.8.4.1-056 JVM 上 kotlinx-datetime 与 java.time 如何互操作?

一句话结论

JVM 平台两类类型可通过对应工厂/转换方法桥接:Instant ↔ java.time.Instant,LocalDateTime/LocalDate 与 java.time 对应类型按字段转换;互操作只发生在 JVM 边界,公共代码仍依赖 kotlinx-datetime 模型,避免把 java.time 类型泄露到公共源码集。

概念解释

  • 平台边界转换:JVM 专属类型不进公共代码。
  • 字段一一映射:时刻、日期、时间、时区。
  • 转换保持精度与时区语义。

原理流程

  1. 进入 JVM 平台代码时识别 java.time 类型。
  2. 调转换方法映射到 kotlinx-datetime。
  3. 公共逻辑使用跨平台类型。
  4. 输出边界反向转回平台类型。

代码或图示

// JVM 边界示例;转换 API 名称以 kotlinx-datetime 版本为准(待确认)
// java.time.Instant.now() → kotlinx Instant

常见误区

  • 在公共 common 源码集引用 java.time:JS/Native 编译失败。
  • 转换时丢失时区信息:本地类型转换必须带时区字段。

追问

  • 转换有精度损失吗?答:纳秒/秒级映射按两边能力对齐,转换前确认精度范围。
  • 哪个方向优先?答:公共模型用 kotlinx-datetime,平台适配层做双向转换。

04.8.4.1-057 java.time.ZoneId 与 kotlinx-datetime TimeZone 如何对应?

一句话结论

JVM 边界可在 java.time.ZoneId 与 TimeZone 之间按时区 ID 转换;规则语义对应 IANA 时区,固定 Offset 对应 ZoneOffset;跨平台公共代码只使用 TimeZone,平台类型在 JVM 适配层映射,时区 ID 字符串可作为稳定交换标识。

概念解释

  • 时区 ID 是跨层稳定标识。
  • 规则对象在平台侧映射。
  • 偏移与规则区分处理。

原理流程

  1. 平台侧读取 ZoneId 取 ID 字符串。
  2. 公共层用 TimeZone.of(id)。
  3. 反向转换把 ID 交回平台 ZoneId。
  4. 固定偏移映射为 ZoneOffset。

代码或图示

val zone = TimeZone.of(zoneId.id) // ID 作为交换键

常见误区

  • 直接把 ZoneId 对象传进公共代码:平台类型泄漏。
  • 用显示名替代 ID 做交换:显示名随区域语言变化。

追问

  • 系统默认时区怎么拿?答:平台 API 读取后映射,公共层不直接调 JVM 默认时区。
  • 时区 ID 非法时?答:解析抛异常,业务层兜底固定 UTC 或报错。

04.8.4.1-058 旧 java.util.Date/Calendar 迁移到新模型要注意什么?

一句话结论

Date 是可变瞬时包装、Calendar 是可变日历操作,新模型用不可变 Instant/本地类型替代;迁移时先厘清数据是瞬时还是本地时间,旧代码的可变副作用改为返回新实例;跨旧系统边界做类型转换,不把旧可变对象传入新模型链路。

概念解释

  • 旧 API:可变、线程安全弱、时区默认依赖。
  • 新模型:不可值类型、时区显式。
  • 迁移分识别语义、替换类型、边界转换三步。

原理流程

  1. 识别旧对象语义:瞬时还是墙上时间。
  2. 映射为 Instant 或 LocalDateTime。
  3. 可变操作改为算术返回新实例。
  4. 兼容旧接口处做双向转换。

代码或图示

// Date(epochMs) → Instant.fromEpochMilliseconds(epochMs)

常见误区

  • 直接把 Date 当 LocalDateTime:丢失时区语义。
  • 共享可变 Calendar 实例跨线程:旧并发风险带入新代码。

追问

  • 旧库返回 Date 怎么办?答:边界立即转 Instant,不向内传递 Date。
  • 闰年/夏令时历史问题?答:交给新模型规则计算,不手写旧 Calendar 逻辑。

04.8.4.1-059 跨平台源码集里能否使用 java.time 类型?

一句话结论

不能在 common 公共源码集引用 java.time:JS/Native 平台无该 API;公共代码使用 kotlinx-datetime,java.time 只出现在 JVM 源集的适配层;依赖注入与接口定义保持平台中立,转换按目标平台分别实现。

概念解释

  • common 编译到所有平台。
  • 平台专属类型隔离在平台源集。
  • 接口暴露跨平台类型。

原理流程

  1. common 定义使用 Instant/LocalDate 的接口。
  2. JVM 源集实现 java.time ↔ kotlinx 转换。
  3. 其他平台提供各自实现。
  4. 依赖方向:common 不反向依赖平台。

代码或图示

// common: fun current(): Instant
// jvm: 内部用 java.time.Instant 转换返回

常见误区

  • common 工具函数返回 java.time.ZonedDateTime:非 JVM 编译失败。
  • 平台转换逻辑写进公共类:破坏跨平台。

追问

  • 单平台 JVM 项目能直接用 java.time 吗?答:可以,但本项目统一用 kotlinx-datetime 模型时仍建议边界隔离。
  • 平台源集如何组织?答:按 kotlin { sourceSets } 结构配置,转换代码放 jvm 目录。

04.8.4.1-060 时间类型做相等性比较与排序时注意什么?

一句话结论

Instant 按时间线时刻比较;本地类型按日历字段比较,不同时区的 LocalDateTime 不能直接排先后;不可变值类型相等性基于字段,集合中作为键时确认 equals/hashCode 语义;跨时区排序必须先统一转 Instant。

概念解释

  • 比较基准:瞬时 vs 墙上时钟。
  • 不可变值类型:字段相等即相等。
  • 跨类型比较无意义,需先换算。

原理流程

  1. 瞬时比较:Instant 先后顺序。
  2. 本地比较:同口径墙上时间字段。
  3. 跨时区:先转 Instant 再排序。
  4. 集合键值依赖稳定 equals/hashCode。

代码或图示

val ordered = events.sortedBy { it.instant }

常见误区

  • 直接排序 LocalDateTime 混合不同时区:顺序错误。
  • 可变旧日期对象作集合键:引用/状态变化导致查不到。

追问

  • 同一时刻两种表示相等吗?答:Instant 与本地类型不是同一概念,不能直接 equals;转同口径后比较。
  • 精度不同的瞬时比较?答:按时间线精度对齐后比较,纳秒/毫秒差异纳入判断。

04.8.4.1-061 序列化枚举与 sealed 多态如何配合时间类型字段?

一句话结论

sealed 子类各自持有可序列化字段,时间字段用绑定好的自定义 serializer;多态标记与子类字段分开编码,解码先按标记选子类,再用子类 serializer 解析时间字段;模块注册与时间 serializer 配置在同一 Json 实例上生效。

概念解释

  • 多态外层结构 + 子类内部字段。
  • 嵌套类型 serializer 逐层解析。
  • 配置(模块、格式)统一挂载。

原理流程

  1. 父类型多态写标记 + 子类数据。
  2. 解码按标记选子类 serializer。
  3. 子类字段中的时间类型走绑定 serializer。
  4. 配置缺失时嵌套类型解析失败。

代码或图示

@Serializable
sealed class Report {
    @Serializable
    data class Snapshot(@Serializable(with = InstantIsoSerializer::class) val at: Instant) : Report()
}

常见误区

  • 只注册多态子类,遗漏字段时间 serializer:嵌套解码失败。
  • 多态标记字段与时间键名冲突:命名需区分。

追问

  • 时间字段在多个模型重复出现怎么复用?答:公共 serializer 对象绑定到各属性。
  • 多态未知子类容错?答:按未知标记策略处理,见多态题。

04.8.4.1-062 Json 原始树与强类型 DTO 如何选择使用场景?

一句话结论

结构稳定、契约明确的接口直接解码为 DTO;结构动态、字段可选、前后端版本差异大或需要先做字段裁剪/兼容判断时先解析 JsonElement 树再映射;树层灵活但有额外分配,性能敏感路径优先强类型解码。

概念解释

  • 强类型:安全、直接、性能好。
  • 原始树:动态导航、容错兼容。
  • 混合:树层预检后转 DTO。

原理流程

  1. 评估报文结构稳定性。
  2. 稳定接口直接 decode DTO。
  3. 动态接口 parseToJsonElement 导航。
  4. 必要时树层筛选字段再解码子结构。

代码或图示

val dto = Json.decodeFromString<Dto>(body)
// 动态场景:先取树节点,再按需解码

常见误区

  • 动态结构强行强解码:版本差异频繁失败。
  • 所有报文都走树层:冗余分配与类型不安全。

追问

  • 树层能直接改对象再编码吗?答:JsonElement 只读语义,修改需构造新树或映射 DTO。
  • 大报文树解析内存?答:整树构造有峰值内存,流式按需解析能力查版本 API。

04.8.4.1-063 服务端日志记录时间应使用哪种时间类型?

一句话结论

日志时间用 UTC Instant 记录,保证多服务器、多时区部署下时序一致;展示给运维时再按时区转换;不要用服务器默认本地墙上时钟打日志,否则跨节点排序与排查会混乱;日志格式统一 ISO UTC 或约定 epoch 数值。

概念解释

  • 日志排序:绝对时刻。
  • 多节点:统一 UTC。
  • 展示转换在查询侧完成。

原理流程

  1. 事件发生取 Clock.System.now()。
  2. 编码为 UTC ISO/epoch 写入日志。
  3. 检索展示按时区换算。
  4. 链路日志按 Instant 排序关联。

代码或图示

log.info("${Clock.System.now()} processed")

常见误区

  • 依赖主机默认时区打日志:容器/地区变更后时间口径不一致。
  • 日志只存可读本地字符串:缺时区上下文无法精确排序。

追问

  • 时钟漂移如何处理?答:服务器 NTP 同步,日志保留采集时间与事件时间区分。
  • 跨服务 trace 时间对齐?答:各服务记录 UTC Instant,链路按时间戳辅助排序。

04.8.4.1-064 日期时间接口契约如何定义才能避免前后端歧义?

一句话结论

契约明确字段是瞬时(Instant,UTC ISO 或 epoch 单位)还是本地日期(LocalDate/墙上时间 + 时区);写明格式字符串、精度、时区标记约定;可空与缺键语义单独说明;示例报文覆盖正常、空值与边界日期(月末、闰年、DST)。

概念解释

  • 类型语义:瞬时 vs 本地。
  • 格式与精度:字符串模式/数值单位。
  • 空值规则:null 与缺键区别。

原理流程

  1. 字段归类为瞬时或本地时间。
  2. 约定编码格式与精度单位。
  3. 明确可空、默认值与省略规则。
  4. 边界样例纳入契约与测试。

代码或图示

"createdAt": "2026-11-19T08:00:00Z"  // Instant, ISO-8601 UTC
"date": "2026-11-19"                 // LocalDate

常见误区

  • 字段名叫 date 却传带时间的瞬时:语义混淆。
  • epoch 不写单位(秒/毫秒):换算千倍错误。

追问

  • 带时区偏移的字符串能直接用吗?答:可以解析为 Instant,注意偏移合法性校验。
  • 前端展示日期依赖什么?答:用户时区,后端只传瞬时或本地+时区。

04.8.4.1-065 序列化中如何处理对象内的集合默认值与空集合?

一句话结论

集合属性默认空集合时,解码缺键回退空集合;编码是否写出空集合受 encodeDefaults 等配置影响;空集合与 null 语义不同,接口约定需区分;集合元素保持可序列化,返回不可变快照避免外部修改内部状态。

概念解释

  • 默认空集合:缺键回退。
  • null:集合未提供。
  • 编码输出受默认值配置控制。

原理流程

  1. 解码:缺集合键用默认空集合,显式 null 赋 null。
  2. 编码:按配置写出空集合或省略。
  3. 元素类型递归序列化。
  4. 对外返回只读集合视图。

代码或图示

@Serializable
data class Page(val items: List<Item> = emptyList())

常见误区

  • 空集合与 null 混用判断空:业务语义不同。
  • 内部 mutableList 直接外泄:外部可绕过保护修改。

追问

  • 省略空集合影响 PATCH 吗?答:未提供集合与清空集合需在契约中区分。
  • 集合元素为可空怎么处理?答:元素类型标可空,解码规则同可空属性。

04.8.4.1-066 两个 kotlinx-datetime 版本能力差异可能体现在哪些方面?

一句话结论

不同版本在格式化器 API、时区数据来源、解析策略、平台支持与类型方法命名上可能演进;落地前以项目依赖版本的 KDoc 为准,不确定的方法名/行为标注「待确认」并写验证点,不凭记忆断言某 API 在所有版本可用。

概念解释

  • API 随版本演进。
  • 平台时区数据提供方式不同。
  • 解析边界策略可能调整。

原理流程

  1. 记录项目 kotlinx-datetime 版本。
  2. 对照官方文档/KDoc 核对类型与方法。
  3. 写小用例验证解析与换算行为。
  4. 文档标注待确认项。

代码或图示

待确认:格式化器类名、DST 歧义解析策略、平台默认时区 API

常见误区

  • 照搬旧教程的方法名:版本不同编译失败。
  • 假设跨平台行为完全一致:平台能力可能有差异。

追问

  • 去哪里查版本行为?答:kotlinx-datetime GitHub releases 与 API KDoc。
  • 升级版本回归什么?答:日期解析、时区换算、序列化格式与测试时钟行为。

04.8.4.1-067 序列化器在多模块项目中如何复用?

一句话结论

通用自定义 serializer 与 SerializersModule 放公共模块,各业务 Json 实例挂载同一模块;DTO 模型按模块归属,公共类型跨模块共享 serializer;避免每个模块重复实现相同转换,配置分散会导致编解码行为不一致。

概念解释

  • serializer 与模块可组合复用。
  • 公共配置统一入口。
  • 业务特殊 serializer 留在业务模块。

原理流程

  1. 公共模块定义时间/枚举等通用 serializer。
  2. 聚合公共 SerializersModule。
  3. 各 Json 实例挂载公共模块,按需追加业务注册。
  4. 模型属性绑定复用 serializer。

代码或图示

val sharedModule = SerializersModule { /* 通用注册 */ }

常见误区

  • 各模块手写同名转换:规则漂移。
  • 业务子类注册进公共模块:耦合公共层。

追问

  • 模块能合并吗?答:SerializersModule 可组合,公共 + 业务分层挂载。
  • 版本兼容规则放哪?答:公共 DTO 模块统一维护字段映射。

04.8.4.1-068 解码时类型不匹配(字符串数字、嵌套对象)会怎样?

一句话结论

解码器按目标类型读取 token:期望对象遇到数组、期望数值收到字符串、字段结构不符都会抛序列化异常;宽松配置只覆盖特定可强制场景,不修复结构错误;业务层在解码边界捕获并记录原始报文,区分报文契约错误与业务异常。

概念解释

  • token 类型匹配是解码前提。
  • 结构错误不可靠 coerce。
  • 异常含字段路径与类型信息。

原理流程

  1. 解码器按 descriptor 期望读取 token。
  2. token 类型不符抛类型不匹配异常。
  3. 特定枚举/数值可 coerce 回退。
  4. 边界捕获后映射错误状态。

代码或图示

// 期望 Int 收到 JSON 字符串数字:按配置可能失败或强制转换(待确认支持范围)

常见误区

  • 依赖 coerce 修复结构错误:对象/数组层级错误仍失败。
  • 异常不带原始报文:定位不到契约问题。

追问

  • 数字字符串能自动转数值吗?答:支持范围以 coerce 配置与版本为准(待确认)。
  • 嵌套结构变平/变深怎么处理?答:自定义 serializer 或 DTO 映射层适配。

04.8.4.1-069 生产环境 Json 实例配置建议包含哪些基线项?

一句话结论

基线按接口约定配置:ignoreUnknownKeys 兼容后端加字段、explicitNulls 对齐 null/缺键语义、coerceInputValues 评估脏数据容忍度、挂载公共 SerializersModule;生产关闭 prettyPrint 减小体积;容错项开启前评估掩盖错误的风险,配置集中在一处复用。

概念解释

  • 兼容输入:未知键容错。
  • 语义对齐:null 表达。
  • 输出体积:关闭缩进。

原理流程

  1. 统一构造应用 Json 实例。
  2. 按契约设置容错与命名配置。
  3. 挂载模块注册多态与自定义 serializer。
  4. 各接口复用同一实例,特殊协议另建实例。

代码或图示

val appJson = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
    prettyPrint = false
    serializersModule = sharedModule
}

常见误区

  • 各处随意开容错:脏数据被静默接受。
  • 调试配置泄漏到生产:输出缩进与宽松解析不一致。

追问

  • 不同接口需要不同策略怎么办?答:建专用 Json 实例,不修改公共实例配置。
  • 配置变更如何回归?答:契约样例测试覆盖默认值、null、缺键与未知字段。

04.8.4.1-070 序列化与时间模型在一次接口请求链路中如何配合?

一句话结论

请求 DTO 用可序列化值类型,时间字段绑定 Instant 等 serializer;解码得到 DTO 后映射领域模型,时间按瞬时/本地语义分类处理;响应反向编码,统一 UTC 传输;边界负责格式与类型转换,业务层只操作跨平台时间模型。

概念解释

  • 链路分层:报文 DTO → 领域模型 → 报文。
  • 时间语义在映射层厘清。
  • 格式问题隔离在序列化边界。

原理流程

  1. 接收报文按 Json 配置解码为 DTO。
  2. 时间字段解析为 Instant/LocalDate。
  3. 领域逻辑操作不可变时间模型。
  4. 响应映射回 DTO 并按约定格式编码。

代码或图示

val dto = Json.decodeFromString<OrderDto>(body)
val domain = dto.toDomain()
val response = domain.toDto()

常见误区

  • 领域模型直接绑序列化注解与平台日期类型:耦合协议与平台。
  • 时间在解码后才发现语义错误:应在映射层校验。

追问

  • 时间校验放哪一层?答:DTO 映射领域时校验合法性与语义,不依赖反序列化单独保证。
  • 链路异常如何分层?答:解码异常在边界捕获,领域错误在业务层处理,取消信号单独放行。

04.8.4.1-071 测试中如何固定或推进当前时间?

一句话结论

依赖注入 Clock,测试替换为固定时刻时钟或可推进时钟:固定时钟让 now() 返回确定值,可推进时钟按测试步长前进,验证超时、周期与日期边界逻辑,不依赖真实系统时钟与 sleep。

概念解释

  • 时钟是时间来源抽象。
  • 测试时钟控制虚拟时间。
  • 业务代码不直接读系统时间。

原理流程

  1. 构造固定/可推进 Clock 实例。
  2. 注入被测服务。
  3. 调用逻辑读取时钟 now()。
  4. 推进时钟后断言时间相关结果。

代码或图示

// 测试注入固定时钟;具体时钟实现类型以 kotlinx-datetime 版本为准(待确认)
val service = OrderService(fixedClock)

常见误区

  • 测试直接断言真实当前时间:结果随运行时刻变化。
  • 用 Thread.sleep 等待时间推进:慢且偶发失败。

追问

  • 协程虚拟时间与时钟如何配合?答:测试调度器推进协程定时器,时钟提供业务时间来源,两者可分别控制。
  • 生产时钟能替换吗?答:生产固定用 Clock.System,配置注入点保留。

04.8.4.1-072 夏令时(DST)切换日换算有哪些易错点?

一句话结论

DST 切换时本地墙上时间可能重复出现(重叠)或跳过不存在的时间(空缺),直接 LocalDateTime ↔ Instant 换算存在歧义;必须依赖时区规则解析,业务侧明确重叠时取哪条偏移,不能假设本地时间一一对应瞬时;跨地区日程要存本地时间 + 时区 ID。

概念解释

  • 重叠: clocks 回拨,同一本地时间两次。
  • 空缺: clocks 前拨,本地时间不存在。
  • 规则由 TimeZone 按日期计算。

原理流程

  1. 本地时间附加时区。
  2. 时区规则判断该时刻是否歧义/空缺。
  3. 按策略选择偏移构造 Instant。
  4. 瞬时转回本地时间规则唯一。

代码或图示

val instant = localDateTime.toInstant(zone) // 歧义由库规则处理(待确认策略)

常见误区

  • 固定偏移 +8 处理 DST 地区:重叠/空缺解析错误。
  • 把本地时间当瞬时存储:切换日后事件时刻偏移错误。

追问

  • 库如何处理重叠本地时间?答:具体选择策略以版本实现为准(待确认),业务可显式校验。
  • 定时任务在 DST 日受影响吗?答:本地周期任务需重新计算瞬时,避免跳变导致执行时刻偏移。

04.8.4.1-073 时间区间(interval)与时长(Duration/Period)如何区分使用?

一句话结论

Duration 表达固定物理时长(秒/纳秒),适合瞬时偏移;日历相关的日/月/年差用日历单位或区间类型;本地日期加减日历单位受月份与闰年规则影响;跨瞬时计算用 Duration,跨日历字段计算用日期算术。

概念解释

  • Duration:固定时长,时间线偏移。
  • 日历单位:日/月/年,墙上日历规则。
  • 区间:两个时刻/日期之间的范围。

原理流程

  1. 瞬时偏移用 Duration/固定单位。
  2. 本地日期加减用 DateTimeUnit 日历单位。
  3. 区间判断包含关系。
  4. 差值按口径选择时长或日历差。

代码或图示

val later = instant.plus(30, DateTimeUnit.SECOND)
val nextMonth = date.plus(1, DateTimeUnit.MONTH)

常见误区

  • 用固定小时数加「一天」:DST 日可能不是 24 小时。
  • 月份差值手工相减字段:月末/闰年处理出错。

追问

  • 两个 LocalDate 相差多少天怎么算?答:按日历日期差 API,具体方法名以版本为准(待确认)。
  • Duration 能加月份吗?答:不能,月份属日历单位,需本地日期算术。

04.8.4.1-074 格式化输出为什么要显式指定区域与时区?

一句话结论

日期格式化依赖区域(月份/星期名称语言)与时区(墙上时间来源);不显式指定会继承环境默认值,跨设备/服务器区域不同导致输出不一致;服务端生成给客户端展示的日期应传输瞬时或结构化字段,展示格式在客户端按用户区域处理。

概念解释

  • 区域:文案语言与顺序。
  • 时区:本地时间换算。
  • 环境默认值不可移植。

原理流程

  1. 确定输出给机器还是给人看。
  2. 机器用 ISO 结构格式。
  3. 人类展示指定区域与时区格式化。
  4. 服务端不依赖主机默认区域生成展示文案。

代码或图示

// 机器可读:ISO 字符串;人类展示在 UI 层按区域格式化

常见误区

  • 服务端把本地化月份名写进报文:跨语言客户端解析失败。
  • 格式化未指定时区:主机时区变化导致显示偏移。

追问

  • 库格式化器支持区域参数吗?答:以版本 API 为准(待确认),不支持时在平台层用对应格式化能力。
  • 报文日期格式约定?答:ISO-8601 机器格式,展示格式不进入传输契约。

04.8.4.1-075 闰年、月末与日期加法有哪些边界规则?

一句话结论

日期加月/年时库按日历规则校正到合法日期(如 1 月 31 日加一个月落到合法月末);闰年二月天数由日历规则计算;测试应覆盖月末、闰年 2 月 29 日、大小月切换;不要用手工字段加减替代库算术。

概念解释

  • 月末校正:目标月无该日时取月末。
  • 闰年:2 月 29 日存在性规则。
  • 库算术封装日历边界。

原理流程

  1. 选择日历单位执行加法。
  2. 目标日期非法时按规则校正。
  3. 闰年判定由日历实现处理。
  4. 边界用例纳入测试断言。

代码或图示

val leap = LocalDate(2024, 2, 29)
// 加一年落到合法日期(校正规则以库实现为准,待确认)

常见误区

  • 手工 day+1 跨月:月份进位与月末遗漏。
  • 存 2 月 29 日到非闰年:日期构造失败需校验。

追问

  • 加一年后 2 月 29 日如何处理?答:库校正策略以版本为准,业务可显式落到 2 月 28 或 3 月 1 日。
  • 日期减法同理吗?答:日历差按规则计算,不做简单字段相减。

04.8.4.1-076 时间类型是否可变,赋值时会复制对象吗?

一句话结论

kotlinx-datetime 类型为不可变值类型:算术与转换返回新实例,原实例不变;赋值传递引用但不可修改,不存在线程内副作用;需要变化状态时生成新对象替换引用,不要尝试修改时间实例内部字段。

概念解释

  • 不可变:无 setter 改内部状态。
  • 操作返回新值。
  • 跨协程共享读取天然安全。

原理流程

  1. 读取当前时间实例。
  2. 算术方法生成新实例。
  3. 旧实例保持不变。
  4. 状态字段用新实例覆盖。

代码或图示

val next = current.plus(1, DateTimeUnit.DAY) // current 不变

常见误区

  • 像旧 Calendar 一样原地 set 字段:API 不支持可变修改。
  • 多个状态引用同一时间实例后假设可独立改:不可变语义下不会互相影响。

追问

  • 不可变对象跨线程共享需要锁吗?答:只读共享不需要同步。
  • 集合中时间实例作键安全吗?答:equals/hashCode 稳定,可作为键。

04.8.4.1-077 解析非法日期(如 2 月 30 日)会发生什么?

一句话结论

构造或解析非法日历日期会抛日期时间异常,不会静默校正为邻近日期;业务层应在边界捕获非法日期,记录原始输入;容错策略(回退默认值/拒绝)按业务约定,不要让非法日期进入领域状态。

概念解释

  • 严格校验:年月日合法性。
  • 非法输入显式失败。
  • 解析异常与序列化异常分别归类。

原理流程

  1. 输入字符串按格式解析字段。
  2. 校验日历合法性。
  3. 非法抛异常,不构造实例。
  4. 边界捕获并映射错误状态。

代码或图示

runCatching { LocalDate.parse(input) }

常见误区

  • 期望库自动纠正到月末:默认严格模式不做隐式校正。
  • 非法日期静默落库:后续换算与排序异常。

追问

  • 宽松解析开关有吗?答:日期解析容错能力以版本为准(待确认),不依赖未验证行为。
  • 非法时间(25:xx)同理吗?答:本地时间字段越界同样抛异常。

04.8.4.1-078 epoch 数值与 Instant 转换时精度与单位如何确认?

一句话结论

epoch 数值必须约定单位(秒/毫秒/微秒/纳秒)与精度;Instant 内部精度高于毫秒时,低精度单位转换会截断或舍入;接口契约写明单位,转换 API 选择对应方法,跨端不要混用秒与毫秒,避免千倍时间错误。

概念解释

  • 单位约定:传输数值的标尺。
  • 精度:纳秒/毫秒/秒逐级损失。
  • 转换方法与单位一一对应。

原理流程

  1. 契约确定 epoch 单位。
  2. 用对应 from/to 方法转换 Instant。
  3. 低精度转换按规则截断/舍入。
  4. 跨端校验数值范围与单位。

代码或图示

// toEpochMilliseconds / fromEpochMilliseconds;其他精度方法以版本为准(待确认)

常见误区

  • 不写单位,前后端一个用秒一个用毫秒:时间相差 1000 倍。
  • 纳秒精度需求用毫秒传输:精度丢失不可恢复。

追问

  • 如何校验数值合理性?答:检查落在合理时间区间,结合报文格式测试。
  • 字符串与数值两种格式能混用吗?答:同一字段保持一种约定,兼容期双字段过渡。

04.8.4.1-079 跨服务传递时间,为什么推荐 ISO-8601 字符串而不是裸 epoch?

一句话结论

ISO-8601 字符串自带时区/偏移语义、可读可调试,字段含义明确;epoch 数值紧凑但依赖单位约定,易错配;对内高性能传输可选 epoch,对外/跨团队接口优先带时区标记的 ISO 字符串,精度与单位在契约中写明。

概念解释

  • 文本:自描述、可读、自带偏移。
  • 数值:紧凑但约定隐式。
  • 按场景选择格式。

原理流程

  1. 评估接口消费方与调试需求。
  2. 对外契约用 ISO UTC 字符串。
  3. 内部高性能链路可用约定 epoch。
  4. 序列化器统一实现双向转换。

代码或图示

"2026-11-19T08:00:00Z"  // ISO-8601 UTC
1763553600000           // epoch 毫秒,需注明单位

常见误区

  • epoch 数值丢时区上下文:接收方按本地时区解读出错。
  • ISO 字符串不带 Z/偏移:本地时间语义不明。

追问

  • 两种格式能互相迁移吗?答:过渡期字段并存,解码兼容旧格式后逐步切换。
  • 字符串排序可行吗?答:UTC ISO 固定格式可按字符串排序,非定宽格式不行。

04.8.4.1-080 kotlinx-datetime 在 JVM 上是否完全替代 java.time?

一句话结论

跨平台公共代码应使用 kotlinx-datetime;纯 JVM 项目中 java.time 能力更成熟、生态更广,可直接使用;两者在 JVM 边界互操作,不存在必须二选一;选型按是否需要跨平台、团队既有经验与库能力覆盖度决定。

概念解释

  • 跨平台需求驱动选 kotlinx。
  • JVM 本地生态:java.time 完整。
  • 边界转换隔离平台差异。

原理流程

  1. 判断项目是否多平台。
  2. 公共代码用跨平台时间模型。
  3. JVM 边界按需转换 java.time。
  4. 纯 JVM 可直接使用 java.time。

代码或图示

// common: Instant;jvm: 边界转换 java.time.Instant

常见误区

  • 跨平台项目强行引用 java.time:其他平台编译失败。
  • 纯 JVM 为统一而套一层跨平台库:增加无谓转换。

追问

  • 库能力缺口怎么办?答:JVM 平台层用 java.time 补齐,公共层保持中立模型。
  • 版本成熟度如何评估?答:查 kotlinx-datetime release 与平台支持矩阵(待确认细节)。

04.8.4.1-081 JVM 边界转换时哪些字段容易丢失?

一句话结论

转换易丢失:时区规则(只传偏移不传 ID)、纳秒精度、本地时间的时区归属、DST 歧义标记;双向转换应保留完整语义:瞬时对瞬时、本地时间带时区 ID,精度按两边能力对齐,不把本地时间无歧义地转成瞬时。

概念解释

  • 语义配对:Instant ↔ Instant,LocalDate ↔ LocalDate。
  • 时区:规则 ID 与偏移区分。
  • 精度:纳秒/毫秒对齐。

原理流程

  1. 识别源类型语义。
  2. 匹配目标平台同类类型。
  3. 保留时区 ID 与精度字段。
  4. 转换后校验字段完整性。

代码或图示

// JVM: ZonedDateTime → 保留 zoneId;Instant → java.time.Instant

常见误区

  • ZonedDateTime 只转成 epoch:丢时区,回到本地展示无法还原规则。
  • 纳秒转毫秒不声明:后续比较出现微小偏差。

追问

  • LocalDateTime 在 JVM 对应什么?答:java.time.LocalDateTime,无时区,转换只搬字段。
  • 转换异常如何处理?答:边界捕获非法值,不把半成品传入领域层。

04.8.4.1-082 java.time.Duration 与 Period 对应到 Kotlin 侧怎么表达?

一句话结论

固定时长对应 kotlinx Duration 或固定时间单位;日期周期(年/月/日)对应日历单位/本地日期差,不能与固定时长混用;JVM 边界按语义分别转换,月份周期在跨平台侧用日历算术表达,不塞进瞬时 Duration。

概念解释

  • Duration:物理时长。
  • Period:日历日期量。
  • 两者口径不可互换。

原理流程

  1. 判定差值是时长还是日历量。
  2. 时长映射固定单位。
  3. 日期量映射日历单位与本地算术。
  4. 转换边界保留原始口径。

代码或图示

// 30 秒 → Duration/SECOND;1 个月 → DateTimeUnit.MONTH 本地算术

常见误区

  • 把「一个月」当 30 天固定时长:月末与闰年误差累积。
  • 跨平台代码引用 java.time.Period:平台类型泄漏。

追问

  • 库是否提供 Period 等价类型?答:以 kotlinx-datetime 当前版本类型清单为准(待确认)。
  • 区间差值展示怎么算?答:按业务口径选择时长差或日历差,分别格式化。

04.8.4.1-083 服务端多实例时钟不一致时时间逻辑如何保证可靠?

一句话结论

关键时序以 NTP 同步后的系统时钟为准,业务时间用 Instant 记录并容忍时钟偏差;不能依赖各实例本地墙上时间做跨节点排序或去重;必要时引入单调时钟或服务端统一时间源,重试/超时逻辑区分事件时间与处理时间。

概念解释

  • 时钟漂移:实例间时刻偏差。
  • 单调时钟:避免回拨影响间隔计算。
  • 事件时间与处理时间分层。

原理流程

  1. 基础设施 NTP 同步主机时钟。
  2. 事件记录 UTC Instant。
  3. 间隔测量优先单调时钟能力(平台支持待确认)。
  4. 排序/去重结合业务标识,不单靠本地时间。

代码或图示

val eventTime = Clock.System.now()

常见误区

  • 用实例本地时间生成唯一顺序号:时钟回拨/漂移导致乱序。
  • 超时判断依赖墙上时间差值:时钟调整影响定时。

追问

  • 分布式时序怎么做?答:结合序列号/逻辑时钟,Instant 只作辅助排序。
  • 时钟回拨库如何处理?答:平台时钟实现行为以文档为准(待确认),业务侧加保护判断。

04.8.4.1-084 持久化时间字段时,库类型与数据库类型如何对应?

一句话结论

Instant 对应数据库 TIMESTAMP(UTC)/epoch 列,LocalDate 对应 DATE 列,LocalDateTime 对应不带时区的 TIMESTAMP;JVM 仓库层做类型转换,SQL 映射不直接暴露平台时间类型到公共模型;列定义明确时区语义,避免混用带时区与不带时区列。

概念解释

  • 瞬时:带时区/UTC 时间戳列。
  • 本地日期:DATE。
  • 墙上时间:无时区时间戳列。

原理流程

  1. 领域时间类型归类语义。
  2. 仓库层映射数据库列类型。
  3. 读写边界做双向转换。
  4. 列定义注明时区口径。

代码或图示

// Instant ↔ TIMESTAMP UTC;LocalDate ↔ DATE

常见误区

  • 用无时区列存 Instant:查询转换依赖会话时区,结果漂移。
  • 数据库返回旧 Date 直接进领域模型:在仓库边界转换为新模型。

追问

  • 数据库驱动返回什么类型?答:按驱动映射取 java.time/旧 Date,仓库层统一转换。
  • 精度不匹配怎么办?答:列精度覆盖业务需要,毫秒/纳秒在转换层对齐。

04.8.4.1-085 前后端时间展示链路中,后端应输出什么?

一句话结论

后端输出瞬时 ISO-UTC(或本地时间 + 时区 ID),不输出按服务器时区格式化的本地化文案;前端按用户时区与区域把 Instant 转本地时间格式化;日期选择等纯日历输入保留 LocalDate 语义,不附带时刻时区歧义。

概念解释

  • 后端负责传输语义,不负责展示区域。
  • 前端持有用户时区偏好。
  • 纯日期与时刻分字段表达。

原理流程

  1. 后端把领域 Instant 编码为 UTC ISO。
  2. 前端读取用户时区。
  3. Instant 转 LocalDateTime 格式化展示。
  4. 纯日期字段直接渲染日历值。

代码或图示

{ "createdAt": "2026-11-19T08:00:00Z", "timezone": "Asia/Shanghai" }

常见误区

  • 后端返回 "11/19/2026" 本地化格式:前端无法还原语义。
  • 把纯日期转成带零点的瞬时:用户时区下可能跨日。

追问

  • 用户时区从哪里获取?答:客户端配置/设备时区,随请求可选上报。
  • 后端能默认按某时区输出吗?答:可作为约定,但字段必须注明偏移/时区 ID。

04.8.4.1-086 序列化 DTO 中的时间字段失败,常见根因有哪些?

一句话结论

常见根因:时间类型未绑定 serializer、字符串格式与解析器不匹配、epoch 单位错误、时区字段缺失、不可序列化平台类型直接出现在 DTO;排查顺序是检查注解绑定、格式样例、单位约定与类型可序列化性,保留原始报文定位。

概念解释

  • 绑定缺失:框架找不到编解码逻辑。
  • 格式不匹配:解析失败。
  • 语义缺失:时区/单位不明。

原理流程

  1. 确认字段类型有 serializer 绑定。
  2. 对照报文样例检查格式字符串。
  3. 核对 epoch 单位与精度。
  4. 检查 DTO 是否混入平台/运行时类型。

代码或图示

@Serializable(with = InstantIsoSerializer::class)
val at: Instant

常见误区

  • 时间字段用默认生成器编码内部结构:跨端格式不稳定。
  • 解码失败只看异常消息:不保留原始报文无法复现。

追问

  • 多态内嵌时间字段失败?答:先确认子类注册,再查嵌套字段 serializer。
  • 修复后如何回归?答:契约样例覆盖正常、null、边界日期与非法格式。

04.8.4.1-087 如何避免在公共模型里混入平台日期类型?

一句话结论

公共接口与 DTO 只声明 kotlinx-datetime 类型;平台日期类型只出现在 JVM 源集的仓库/适配器层;代码评审检查 common 源集 import,转换函数放在平台适配类;依赖注入接口返回跨平台类型,不暴露平台实现。

概念解释

  • 依赖方向:平台适配依赖公共模型。
  • 平台类型隔离在 jvm 源集。
  • 评审防线:import 检查。

原理流程

  1. common 定义使用 Instant/LocalDate 的接口。
  2. jvm 适配器读取平台类型并转换。
  3. 返回值保持跨平台类型。
  4. CI/评审拦截 common 中的平台 import。

代码或图示

// common: interface Clock { fun now(): Instant }
// jvm: 实现内可用 java.time,转换后返回 Instant

常见误区

  • 工具函数在 common 返回 java.time.LocalDate:非 JVM 编译失败。
  • 平台类型作为泛型参数泄漏到公共接口:约束无法跨平台满足。

追问

  • 第三方库返回平台日期怎么办?答:在调用边界立即转换为跨平台类型,不向内传递。
  • 单平台项目也建议隔离吗?答:未来若跨平台可降低迁移成本。

04.8.4.1-088 时间相等性在跨时区比较时容易犯什么错?

一句话结论

错误做法是比较本地时间字符串或 LocalDateTime 字段判断同一时刻;正确做法是先统一转 Instant 再比较;同一墙上时间在不同时区是不同瞬时,纯日历日期(LocalDate)才按日期字段比较,不与 Instant 混比。

概念解释

  • 瞬时比较:时间线坐标。
  • 日期比较:日历字段。
  • 类型口径不同不能直接 equals。

原理流程

  1. 判定比较对象是瞬时还是日期。
  2. 瞬时统一转 Instant 比较时刻。
  3. 日期比较 LocalDate 字段。
  4. 混合口径先换算到同一类型。

代码或图示

val sameMoment = aInstant == bInstant
val sameDay = aDate == bDate

常见误区

  • 比较格式化后的时间字符串:格式/时区不同即误判不等。
  • 把不同时区的 LocalDateTime 当同一时刻。

追问

  • 两个瞬时精度不同怎么比?答:对齐精度后比较,标记纳秒/毫秒差异。
  • 集合按时间排序用什么键?答:事件 Instant 作为排序键。

04.8.4.1-089 接口新增一个可空时间字段,兼容策略是什么?

一句话结论

新字段给默认值或可空,旧客户端解码新报文时忽略未知键;新客户端读旧报文缺字段回退默认值/null;序列化器绑定保持一致,字段语义(瞬时还是本地日期)在契约注明;不要把新必填字段直接加入旧报文模型。

概念解释

  • 向前兼容:旧端读新报文。
  • 向后兼容:新端读旧报文。
  • 默认值与忽略未知键兜底。

原理流程

  1. 字段声明可空/带默认值。
  2. Json 开启 ignoreUnknownKeys。
  3. 旧报文缺字段回退默认。
  4. 契约文档标注格式与语义。

代码或图示

@Serializable
data class Profile(val id: Long, val lastSeen: Instant? = null)

常见误区

  • 新字段无默认值且不可空:旧报文解码失败。
  • 字段命名混用 date/time 语义:前后端理解分歧。

追问

  • 字段从必填改可空如何迁移?答:双端版本兼容期允许 null,消费方处理空值分支。
  • 时间格式变更怎么过渡?答:新旧字段并存,解码兼容后再下线旧字段。

04.8.4.1-090 自定义序列化器解析失败时应抛什么异常?

一句话结论

解码失败抛序列化框架约定的异常类型(描述字段路径与原因),不要抛裸 NPE 或自定义未包装异常;编码阶段的非法状态在业务层提前校验;异常消息包含输入片段与目标类型,便于边界定位;自定义 serializer 不吞掉解析错误返回臆造默认值。

概念解释

  • 异常类型与框架解码器一致。
  • 字段路径便于定位。
  • 失败显式优于静默错误默认。

原理流程

  1. 读取输入校验格式/字段。
  2. 非法构造失败抛序列化异常。
  3. 异常带字段名、期望类型与输入。
  4. 边界捕获后映射错误状态。

代码或图示

// deserialize 中校验不通过时抛框架序列化异常;具体异常类名以版本为准(待确认)

常见误区

  • 解析失败返回 null 默认对象:脏数据进入领域状态。
  • 异常不带上下文:报文出错无法定位字段。

追问

  • 编码阶段会失败吗?答:不可表示的值应在编码前校验,避免编码器抛意外异常。
  • 与业务异常区分?答:序列化异常是边界数据错误,业务失败在领域层另分类。

04.8.4.1-091 设计一个包含时间字段的用户资料 DTO,序列化与时区如何约定?

一句话结论

Profile DTO 用可序列化 data class,注册时间用 Instant 的 ISO-UTC serializer,生日用 LocalDate ISO 日期;昵称等基础类型默认生成器;Json 实例忽略未知键、明确 null 语义;后端只传瞬时与日期,展示时区由前端处理,字段语义写进契约样例。

概念解释

  • 字段分类:瞬时、纯日期、基础值。
  • 序列化绑定按字段类型。
  • 传输不含本地化展示格式。

原理流程

  1. 定义 ProfileDto 各字段类型。
  2. 绑定时间自定义 serializer。
  3. 配置 Json 容错与模块。
  4. 契约样例覆盖注册时刻、生日、空值。

代码或图示

@Serializable
data class ProfileDto(
    val id: Long,
    @Serializable(with = InstantIsoSerializer::class)
    val registeredAt: Instant,
    val birthday: LocalDate? = null
)

常见误区

  • 生日存成 Instant:用户生日应按日历日期,跨时区可能错日。
  • 注册时刻带服务器本地偏移未标时区:接收方误读。

追问

  • 生日缺省怎么表达?答:null 而非 epoch 零点,避免被误判为 1970-01-01。
  • 资料更新部分字段怎么传?答:PATCH 用可选字段,缺键不更新,null 表清空需单独约定。

04.8.4.1-092 批量导出报文里的时间字段如何保证格式统一?

一句话结论

批量模型复用同一 Json 实例与时间 serializer,所有 Instant 走同一 ISO/epoch 约定,LocalDate 走日期格式;导出前校验字段非空与合法性,避免部分记录格式不一致;格式化不在每行记录内单独配置,统一在导出层编码。

概念解释

  • 单一配置入口保证格式一致。
  • 复用 serializer 避免逐行手写。
  • 校验拦截非法时间值。

原理流程

  1. 导出层复用公共 Json 实例。
  2. 每条记录经同一模型编码。
  3. 时间字段统一 serializer 转换。
  4. 校验非法日期/空值后再输出。

代码或图示

val records = items.map { it.toDto() }
val output = Json.encodeToString(records)

常见误区

  • 部分记录手写日期字符串:格式漂移。
  • 批量导出不关 prettyPrint:体积与换行膨胀。

追问

  • 导出文件大如何处理?答:分页/流式输出,避免整表一次性构造内存。
  • 历史数据非法时间怎么清洗?答:导出边界标记异常记录,不静默改值。

04.8.4.1-093 缓存对象被序列化复用,时间快照应如何处理?

一句话结论

缓存中保存的时间应是不可变快照 Instant/LocalDate,序列化时按快照值编码;不要在缓存对象上携带可变时钟或运行时依赖;缓存更新生成新快照替换旧值,反序列化得到的是历史时刻,不应被当作「当前时间」。

概念解释

  • 快照:历史时刻值。
  • 不可变:缓存复用安全。
  • 当前时间运行时重新取时钟。

原理流程

  1. 写入缓存时记录当时 Instant。
  2. 缓存对象只含可序列化值。
  3. 序列化输出历史快照。
  4. 需要当前状态时重新取时钟计算。

代码或图示

data class CachedProfile(val snapshotAt: Instant, val data: ProfileDto)

常见误区

  • 缓存里存 Clock 引用:不可序列化且随时间漂移。
  • 反序列化旧缓存后把快照时间当实时状态:展示过期数据。

追问

  • 缓存过期判断用什么?答:快照 Instant 与当前时钟比较,不依赖本地系统字段。
  • 缓存跨进程传输?答:只传值对象,运行时句柄不进缓存结构。

04.8.4.1-094 第三方接口返回非标准日期格式,kotlinx 层如何适配?

一句话结论

在自定义 serializer 的 deserialize 中兼容解析历史/非标准格式,必要时尝试多个格式并校验合法性;编码统一输出标准格式;适配逻辑集中在 serializer 或 DTO 映射层,业务模型只持有标准时间类型,脏格式记录解析失败原因。

概念解释

  • 输入兼容:多格式尝试。
  • 输出标准化。
  • 适配隔离在边界。

原理流程

  1. 识别第三方日期字符串格式变体。
  2. serializer 按优先级尝试解析。
  3. 非法输入抛异常或映射错误状态。
  4. 编码统一为契约标准格式。

代码或图示

// deserialize: 依次尝试 ISO、旧格式,校验后构造 Instant/LocalDate

常见误区

  • 把非标准格式带进领域模型:后续计算口径混乱。
  • 静默猜测格式:歧义日期解析错误难排查。

追问

  • 格式无法判断怎么办?答:保留原始字符串,标记解析失败,上报第三方契约问题。
  • 新旧格式过渡期多久?答:双格式解析,编码只出新标准,观察无旧输入后下线兼容。

04.8.4.1-095 单元测试如何覆盖序列化与时间解析边界?

一句话结论

测试覆盖:正常往返编码解码、缺字段回退默认值、未知键忽略、null/缺键区分、非法格式与非法日期、多态子类标记、时间 ISO/epoch 双向转换与时区换算;用固定时钟构造确定时间,断言报文字段与解码对象一致,非法输入断言抛约定异常。

概念解释

  • 往返一致性:编码再解码等价。
  • 容错配置行为逐项断言。
  • 时间边界:月末、闰年、DST、精度。

原理流程

  1. 构造固定时间与 DTO 样例。
  2. encode 后断言报文键值。
  3. decode 报文断言对象字段。
  4. 非法/缺字段样例断言异常或默认值。

代码或图示

val dto = ProfileDto(1, fixedInstant, null)
val json = Json.encodeToString(dto)
assertEquals(dto, Json.decodeFromString(json))

常见误区

  • 只测正常路径:缺字段、未知键、非法格式在生产暴露。
  • 时间依赖当前时钟:断言随时刻变化。

追问

  • 多态子类测试?答:每个注册子类编解码往返,未知标记断言失败路径。
  • 时间时区边界用例?答:固定时钟构造 DST 边界日期,验证换算结果。

04.8.4.1-096 序列化库与项目构建工具链需要对齐哪些版本?

一句话结论

kotlinx-serialization 编译器插件版本与 Kotlin 编译器版本配套,运行时库版本与插件兼容;kotlinx-datetime 版本按 Kotlin 版本与目标平台选择;不凭记忆写坐标,以项目现有 build 脚本与官方兼容矩阵为准,不确定处标注「待确认」并在升级时跑编解码回归。

概念解释

  • 插件与编译器配套。
  • 运行时库与插件兼容。
  • 平台能力随库版本。

原理流程

  1. 确认 Kotlin 版本。
  2. 选配套 serialization 插件与库版本。
  3. 选 kotlinx-datetime 兼容版本。
  4. 升级后跑序列化/时间解析测试。

代码或图示

待确认:项目实际 plugin/artifact 版本坐标,以 build 脚本为准

常见误区

  • 插件版本与 Kotlin 不配套:编译报错或生成器异常。
  • 运行时库落后于插件:新特性解码/编码失败。

追问

  • 兼容矩阵在哪里查?答:官方文档 GitHub releases 与插件说明。
  • 多平台版本分别声明?答:公共依赖统一,平台特有按源集补充。

04.8.4.1-097 为什么不推荐手写反射式 JSON 解析替代编译期序列化器?

一句话结论

手写反射解析重复处理字段映射、可空性、默认值、多态与集合递归,易漏边界且性能与可维护性差;kotlinx 编译期生成器在编译期校验类型,运行时路径固定;除非有极端定制需求,否则应复用生成器与自定义 serializer 扩展点,不另造反射框架。

概念解释

  • 生成器覆盖类型规则。
  • 反射手写容易遗漏 null/默认值/多态。
  • 扩展点:自定义 serializer 处理特殊格式。

原理流程

  1. 常规 DTO 用生成器。
  2. 特殊类型走自定义 serializer。
  3. 反射手写只在遗留兼容层短期存在。
  4. 边界格式问题通过扩展点解决。

代码或图示

@Serializable
data class Dto(/* 生成器处理 */)

常见误区

  • 每个接口手写字段提取:契约变更时多处漏改。
  • 反射忽略可空性与默认值规则:解码崩溃或脏数据。

追问

  • 生成器能覆盖特殊嵌套结构吗?答:不能处用自定义 serializer 补足,不整体反射替代。
  • 性能手写一定更快吗?答:未必,生成器路径通常更直接,需实测对比。

04.8.4.1-098 序列化模型变更后如何保证旧版本客户端兼容?

一句话结论

字段只增不改不删语义,新增字段带默认值/可空;类型变更走新字段过渡;枚举新增值提供旧端容错;多态新增子类注册并验证旧端未知标记处理;契约变更保留双向兼容样例测试,灰度观察旧版本解码失败率后再下线旧字段。

概念解释

  • 兼容方向:旧端读新报文、新端读旧报文。
  • 破坏性变更必须新字段/新版本号。
  • 灰度与监控兜底。

原理流程

  1. 评估变更对旧端解码的影响。
  2. 新增字段带默认值。
  3. 保留旧字段直到旧端下线。
  4. 契约测试覆盖双方向样例。

代码或图示

@Serializable
data class V3(val id: Long, val legacyName: String? = null, val displayName: String? = null)

常见误区

  • 直接改字段类型/含义:旧报文解码失败或语义错配。
  • 删字段前不观察旧端版本:仍有客户端发送旧结构。

追问

  • 不兼容变更如何发布?答:新版本接口/字段,并行过渡期,不原地破坏旧契约。
  • 多态旧端遇到新子类?答:旧端按未知标记容错或忽略,不崩溃。

04.8.4.1-099 当前批次与版本相关的待确认点有哪些?

一句话结论

待确认项包括:serialization 插件与库在项目中的实际坐标版本、namingStrategy/coerceInputValues/isLenient 支持范围、多态 sealed 自动注册程度、kotlinx-datetime 格式化器类名、DST 歧义解析策略、时钟测试实现类型、epoch 精度转换方法;均需对照项目依赖版本 KDoc 与实测用例确认,不编造版本行为。

概念解释

  • 版本差异落在 API 与默认行为。
  • 平台能力(时区/时钟)实现不同。
  • 不确定项标注验证方法。

原理流程

  1. 记录依赖版本号。
  2. 查官方 KDoc/changelog 核对 API。
  3. 写最小用例验证默认行为。
  4. 文档保留「待确认」与验证点。

代码或图示

待确认:插件坐标、配置项枚举、多态注册规则、格式化 API、DST 策略、时钟实现、精度方法

常见误区

  • 凭教程记忆断言默认值:版本升级后行为可能改变。
  • 把平台特有能力写成跨平台保证。

追问

  • 验证不通过时怎么办?答:按实测行为修正文档,不保留错误结论。
  • 升级库版本先回归什么?答:编解码往返、容错配置、时间解析与时区换算用例。

04.8.4.1-100 设计一套「DTO 序列化 + 时间模型 + 互操作边界」的工程规范,要点有哪些?

一句话结论

DTO 层只用可序列化值类型并标注 serializer;时间统一用 kotlinx-datetime 跨平台模型,Instant 存瞬时、LocalDate 存纯日期,边界与 java.time/旧 Date 转换;Json 实例集中配置并复用,多态与自定义 serializer 进公共模块;默认值/可空/未知键规则对齐契约,测试覆盖往返、容错与时间边界。

概念解释

  • 分层:DTO ↔ Domain ↔ 平台适配。
  • 时间语义:瞬时、本地日期、墙上时间分清。
  • 配置集中、测试兜底。

原理流程

  1. 定义公共 Json 实例与 SerializersModule。
  2. DTO 标注可序列化,时间字段绑定 serializer。
  3. 仓库/平台层做时间类型与平台转换。
  4. 契约测试覆盖编解码、缺字段、null、非法格式与时区换算。

代码或图示

// DTO: 可序列化值对象;Domain: 行为与不可变模型;Platform: java.time 适配
@Serializable
data class ApiItem(val id: String, val at: Instant)

常见误区

  • Domain 类直接加序列化注解:协议与行为耦合。
  • 时间语义在字段命名上不区分:瞬时/日期/墙上时间混用。
  • Json 配置散落在各接口:容错与格式不一致。
  • 公共代码引用平台日期类型:跨平台编译失败。

追问

  • 新增 DTO 类型走什么流程?答:标注可序列化、绑定必要 serializer、加入模块注册、补往返测试。
  • 时间字段接入新接口先确认什么?答:语义(瞬时/日期)、传输格式、精度单位与时区约定。

参考来源

待整理清单

  • [ ] 核对项目实际 kotlinx-serialization 插件与运行时库坐标、版本号。
  • [ ] 核对 Json 配置项 namingStrategy、coerceInputValues、isLenient 的支持范围与默认值。
  • [ ] 核对 sealed 多态自动注册规则与开放层次注册 API 细节。
  • [ ] 核对 kotlinx-datetime 格式化器类名、DST 歧义解析策略与测试时钟实现类型。
  • [ ] 核对 epoch 精度转换方法(秒/毫秒/纳秒)在当前版本的 API 名称。