Java Time Chronology 非 ISO 日历的格式化

我第一次把日本年号放进报表时，真正容易出错的不是模式字符串，而是把“展示日历”和“业务日期”混在了一起。稳妥做法是：数据库、接口和计算仍使用 ISO 的 LocalDate，到用户界面再用 DateTimeFormatter.withChronology() 覆盖为指定日历。这样同一个 2025-05-01 可以显示为日本历令和 7 年 5 月 1 日，却不会改变原始日期。

官方资料：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/chrono/package-summary.html

先把 ISO 存储和非 ISO 展示分成两条边界

java.time.chrono 面向 ISO 之外的日历系统，官方也提醒它更适合用户界面的本地化输入输出。我的项目里会让订单表保存 LocalDate，报表层再转换为 JapaneseChronology、ThaiBuddhistChronology 等。不要把 JapaneseDate 序列化成接口的默认日期字符串，也不要用显示文本参与排序。

用 withChronology 把同一天格式化成目标日历

下面的示例以日本历为例。先用 ISO 日期表达业务事实，再把格式化器绑定到日本历；G 输出纪元，y 输出纪元内年份。

import java.time.LocalDate;
import java.time.chrono.JapaneseChronology;
import java.time.format.DateTimeFormatter;
import java.util.Locale;

public class ChronologyFormatDemo {
    public static void main(String[] args) {
        // ISO 日期保留业务事实，适合存储、排序和接口交换。
        LocalDate isoDate = LocalDate.of(2025, 5, 1);

        // G 是纪元，y 是纪元内年份；Locale 只负责本地化文字。
        DateTimeFormatter formatter = DateTimeFormatter
                .ofPattern("G y年M月d日", Locale.JAPAN)
                .withChronology(JapaneseChronology.INSTANCE);

        // withChronology 会按日本历解释同一个 epoch day，不改变 isoDate。
        String display = formatter.format(isoDate);
        System.out.println(display); // 令和 7年5月1日（文字以 JDK 资源为准）
    }
}

关键点是接收 withChronology 的返回值。DateTimeFormatter 是不可变对象，直接调用而不赋值不会修改原格式化器。若只想输出数字年，可以去掉 G；但跨纪元展示时省略它会让“7 年”失去语义。

格式化字段和 Locale 要分别检查

排查格式不对时，我会按“日历体系、字段、语言环境”三项拆开。withChronology(JapaneseChronology.INSTANCE) 决定换算规则；Locale.JAPAN 影响纪元名称和月份文字；G、y、M、d 决定输出哪些字段。把 Locale 改成英文，并不会把日本历变回 ISO。

解析时不要丢掉 Chronology

如果页面提交的是带年号的字符串，解析器也要绑定同一个 Chronology。否则读到的 7 可能被误当作 ISO 公历 7 年，日期会直接落到错误的时间线上。

import java.time.chrono.ChronoLocalDate;
import java.time.chrono.JapaneseChronology;
import java.time.format.DateTimeFormatter;
import java.util.Locale;

// 解析带纪元文本时，格式化和解析共享同一套日历语义。
DateTimeFormatter japanese = DateTimeFormatter
        .ofPattern("G y年M月d日", Locale.JAPAN)
        .withChronology(JapaneseChronology.INSTANCE);

// 文本必须包含与 Locale 匹配的纪元文字；失败时应记录输入并返回业务错误。
ChronoLocalDate parsed = JapaneseChronology.INSTANCE
        .date(japanese.parse("令和 7年5月1日"));

日本历只支持明治 6 年 1 月 1 日之后的范围，其他 Chronology 也有各自的有效区间。生产代码应捕获 DateTimeParseException 或 DateTimeException，把用户输入错误和系统内部的 ISO 日期分开处理。

上线前用这张边界清单复查

• 存储、排序、接口字段是否仍是 ISO 日期，而不是年号文本？
• 格式化器是否同时明确了 Chronology 与 Locale？
• 跨纪元展示是否包含 G，解析是否沿用了同一套格式化器？
• 是否覆盖了日期范围、无效纪元、不同 Locale 和解析失败分支？

这个方案适合把非 ISO 日历限制在输入输出层。计算、持久化和跨服务传输仍以 ISO 为主，只有确实面对本地日历的界面才引入 Chronology，维护成本会低很多。

相关问题

withChronology 会修改 LocalDate 吗？

不会。它按同一个时间线日期生成目标 Chronology 的展示视图，原来的 LocalDate 仍是 ISO 值。

Locale.JAPAN 能单独切换日本历吗？

不能。Locale 负责本地化资源，日历转换要显式设置 JapaneseChronology 或从 Locale 取得合适的 Chronology。

为什么只写 y 不写 G 有风险？

y 只有纪元内年份，跨纪元时单独看到“1”或“7”无法判断属于哪个 Era。