ZonedDateTime — 详解时区与时间操作

什么是 ZonedDateTime？

ZonedDateTime —— java.time 包中的关键类之一，用于表示带有完整时区信息的日期和时间。它结合了三个组件：LocalDateTime（日期和时间）、ZoneId（时区标识符）和 ZoneOffset（相对于 UTC 的偏移量）。

与仅存储不带时区的挂钟时间（wall-clock time）的 LocalDateTime 不同，ZonedDateTime 能唯一定位一个时刻。两个相同的 LocalDateTime 在不同时区代表不同的时间点。两个相同的 ZonedDateTime —— 代表同一个时间点。

该类是完全不可变（immutable）且线程安全的。所有算术运算都返回新对象。ZonedDateTime 实现了 ChronoZonedDateTime 接口，可在任何需要 Java 中时区时间处理的地方使用。

根据 Oracle Java 17 规范，ZonedDateTime 支持与来自 IANA Time Zone Database 的任何时区进行交互，该数据库包含超过 600 个时区。

ZonedDateTime vs LocalDateTime：有什么区别？

主要区别 —— ZonedDateTime 包含时区，而 LocalDateTime 不包含。这一根本区别决定了两者的应用范围。

LocalDateTime 用于本地事件：音乐会时间、课程安排、出生日期。如果事件在莫斯科的 15:00 发生，LocalDateTime 将记录 15:00 而不带关联。如果将服务器移到纽约，时间仍为 15:00 —— 但这将是不同的物理时间。

ZonedDateTime 用于全局数据：服务器日志、API 时间戳、国际会议。如果会议安排在 15:00 MSK，ZonedDateTime 将同时保存时间和时区。在纽约它将正确显示为 8:00 EST。根据 Baeldung (2024)，选择 LocalDateTime 还是 ZonedDateTime 是处理日期时最常见的架构决策。

实用规则：如果数据存储用于单一区域 —— 使用 LocalDateTime。如果数据跨越时区边界 —— 使用 ZonedDateTime。如果需要传递绝对时间点 —— 使用 Instant。

java.time 中的时区如何运作？

java.time 中的时区由 ZoneId 类表示。ZoneId 是格式为 “continent/region” 的时区标识符，例如 “Europe/Moscow”、“America/New_York”、“Asia/Tokyo”。ZoneId 通过静态方法 of(String zoneId) 或通过系统默认时区获取。

ZoneId 分为两种类型：fixed offset（固定偏移，例如 “+03:00”）和 region-based（区域时区，例如 “Europe/London”）。区域时区包含夏令时转换规则和历史变更。Fixed offset 只是一个固定的偏移量。

要获取特定时刻的 ZoneId 当前偏移量，请使用 getRules() 方法，该方法返回 ZoneRules。ZoneRules 包含该时区的所有转换和偏移量。这是正确处理 DST 的关键机制。

所有时区通过 tzdata（IANA Time Zone Database）文件随 JDK 提供，并定期更新。在 Android 上，tzdata 版本取决于通过 Google Play Services 的系统更新。

创建 ZonedDateTime

可以通过多种方式创建 ZonedDateTime。最简单的方式是 now()，它返回系统默认时区中的当前时间。now(ZoneId) 变体允许获取指定时区中的当前时间。

of(LocalDateTime, ZoneId) 方法从本地时间和时区创建 ZonedDateTime。of(int year, int month, int dayOfMonth, int hour, int minute, int second, int nanoOfSecond, ZoneId zone) 变体 —— 从各组件创建。

LocalDateTime 可以通过 atZone(ZoneId) 方法转换为 ZonedDateTime。Instant —— 通过 Instant.atZone(ZoneId)。Date —— 通过 Date.toInstant().atZone(ZoneId)。

val moscowZone = ZoneId.of("Europe/Moscow")

val nowInMoscow = ZonedDateTime.now(moscowZone)

val fromComponents = ZonedDateTime.of(
    2026, 7, 21, 15, 30, 0, 0, moscowZone
)

val fromLocal = LocalDateTime.now().atZone(moscowZone)

val fromInstant = Instant.now().atZone(moscowZone)

时区之间的转换

主要的转换方法是 withZoneSameInstant(ZoneId)。它将 ZonedDateTime 转换为另一个时区，同时保留相同的时间点。例如，15:00 MSK → 8:00 EST。withZoneSameLocal(ZoneId) 方法更改时区但保留本地时间 —— 这会产生不同的时间点。

要获取相对于 UTC 的偏移量，请使用 getOffset() 方法，该方法返回 ZoneOffset。ZoneOffset 是 ZoneId 的子类，以 “+HH:mm” 或 “-HH:mm” 格式表示固定偏移量。

通过 toInstant() 方法转换为 Instant。Instant 是绝对时间点，不依赖于时区。反向转换 —— Instant.atZone(ZoneId)。

val moscow = ZonedDateTime.of(
    2026, 7, 21, 15, 0, 0, 0,
    ZoneId.of("Europe/Moscow")
)

val newYork = moscow.withZoneSameInstant(
    ZoneId.of("America/New_York")
)

