Kotlin 时代的时间管理：从 java.time 迁移至 kotlinx-datetime

Ehtan_Zheng
0 阅读4分钟

在现代 Android 开发中，保持代码库的整洁、前瞻性以及对 Kotlin Multiplatform (KMP) 的兼容至关重要。将日期和时间处理从 Java 传统的 java.time 迁移到 Kotlin 原生的时间 API 已经是大势所趋。

本文将基于真实的迁移经验，为你拆解这一过程中的核心逻辑、技术细节以及那些“前人踩过的坑”。

一、 什么是 Kotlin Time？

为了方便起见，我们将 Kotlin 团队开发的一系列日期和时间相关 API 统称为 Kotlin Time。它主要由两部分组成：

  1. 标准库 kotlin.time：主要用于测量时间间隔和计算时长。核心类是 Duration。

    • 注：在 Kotlin 2.1.20 中，Instant 和 Clock 作为实验性 API 加入了标准库，未来将取代 kotlinx-datetime 中的对应类型。

  2. 扩展库 kotlinx-datetime：涵盖了其余的日期时间处理 API，包括 LocalDate、LocalDateTime、DateTimePeriod 以及各种辅助工具。

二、 为什么迁移？

相比 Java Time，Kotlin Time 拥有四个核心优势：

  1. Kotlin 优先的语法： 不再需要 Duration.ofDays(1)，直接使用扩展属性 1.days；计算差值时，直接使用 end - start 而非繁琐的 Duration.between(start, end)。
  2. 物理时间（Instant）与民用时间（Local）的清晰界限： Java Time 中的 OffsetDateTime 和 ZonedDateTime 试图将“绝对时间戳”与“本地时区偏移”强行捆绑在一起。

Kotlin Time 摒弃了这种复杂的组合，强制开发者理清“这一刻是什么”与“当地人看钟表是多少”的区别，从而减少逻辑 Bug。

  1. KMP 跨平台支持： 底层自动封装了 JVM 的 Java Time、JS 的 js-joda 以及 Native 的回溯实现，一套代码走天下。
  2. 摆脱 JDK 版本限制： 不再需要为了在老版本 Android 上使用时间 API 而进行复杂的 Backport 或库迁移。

image.png

三、 迁移实战：分步进阶指南

1. 基础类的“平替”

首先，处理那些逻辑最接近的类：

  • Instant、Duration、LocalDate、LocalTime、LocalDateTime。
  • Period -> 替换为 DatePeriod 或 DateTimePeriod。

提醒： 绝对不要尝试一次性全局替换所有 import java.time。这会导致编译报错堆积如山，处理起来极其痛苦。

2. 增量重构：利用“桥梁”函数

推荐采用逐文件重构的方式。库中提供了非常方便的转换扩展：

  • Java -> Kotlin: 使用 toKotlin*()（例如 toKotlinLocalDate()）。
  • Kotlin -> Java: 使用 toJava*()。

3. 关键语法的细微变化

在迁移过程中，你会发现一些“故意为之”的不兼容：

  • Instant.now() 被废弃：必须使用 Clock.System.now()。
  • LocalDateTime.now() 消失了：这是为了强迫你先获取一个 Instant，再根据时区将其转换为 LocalDateTime。这能有效防止时区处理不当导致的错误。

4. 日期周期的加减

在 Java Time 中，你可以直接 LocalDateTime + Period。但在 Kotlin 中：

  • 如果不关心时间组件：使用 LocalDate.plus(DatePeriod(...))。
  • 如果关心时间组件：必须使用 instant.plus(DateTimePeriod(years = 1), TimeZone.UTC)。注意，这个重载函数有时比较难找，因为它隐藏在 Instant 的扩展中。

四、处理“消失”的 OffsetDateTime

Kotlin Time 并没有 OffsetDateTime 的直接对应物。

如何处理？ 其实 OffsetDateTime 在底层就是一个 LocalDateTime 加上一个 ZoneOffset。在大多数业务场景（尤其是 API 交互）中，你会发现 OffsetDateTime 往往被滥用了。

建议方案：将其拆解。在 API 层使用 Instant，在业务逻辑层结合 TimeZone 使用。这种显式的拆解虽然初看繁琐，但极大增强了代码的鲁棒性。

image.png

五、 如何定义迁移“已完成”？

由于 Java Time 是 SDK 的一部分而非外部库，你无法通过“删除依赖”来确认迁移进度。

实战技巧：利用静态分析（Detekt） 你可以设置一条 ForbiddenImport 规则，将 java.time.* 加入禁入名单。

YAML

# detekt-config.yml
ForbiddenImport:
  active: true
  imports:
    - reason: '新代码请使用 Kotlin Time'
      value: 'java.time.*'

通过这种方式，现有的旧代码会报错，你可以将它们放入 Baselines（基准线文件） 中。随着基准线文件的行数减少，你的“技术债”指标也就一目了然。

六、 总结与局限

迁移到 Kotlin Time 后，代码会变得更加现代和安全。但请注意：目前的 kotlinx-datetime 还不支持本地化日期格式化。对于这种需求，目前仍需通过抽象层保留一部分平台相关的（JVM）代码。

avatar
文章
阅读
粉丝