Java 3次重写日期API，第3次还是栽了

Java的日期处理是个老大难问题。从1995年诞生至今，这门语言在日期API上摔了三次跟头，每次都说"这次不一样"。

第三次重写的java.time.LocalDate，2014年随Java 8发布，被官方推荐为"现代Java日期时间的标准解决方案"。11年过去了，一个基础到不能再基础的操作——获取月份名称——依然能让开发者踩坑。

前两次尝试：从废弃到半废弃

Java最早的日期类java.util.Date，1995年设计时就没想过后续的闰秒、时区变更这些麻烦事。Date类把日期和时间揉成一个毫秒数，简单得像块砖头。

闰年规则已经够折腾了：能被4整除但不能被100整除，或者能被400整除。更麻烦的是闰秒——国际地球自转服务组织（IERS）会根据地球自转情况，随机在某年6月或12月最后一天加一秒或减一秒。Date类根本表达不了这种"临时补丁"。

1997年，Sun公司推出java.util.Calendar，试图挽救局面。Calendar确实更灵活，支持时区、历法系统，甚至能算农历。但它带着浓重的90年代设计痕迹：月份从0开始计数（0=一月，11=十二月），没有类型安全的枚举（enum），一堆魔法常量让人头晕。

开发者社区对Calendar的评价很分裂。有人觉得它"能用"，更多人抱怨"每次用都要查文档"。Stack Overflow上关于"为什么Calendar.MONTH从0开始"的问题，积累了数千个回答和评论。

Oracle接手Java后，Calendar进入维护模式。官方文档明确标注Date和Calendar为"遗留类"，建议迁移到新API。但迁移成本太高，大量旧代码至今仍在运行。

第三次：java.time的设计野心

2014年Java 8发布，带来全新的java.time包。这个API由JSR 310规范定义，主笔是Stephen Colebourne——他之前维护的Joda-Time库，被公认为Java日期处理的"事实标准"。

官方给java.time的定位很清晰：不可变对象、线程安全、清晰分离日期/时间/时区概念。LocalDate专门处理"日期"（年月日），LocalTime处理"时间"（时分秒），ZonedDateTime再把时区叠加上去。

设计上确实解决了前代的硬伤。月份终于用上了枚举类型java.time.Month，JANUARY到DECEMBER一目了然，不再是魔法数字0-11。时区信息单独拆成ZoneId，更新时区数据库不用动核心代码。

但设计者做了一个看似合理、实则埋雷的决定：Month枚举的getValue()方法，返回1-12的数值，而不是0-11。

他们的理由很充分：符合ISO 8601标准，符合人类直觉（1月=1），避免Joda-Time时代"月份+1"的转换麻烦。这个设计选择，在特定场景下制造了新的混乱。

那个让开发者懵掉的细节

问题出在数组索引的场景。Java开发者获取月份名称，最直白的写法是用字符串数组：

final var MESES = new String[]{ "Enero", "Febrero", "Marzo", "Abril", "Mayo", "Junio", "Julio", "Agosto", "Septiembre", "Octubre", "Noviembre", "Diciembre" };

假设当前日期是2026年4月7日，LocalDate正确输出了ISO格式"2026-04-07"。调用fecha.getMonth()返回Month.APRIL，一切正常。

但接下来两行代码，输出结果截然不同：

System.out.println( "Mes (val): " + MESES[ fecha.getMonth().getValue() ] ); // 输出"Mayo"

System.out.println( "Mes (ord): " + MESES[ fecha.getMonth().ordinal() ] ); // 输出"Abril"

getValue()返回4，ordinal()返回3。数组索引从0开始，MESES[4]对应的是第五个元素"Mayo"，而MESES[3]才是正确的"Abril"。

Month.APRIL在枚举中的声明顺序是第4个（从0数），所以ordinal()=3。但getValue()被硬编码返回4，为了"符合人类直觉"。同一个枚举常量，两个方法给出不同数值，这种设计在Java标准库中极为罕见。

开发者必须记住：用数组或List时，要么用ordinal()，要么用getValue()-1。前者依赖枚举声明顺序（理论上不安全），后者每次都要手动减一。

更隐蔽的坑在于：很多开发者根本没意识到这两个方法的区别。代码能编译，测试用例碰巧过了，直到某个边界条件触发才暴露问题。4月变成5月只是显眼，如果发生在数据处理管道里，可能就是静默的数据错位。

为什么改不掉？

这个设计2014年定稿，写入Java 8的正式规范。11年来，Oracle没有动过Month枚举的定义。不是没人提意见，而是兼容性约束太强。

java.time被定位为"现代Java的基石API"，Spring Boot、Hibernate、Jackson等主流框架全部深度集成。修改Month.getValue()的返回值，意味着破坏数百万行生产代码。Java的兼容性承诺是金字招牌，宁可让新开发者踩坑，也不能让旧系统崩溃。

社区有过折中提案：新增一个getIndex()方法返回0-11，或者给Month添加内置的显示名称支持。但这些方案要么增加API复杂度，要么与现有i18n（国际化）机制冲突。java.time.format.DateTimeFormatter其实已经提供了月份名称的本地化输出，只是很多开发者习惯了"数组索引"这种简单粗暴的方式。

时区数据库的更新倒是确实频繁。IANA时区数据库每年发布多次，处理各国夏令时规则的变更。Java通过tzdata-updater工具链同步这些更新，这是java.time相比前代真正的工程优势。但核心API的设计债务，只能原样继承下去。

作者Baltasar García在原文末尾调侃：还会有第四次尝试的。这不是悲观，是对软件工程现实的清醒认知。日期时间处理涉及天文学、政治学、历史学（历法变更），任何API都只能逼近"足够好用"，而非"完美"。

Java 21已经发布，java.time依然是官方推荐的唯一选择。那些从Date和Calendar迁移过来的开发者，以为终于摆脱了"月份-1"的噩梦，直到某天深夜调试时，发现数组索引又越界了。

你的代码里，用的是getValue()还是ordinal()？或者你已经彻底抛弃了数组索引，改用DateTimeFormatter.getText()？