val utcInstant = moscow.toInstant()
val backToMoscow = utcInstant.atZone(ZoneId.of("Europe/Moscow"))

处理夏令时（DST）

夏令时转换会导致两个问题：“间隙”（gap）和 “重叠”（overlap）。间隙出现在春季，当时钟拨快 —— 某个时间不存在。重叠出现在秋季，当时钟回调 —— 同一时间出现两次。

ZonedDateTime 通过 resolve 策略处理这些情况。在间隙期间创建对象时，java.time 会自动将时间向前偏移。在重叠期间创建时，选择第一个选项（调整前）。可以通过 withZoneSameInstant 更改此行为。

可以通过 zone.getRules().isDaylightSavings(instant) 检查时间是否处于 DST 时区。getOffset() 方法显示该时刻的当前偏移量，而 getRules().getDaylightSavings(instant) 显示 DST 调整量（以毫秒为单位）。

fun checkDST(zdt: ZonedDateTime) {
    val rules = zdt.getZone().getRules()
    val instant = zdt.toInstant()

    if (rules.isDaylightSavings(instant)) {
        val dstAmount = rules.getDaylightSavings(instant)
        Log.d("夏令时", "夏令时偏移：$dstAmount")
    }
}

格式化 ZonedDateTime

使用 DateTimeFormatter 格式化 ZonedDateTime。标准 ISO 格式包括日期、时间和偏移量：“2026-07-21T15:30:00+03:00[Europe/Moscow]”。预定义格式：ISO_ZONED_DATE_TIME、ISO_OFFSET_DATE_TIME、ISO_INSTANT。

对于本地化格式，请使用 DateTimeFormatter.ofLocalizedDateTime(FormatStyle)。FormatStyle 可以是 SHORT、MEDIUM、LONG、FULL。LONG 包括时区名称（“MSK”），FULL —— 完整名称（“Moscow Standard Time”）。

重要提示：在解析包含 ZonedDateTime 的字符串时，格式必须包含时区或偏移量信息。如果未指定时区，请使用 LocalDateTime.parse() 然后使用 atZone()。

val zdt = ZonedDateTime.now(ZoneId.of("Europe/Moscow"))

val iso = zdt.format(DateTimeFormatter.ISO_ZONED_DATE_TIME)

val custom = DateTimeFormatter
    .ofPattern("dd.MM.yyyy HH:mm z")
val formatted = zdt.format(custom)

val parsed = ZonedDateTime.parse(
    "2026-07-21T15:30:00+03:00",
    DateTimeFormatter.ISO_OFFSET_DATE_TIME
)

Android 中的 ZonedDateTime：实用示例

第一个示例 —— 为用户显示其所在时区的会议时间。服务器以 UTC 形式提供 ZonedDateTime，客户端将其转换为设备的本地时区。

fun displayMeetingTime(
    serverUtc: ZonedDateTime
): String {
    val deviceZone = ZoneId.systemDefault()
    val localTime = serverUtc.withZoneSameInstant(deviceZone)
    val formatter = DateTimeFormatter
        .ofPattern("dd.MM.yyyy HH:mm z")
    return localTime.format(formatter)
}

第二个示例 —— 考虑时区的情况下计算距离下一个事件的时间。使用 ZonedDateTime 表示服务器时间，使用 Duration.between() 计算差值。

fun timeUntilEvent(eventTime: ZonedDateTime): String {
    val now = ZonedDateTime.now()
    val duration = Duration.between(now, eventTime)

    val hours = duration.toHours()
    val minutes = duration.toMinutes() % 60
    return "Remaining $hours h $minutes min"
}

第三个示例 —— 与 Retrofit API 配合使用。服务器返回 ISO-8601 格式的带时区字符串。使用自定义反序列化器转换为 ZonedDateTime。

data class EventResponse(
    @JsonAdapter(ZonedDateTimeAdapter::class)
    val eventTime: ZonedDateTime
)

class ZonedDateTimeAdapter : JsonAdapter<ZonedDateTime>() {
    override fun fromJson(reader: JsonReader): ZonedDateTime? {
        return ZonedDateTime.parse(
            reader.nextString()
        )
    }
}

时区操作的常见错误

第一个错误 —— 在服务器代码中使用 ZoneId.systemDefault()。服务器的时区可能与客户端不同，在服务器上使用系统时区会导致错误计算。始终明确指定时区或使用 UTC 作为标准。

第二个错误 —— 在计算时长时忽略 DST。Duration.between() 正确处理转换，但如果手动减去时间戳，夏令时转换可能导致 1 小时的误差。使用 ChronoUnit.HOURS.between() 方法代替手动计算。

第三个错误 —— 混淆 withZoneSameInstant 和 withZoneSameLocal。前者更改时区但保留时间点 —— 时间偏移。后者更改时区但保留本地时间 —— 时间点改变。根据 SonarSource (2024) 的数据，选择错误的方法是最常见的错误之一。

第四个错误 —— 假设设备的时区始终与用户的时区相同。用户可能旅行并期望应用程序显示其“家庭”时区的时间，而不是当前时区。在这种情况下，需要通过界面提供时区选择。