Java Date Calendar使用指南与常见问题

Java中传统的Date和Calendar类充斥着反直觉的设计陷阱：年份参数以1900为基准导致`new Date(2024, 0, 1)`竟指向2924年，月份从0开始、`DAY_OF_WEEK`值与日常认知及ISO标准错位、`set()`的惰性更新引发字段冲突、时区处理隐晦易出错……这些隐患让时间操作成为线上故障高发区；文章不仅一针见血指出问题根源，更给出清晰可行的现代化替代方案——优先采用线程安全、语义明确的`LocalDateTime`/`ZonedDateTime`，用`toInstant()`安全跨时区转换，并强调将解析、计算、展示严格分离，助你彻底避开Java时间API的“坑中坑”。

用 Date 构造时间时，年份参数是「1900年起始偏移量」

这是最常踩的坑：传 new Date(2024, 0, 1) 得到的不是 2024 年 1 月 1 日，而是 2025 年 1 月 1 日（因为年份按「距 1900 年的差值」算，2024 − 1900 = 1024，所以实际是 1024 + 1900 = 2924 年）。更糟的是，月份从 0 开始，0 表示一月，11 表示十二月。

• 永远别用带参数的 Date(int, int, int) 构造器 —— 它在 Java 9+ 已被标记为 @Deprecated，且语义反直觉
• 想从年月日构造时间，改用 Calendar 设置再调 calendar.getTime()，或直接升级到 LocalDateTime.of(2024, 1, 1, 0, 0)
• 如果必须解析字符串，用 SimpleDateFormat，但注意它不是线程安全的 —— 多线程下必须每个线程 new 一个实例，或用 ThreadLocal 包装

Calendar.get(Calendar.DAY_OF_WEEK) 返回的数字和日常认知不一致

它返回的是 Calendar.SUNDAY = 1、Calendar.MONDAY = 2 … Calendar.SATURDAY = 7。这和 ISO 8601（周一为第一天）或很多数据库（如 MySQL 的 WEEKDAY() 返回 0=周一）都对不上。

• 不要直接拿返回值做「周几中文映射」，先确认你用的 Calendar 实例的 getFirstDayOfWeek() 是什么（不同 Locale 可能不同）
• 跨系统对接时，建议统一转成 ISO 标准：用 calendar.get(Calendar.DAY_OF_WEEK) - calendar.getFirstDayOfWeek() + 1 再模 7 调整
• 更简单的方式：用 LocalDateTime.getDayOfWeek().getValue()（周一=1，周日=7），语义清晰且不可变

Calendar 的 set() 和 add() 行为差异极大

set() 是「惰性设置」：只记下字段值，不立即计算时间戳；而 add() 会立刻触发重计算，并处理进位/借位（比如给 1 月 31 日加一个月，结果是 2 月 28 日或 29 日）。

• 连续调用多次 set() 后直接 getTime()，可能因字段冲突导致意外结果（例如先设 DAY_OF_MONTH = 31，再设 MONTH = 1（二月），最终时间可能是 3 月 3 日）
• 需要精确增减日期时，无条件选 add()；仅需覆盖单个字段且确定其他字段无冲突时，才用 set()
• 如果用 set() 后还要读其他字段（如 get(Calendar.WEEK_OF_YEAR)），务必在读之前调一次 calendar.getTime() 或 calendar.complete() 强制刷新

从 Date 或 Calendar 转 Instant 时，时区容易被忽略

Date 本质是毫秒数（UTC 时间轴上的点），但 Calendar 默认绑定 JVM 本地时区。直接 calendar.getTime().toInstant() 看似没问题，可一旦 Calendar 是用非默认时区构造的（比如 Calendar.getInstance(TimeZone.getTimeZone("GMT"))），结果就可能错。

• 最安全的转换路径：用 calendar.toInstant()（Java 8+），它明确基于 Calendar 自身的时区上下文
• 如果只有 Date，它转 Instant 是安全的（date.toInstant()），但反过来 instant.toEpochMilli() 再塞进 Date 构造器，会丢失纳秒精度（Date 只支持毫秒）
• 所有涉及「显示给用户看的时间」，千万别只靠 Date.toString() —— 它内部用本地时区格式化，同一毫秒数在不同时区机器上输出完全不同

这些类的设计初衷是适配上世纪 90 年代的时区和历法需求，现在看处处是隐式状态和时区陷阱。哪怕只是临时兼容老代码，也建议把解析、计算、展示三阶段严格拆开，中间统一用 Instant 或 ZonedDateTime 过渡。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。