1. 项目概述为什么我们绕不开 Calendar 类在 Java 的世界里处理日期和时间是每个开发者都逃不开的日常。从最简单的记录日志时间戳到复杂的排班系统、财务周期计算再到电商平台的促销活动倒计时日期时间处理无处不在。虽然 Java 8 引入了全新的java.timeAPI也就是 JSR-310功能强大且设计优雅但现实是大量的遗留系统、第三方库以及面试官的“八股文”题库里java.util.Calendar类依然占据着重要的一席之地。我见过不少新手一上来就直奔LocalDateTime结果在对接老系统或者阅读旧代码时面对Calendar的一堆get、set和add操作直接懵了。所以这篇指南的目的很明确不是鼓吹你用Calendar去写新代码而是帮你彻底搞懂这个“历史产物”。理解它你才能更好地维护老项目才能在面试中被问到“Calendar和Date的区别”时对答如流也才能更深刻地体会到java.timeAPI 的设计精妙之处。我们会从最基础的创建对象开始一步步拆解它的核心方法、那些容易踩的“坑”以及如何用它完成常见的业务场景。相信我啃下这块“硬骨头”你对 Java 时间处理的理解会上一个台阶。2. Calendar 类核心设计与思路拆解2.1 理解 Calendar 的抽象与工厂模式Calendar类本身是一个抽象类你不能直接new Calendar()。这种设计体现了“工厂模式”的思想。最常用的获取实例的方法是Calendar.getInstance()。这个方法背后会根据你的默认时区和地区Locale返回一个具体的子类实例通常是GregorianCalendar格里高利历即我们常用的公历。为什么要这么设计因为世界上存在不同的历法系统。虽然我们99%的场景用的是公历但理论上这个抽象结构为支持农历Chinese Lunar Calendar、伊斯兰历等提供了可能。getInstance方法还可以传入时区和地区参数来获取特定区域的日历实例这对于国际化应用很重要。// 获取默认时区和地区的当前日期时间日历实例 Calendar calendar Calendar.getInstance(); // 获取美国纽约时区的日历实例 Calendar nyCalendar Calendar.getInstance(TimeZone.getTimeZone(America/New_York), Locale.US);这里的一个关键点是getInstance()获得的Calendar对象其内部字段年、月、日、时、分、秒等已经被设置为当前时刻。这一点和new Date()类似但Calendar提供了更结构化的访问方式。2.2 字段常量Field Constants与内部状态模型Calendar将日期时间分解为多个独立的字段每个字段用一个整型常量表示。这是它最核心的设计思路。比如Calendar.YEAR: 年份Calendar.MONTH: 月份注意从0开始0代表一月11代表十二月Calendar.DATE或Calendar.DAY_OF_MONTH: 月中的天数1-31Calendar.HOUR_OF_DAY: 24小时制的小时0-23Calendar.MINUTE: 分钟Calendar.SECOND: 秒Calendar.MILLISECOND: 毫秒Calendar.DAY_OF_WEEK: 星期几Calendar.SUNDAY1, ...,Calendar.SATURDAY7你可以把Calendar对象想象成一个拥有多个“旋钮”的复杂时钟每个旋钮对应一个字段。通过get(int field)来读取某个旋钮的当前值通过set(int field, int value)来调整某个旋钮。这种模型非常灵活但也带来了两个著名的“坑”月份从0开始这是最反直觉的地方。calendar.set(Calendar.MONTH, 5)设置的是六月而不是五月。我无数次在代码审查中看到因为这个导致的日期错误。可变性MutabilityCalendar对象是可变的。任何set或add操作都会直接修改对象内部状态。这意味着如果你不小心将同一个Calendar实例传递到多个方法中一个方法的修改可能会意外影响另一个方法引发难以调试的Bug。在并发环境下这更是灾难。2.3 与 Date 类的爱恨纠葛Calendar和Date是旧日期时间 API 的“难兄难弟”。Date本质上是一个包裹着自1970年1月1日00:00:00 GMT以来的毫秒数的对象它的大部分方法如getYear,getMonth都已废弃。Calendar的一个核心职责就是充当Date的“解析器”和“生成器”。Calendar - Date: 通过calendar.getTime()方法可以将Calendar的内部状态转换成一个Date对象。这个Date对象表示的是同一个瞬间。Date - Calendar: 通过calendar.setTime(Date date)方法可以用一个Date对象来设置Calendar的所有字段。Date now new Date(); // 一个简单的时刻表示 Calendar calendar Calendar.getInstance(); calendar.setTime(now); // 将Date的瞬间信息“解码”到Calendar的各个字段中 int year calendar.get(Calendar.YEAR); int month calendar.get(Calendar.MONTH) 1; // 记得1 int day calendar.get(Calendar.DAY_OF_MONTH); // 修改Calendar calendar.add(Calendar.DAY_OF_MONTH, 7); Date nextWeek calendar.getTime(); // 再生成一个新的Date对象理解这种关系你就明白了为什么老代码里总是Date和Calendar混用。Date用于存储和传输时间点就像是一个时间戳而Calendar用于对这个时间点进行复杂的计算和字段操作。3. 核心细节解析与实操要点3.1 创建与初始化 Calendar 实例的多种姿势除了最常用的无参getInstance()根据不同的业务场景正确地初始化Calendar对象是第一步。场景一获取一个表示特定日期/时间的 Calendar如果你想表示一个非当前的时间比如用户的生日 1990年8月20日。有几种方法先获取当前实例再逐个字段设置这是最直观但最繁琐的方法且容易忘记清除其他字段如小时、分钟。Calendar birthday Calendar.getInstance(); birthday.set(Calendar.YEAR, 1990); birthday.set(Calendar.MONTH, Calendar.AUGUST); // 使用常量比直接写7更清晰 birthday.set(Calendar.DAY_OF_MONTH, 20); // 问题此时birthday的小时、分钟、秒还是当前时间这通常不是我们想要的。使用set方法的重载版本一次性设置年、月、日这个方法会自动将小时、分钟、秒、毫秒设置为0对于只关心日期的场景很友好。Calendar birthday Calendar.getInstance(); birthday.set(1990, Calendar.AUGUST, 20); // 时间部分默认为0先清空再设置最安全、最推荐的做法。clear()方法会将所有日历字段值和时间值从历元至现在的毫秒偏移量设置为未定义。然后再设置你关心的字段。Calendar birthday Calendar.getInstance(); birthday.clear(); // 关键一步清除所有字段 birthday.set(Calendar.YEAR, 1990); birthday.set(Calendar.MONTH, Calendar.AUGUST); birthday.set(Calendar.DAY_OF_MONTH, 20); // 现在birthday表示1990-08-20 00:00:00.000非常干净。实操心得在处理纯日期不关心具体时间的业务逻辑时务必使用clear()或set(year, month, day)的重载形式。否则残留的时间部分比如下午3点可能会导致你在进行日期比较或格式化时得到意想不到的结果。这是我早期踩过的一个大坑在比较两个“同一天”的日期时因为一个有时间一个没时间导致判断错误。场景二从时间戳或字符串初始化// 从时间戳毫秒初始化 long timestamp 1621234567890L; Calendar calFromTs Calendar.getInstance(); calFromTs.setTimeInMillis(timestamp); // 从Date对象初始化常见于从数据库或API获取数据 Date someDate ...; Calendar calFromDate Calendar.getInstance(); calFromDate.setTime(someDate); // 从格式化字符串初始化需要配合SimpleDateFormat这是另一个话题但很常见 String dateStr 2023-10-01; SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd); Date date sdf.parse(dateStr); Calendar calFromStr Calendar.getInstance(); calFromStr.setTime(date);3.2 日期时间的计算add 与 roll 的微妙区别Calendar提供了两个非常重要的方法来进行日期时间计算add和roll。它们功能相似但有一个关键区别理解错了会导致业务逻辑错误。add(int field, int amount):字段滚动。这个方法会对指定的日历字段进行加减操作并且会触发更大字段的进位或借位。它的行为符合我们的日常直觉。Calendar cal Calendar.getInstance(); cal.clear(); cal.set(2023, Calendar.DECEMBER, 31); // 2023-12-31 cal.add(Calendar.DAY_OF_MONTH, 1); // 加一天 // 结果2024-01-01。不仅日期变了月份和年份也自动进位了。roll(int field, int amount):字段循环。这个方法也会对指定字段进行加减操作但不会改变更大的字段。它只在当前字段的合法范围内“滚动”。Calendar cal Calendar.getInstance(); cal.clear(); cal.set(2023, Calendar.DECEMBER, 31); // 2023-12-31 cal.roll(Calendar.DAY_OF_MONTH, 1); // 滚动一天 // 结果2023-12-01。日期变成了1号但月份和年份保持不变12月只有31天从31滚动1就回到了1。如何选择绝大多数业务场景如“3天后”、“下个月”你需要的是add。只有当你明确希望字段在固定范围内循环且不影响更大单位时才使用roll。一个典型的例子是模拟一个只有月份和日期变化的时钟界面年份不变。3.3 获取信息get 方法及其衍生get方法是最基本的读取操作。但有几个衍生方法非常实用getActualMaximum(int field): 获取指定字段在当前日历设置下的实际最大值。这比死记硬背每月天数要聪明得多因为它考虑了闰年等因素。Calendar cal Calendar.getInstance(); cal.set(2024, Calendar.FEBRUARY, 1); // 2024年是闰年 int maxDay cal.getActualMaximum(Calendar.DAY_OF_MONTH); System.out.println(maxDay); // 输出29getActualMinimum(int field): 同理获取实际最小值对于DAY_OF_MONTH总是1。getTimeInMillis(): 直接获取自历元1970-01-01 00:00:00 GMT以来的毫秒数。这比getTime().getTime()更高效常用于性能要求高的计算或存储。4. 实操过程与核心环节实现4.1 场景一计算两个日期之间的天数差这是一个高频需求比如计算会员有效期、项目周期等。用Calendar实现需要一点技巧因为直接相减毫秒数会受时区和夏令时影响。最可靠的方法是将两个日期都规范化到当天的起始时刻00:00:00.000再计算毫秒差。public static int daysBetween(Calendar start, Calendar end) { // 创建两个副本避免修改原始对象 Calendar cal1 (Calendar) start.clone(); Calendar cal2 (Calendar) end.clone(); // 将时间部分清零只保留日期 clearTime(cal1); clearTime(cal2); // 计算毫秒差 long diffMs cal2.getTimeInMillis() - cal1.getTimeInMillis(); // 将毫秒差转换为天数 (1000ms * 60s * 60min * 24h) long diffDays diffMs / (1000 * 60 * 60 * 24); return Math.toIntExact(diffDays); } private static void clearTime(Calendar calendar) { calendar.set(Calendar.HOUR_OF_DAY, 0); calendar.set(Calendar.MINUTE, 0); calendar.set(Calendar.SECOND, 0); calendar.set(Calendar.MILLISECOND, 0); } // 使用示例 Calendar start Calendar.getInstance(); start.set(2023, Calendar.OCTOBER, 1); Calendar end Calendar.getInstance(); end.set(2023, Calendar.OCTOBER, 10); int days daysBetween(start, end); // 结果为 9注意事项这里必须使用clone()创建副本。因为clearTime方法会修改Calendar对象的状态。如果不克隆传入的原始start和end对象的时间部分就会被意外清空这违反了方法的“无副作用”原则是潜在的Bug来源。在涉及Calendar计算的工具方法中养成先clone的习惯。4.2 场景二获取某个月的第一天和最后一天在生成报表、统计月度数据时非常常用。public static Calendar getFirstDayOfMonth(Calendar calendar) { Calendar result (Calendar) calendar.clone(); result.set(Calendar.DAY_OF_MONTH, 1); // 设置为当月1号 clearTime(result); // 通常我们只关心日期不关心时间 return result; } public static Calendar getLastDayOfMonth(Calendar calendar) { Calendar result (Calendar) calendar.clone(); // 先设置为下个月1号 result.add(Calendar.MONTH, 1); result.set(Calendar.DAY_OF_MONTH, 1); // 再往回减一天就是本月最后一天 result.add(Calendar.DAY_OF_MONTH, -1); clearTime(result); return result; } // 使用示例 Calendar anyDay Calendar.getInstance(); anyDay.set(2023, Calendar.FEBRUARY, 15); // 2023-02-15 Calendar firstDay getFirstDayOfMonth(anyDay); // 2023-02-01 Calendar lastDay getLastDayOfMonth(anyDay); // 2023-02-284.3 场景三判断某个日期是星期几Calendar.DAY_OF_WEEK字段直接给出了星期几的数字从Calendar.SUNDAY(1) 到Calendar.SATURDAY(7)。但通常我们需要更友好的显示。public static String getDayOfWeekChinese(Calendar calendar) { int dayOfWeek calendar.get(Calendar.DAY_OF_WEEK); switch (dayOfWeek) { case Calendar.SUNDAY: return 星期日; case Calendar.MONDAY: return 星期一; case Calendar.TUESDAY: return 星期二; case Calendar.WEDNESDAY: return 星期三; case Calendar.THURSDAY: return 星期四; case Calendar.FRIDAY: return 星期五; case Calendar.SATURDAY: return 星期六; default: return 未知; } } // 更通用的做法利用Locale public static String getDayOfWeekDisplayName(Calendar calendar, Locale locale) { int dayOfWeek calendar.get(Calendar.DAY_OF_WEEK); // Calendar 提供了获取字段显示名称的方法 return calendar.getDisplayName(Calendar.DAY_OF_WEEK, Calendar.LONG, locale); } // 使用getDayOfWeekDisplayName(cal, Locale.CHINA) - “星期一”4.4 场景四与 SimpleDateFormat 配合进行格式化输出Calendar本身没有toString()成友好字符串的方法需要借助SimpleDateFormat。关键是调用calendar.getTime()获取Date对象。Calendar calendar Calendar.getInstance(); calendar.set(2023, Calendar.OCTOBER, 27, 14, 30, 15); SimpleDateFormat sdf1 new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); System.out.println(sdf1.format(calendar.getTime())); // 输出2023-10-27 14:30:15 SimpleDateFormat sdf2 new SimpleDateFormat(yyyy年MM月dd日 EEEE); System.out.println(sdf2.format(calendar.getTime())); // 输出2023年10月27日 星期五 // 重要SimpleDateFormat 是非线程安全的 // 如果在Web应用等多线程环境使用务必不要将其定义为静态变量。 // 推荐每次使用new一个实例或使用ThreadLocal包装。5. 常见问题与排查技巧实录即使理解了原理在实际编码中Calendar依然有很多“坑”。下面是我总结的常见问题清单和解决方法。5.1 月份总是差1月份从0开始问题现象设置的月份或获取的月份比预期少1或多1。根本原因Calendar.MONTH字段从0开始计数0一月11十二月。解决方案设置时使用Calendar提供的常量如Calendar.JANUARY,Calendar.FEBRUARY等它们已经是正确的数值。calendar.set(Calendar.MONTH, Calendar.MAY); // 正确设置为5月获取时对结果进行1操作。int month calendar.get(Calendar.MONTH) 1; // 得到人类可读的月份1-12格式化输出时交给SimpleDateFormat处理它的 “MM” 模式会输出正确的月份数字。排查技巧当你发现日期相关逻辑出现莫名其妙的“偏移一个月”错误时第一个怀疑点就是MONTH字段。在调试时打印calendar.get(Calendar.MONTH)的值看它是不是你心里想的那个数字。5.2 日期比较结果不符合预期问题现象两个看起来是同一天的Calendar用before()、after()或compareTo()比较时结果却显示不同。根本原因比较的是完整的日期时间包括时、分、秒、毫秒。如果两个对象的时间部分不同即使日期相同比较结果也会不同。解决方案在比较前规范化日期即清除时间部分。public static boolean isSameDay(Calendar cal1, Calendar cal2) { if (cal1 null || cal2 null) { return false; } return cal1.get(Calendar.YEAR) cal2.get(Calendar.YEAR) cal1.get(Calendar.MONTH) cal2.get(Calendar.MONTH) cal1.get(Calendar.DAY_OF_MONTH) cal2.get(Calendar.DAY_OF_MONTH); } // 或者使用上面定义的 clearTime 方法后再比较 getTimeInMillis()。5.3 add 和 set 操作后其他字段发生意外变化问题现象只修改了日期但时间却变了或者修改了时间日期却错了。根本原因Calendar的set方法在某些情况下不会立即重新计算所有字段。它的内部有一个isTimeSet的标志和字段值数组。连续调用多个set方法或者调用set后不立即调用get、getTime、getTimeInMillis、add或roll可能导致字段间的不一致。虽然现代JVM实现中这个问题不那么明显但为了代码健壮性最佳实践是调用set方法后如果涉及多个字段最好紧接着调用一次getTimeInMillis()来强制重新计算。更推荐使用set(year, month, day)或set(year, month, day, hour, minute)等重载方法它们内部会处理同步。对于复杂操作先clear()再按顺序设置字段。5.4 时区TimeZone和夏令时DST导致的诡异问题问题现象在跨时区的系统里计算出的日期差少一天或多一小时。根本原因Calendar.getInstance()默认使用系统默认时区。如果用户处在不同时区或者涉及夏令时切换日期计算就可能出错。解决方案明确时区在创建Calendar实例时如果业务涉及特定时区务必使用Calendar.getInstance(TimeZone zone)。// 处理总是以UTC时间为准的业务逻辑 Calendar utcCal Calendar.getInstance(TimeZone.getTimeZone(UTC));日期计算考虑时区像“计算两天间隔”这种操作必须在同一时区下进行。将输入时间转换到同一时区比如UTC后再计算是稳妥的做法。格式化时指定时区SimpleDateFormat也有时区概念。确保它的时区和你Calendar的时区一致或者都设置为UTC。SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss Z); sdf.setTimeZone(calendar.getTimeZone()); // 保持时区一致 System.out.println(sdf.format(calendar.getTime()));5.5 性能问题与线程安全问题现象在高并发场景下日期处理出错或成为性能瓶颈。根本原因性能Calendar对象的创建和计算特别是涉及时区转换开销相对较大。在循环或高频调用中频繁创建Calendar实例会影响性能。线程安全Calendar本身不是线程安全的。它的内部状态可变如果多个线程共享同一个实例并修改它会导致数据错乱。SimpleDateFormat同样非线程安全。解决方案对象复用对于非关键路径可以考虑使用ThreadLocal来为每个线程缓存一个Calendar实例避免频繁创建。private static final ThreadLocalCalendar CALENDAR_CACHE ThreadLocal.withInitial(() - { Calendar cal Calendar.getInstance(); cal.clear(); // 初始化为一个干净状态 return cal; }); public static Calendar getThreadLocalCalendar() { Calendar cal CALENDAR_CACHE.get(); cal.clear(); // 每次使用前清空避免旧数据干扰 return cal; } // 注意使用完后在线程结束时最好调用 CALENDAR_CACHE.remove() 防止内存泄漏。升级到 java.time对于新项目或重构部分这是终极解决方案。java.time包下的类如LocalDate,ZonedDateTime不可变且线程安全API设计更清晰性能也更好。同步控制如果必须在线程间共享Calendar或SimpleDateFormat那么访问它们时必须进行同步synchronized但这会严重影响并发性能不推荐。5.6 内存泄漏隐患问题现象在Web应用如使用Tomcat中部署或重启时报告内存溢出堆栈跟踪指向Calendar或TimeZone相关代码。根本原因Calendar.getInstance()和TimeZone.getDefault()可能会触发对sun.util.calendar.ZoneInfo等资源的加载。在某些应用服务器中如果 WebApp 的类加载器管理不当这些资源可能无法被正常垃圾回收。排查与缓解这通常不是应用代码的直接错误而是容器级别的类加载器问题。确保你的应用正确清理静态的ThreadLocal变量。考虑在应用关闭的钩子Shutdown Hook中清理可能持有这些资源的缓存。对于新系统直接采用java.time是避免此类历史遗留问题的最佳途径。6. 从 Calendar 平滑迁移到 java.time 的建议虽然本文重点在Calendar但作为负责任的指南必须指出未来的方向。如果你正在开发新功能或重构旧模块强烈建议使用 Java 8 引入的java.timeAPI。对应关系与迁移示例Calendar 操作java.time 对应操作 (推荐)说明Calendar.getInstance()ZonedDateTime.now()获取当前带时区的日期时间calendar.set(2023, Calendar.OCTOBER, 27)LocalDate.of(2023, 10, 27)创建特定日期注意月份是1-12calendar.add(Calendar.DAY_OF_MONTH, 7)localDate.plusDays(7)日期加减API更直观calendar.get(Calendar.DAY_OF_WEEK)localDate.getDayOfWeek()返回DayOfWeek枚举如MONDAYcalendar.getTime()localDateTime.atZone(zone).toInstant()转换为Instant(时间戳)new SimpleDateFormat(...)DateTimeFormatter.ofPattern(...)格式化器线程安全迁移策略渐进式迁移不要试图一次性重写所有代码。对于新增功能直接使用java.time。对于修改的旧功能在理解清楚逻辑后可以将其中的Calendar逻辑替换为java.time。利用适配代码在需要与老API如JDBC、旧的第三方库交互时使用java.time提供的转换方法。// java.time - java.util.Date (用于兼容老API) Date oldDate Date.from(instant); // java.util.Date - java.time Instant instant oldDate.toInstant(); LocalDateTime ldt LocalDateTime.ofInstant(instant, ZoneId.systemDefault());重新设计利用java.time更丰富的类Period,Duration,TemporalAdjusters等重新思考你的日期时间逻辑往往能写出更简洁、健壮的代码。理解Calendar的复杂性和缺陷会让你在拥抱java.time时更加坚定和愉悦。它就像一本老旧的说明书虽然还能用但我们已经有了更清晰、更强大的新工具。掌握它是为了更好地读懂过去然后 confidently 地走向未来。 Java Calendar类深度解析：从核心原理到实战避坑指南
1. 项目概述为什么我们绕不开 Calendar 类在 Java 的世界里处理日期和时间是每个开发者都逃不开的日常。从最简单的记录日志时间戳到复杂的排班系统、财务周期计算再到电商平台的促销活动倒计时日期时间处理无处不在。虽然 Java 8 引入了全新的java.timeAPI也就是 JSR-310功能强大且设计优雅但现实是大量的遗留系统、第三方库以及面试官的“八股文”题库里java.util.Calendar类依然占据着重要的一席之地。我见过不少新手一上来就直奔LocalDateTime结果在对接老系统或者阅读旧代码时面对Calendar的一堆get、set和add操作直接懵了。所以这篇指南的目的很明确不是鼓吹你用Calendar去写新代码而是帮你彻底搞懂这个“历史产物”。理解它你才能更好地维护老项目才能在面试中被问到“Calendar和Date的区别”时对答如流也才能更深刻地体会到java.timeAPI 的设计精妙之处。我们会从最基础的创建对象开始一步步拆解它的核心方法、那些容易踩的“坑”以及如何用它完成常见的业务场景。相信我啃下这块“硬骨头”你对 Java 时间处理的理解会上一个台阶。2. Calendar 类核心设计与思路拆解2.1 理解 Calendar 的抽象与工厂模式Calendar类本身是一个抽象类你不能直接new Calendar()。这种设计体现了“工厂模式”的思想。最常用的获取实例的方法是Calendar.getInstance()。这个方法背后会根据你的默认时区和地区Locale返回一个具体的子类实例通常是GregorianCalendar格里高利历即我们常用的公历。为什么要这么设计因为世界上存在不同的历法系统。虽然我们99%的场景用的是公历但理论上这个抽象结构为支持农历Chinese Lunar Calendar、伊斯兰历等提供了可能。getInstance方法还可以传入时区和地区参数来获取特定区域的日历实例这对于国际化应用很重要。// 获取默认时区和地区的当前日期时间日历实例 Calendar calendar Calendar.getInstance(); // 获取美国纽约时区的日历实例 Calendar nyCalendar Calendar.getInstance(TimeZone.getTimeZone(America/New_York), Locale.US);这里的一个关键点是getInstance()获得的Calendar对象其内部字段年、月、日、时、分、秒等已经被设置为当前时刻。这一点和new Date()类似但Calendar提供了更结构化的访问方式。2.2 字段常量Field Constants与内部状态模型Calendar将日期时间分解为多个独立的字段每个字段用一个整型常量表示。这是它最核心的设计思路。比如Calendar.YEAR: 年份Calendar.MONTH: 月份注意从0开始0代表一月11代表十二月Calendar.DATE或Calendar.DAY_OF_MONTH: 月中的天数1-31Calendar.HOUR_OF_DAY: 24小时制的小时0-23Calendar.MINUTE: 分钟Calendar.SECOND: 秒Calendar.MILLISECOND: 毫秒Calendar.DAY_OF_WEEK: 星期几Calendar.SUNDAY1, ...,Calendar.SATURDAY7你可以把Calendar对象想象成一个拥有多个“旋钮”的复杂时钟每个旋钮对应一个字段。通过get(int field)来读取某个旋钮的当前值通过set(int field, int value)来调整某个旋钮。这种模型非常灵活但也带来了两个著名的“坑”月份从0开始这是最反直觉的地方。calendar.set(Calendar.MONTH, 5)设置的是六月而不是五月。我无数次在代码审查中看到因为这个导致的日期错误。可变性MutabilityCalendar对象是可变的。任何set或add操作都会直接修改对象内部状态。这意味着如果你不小心将同一个Calendar实例传递到多个方法中一个方法的修改可能会意外影响另一个方法引发难以调试的Bug。在并发环境下这更是灾难。2.3 与 Date 类的爱恨纠葛Calendar和Date是旧日期时间 API 的“难兄难弟”。Date本质上是一个包裹着自1970年1月1日00:00:00 GMT以来的毫秒数的对象它的大部分方法如getYear,getMonth都已废弃。Calendar的一个核心职责就是充当Date的“解析器”和“生成器”。Calendar - Date: 通过calendar.getTime()方法可以将Calendar的内部状态转换成一个Date对象。这个Date对象表示的是同一个瞬间。Date - Calendar: 通过calendar.setTime(Date date)方法可以用一个Date对象来设置Calendar的所有字段。Date now new Date(); // 一个简单的时刻表示 Calendar calendar Calendar.getInstance(); calendar.setTime(now); // 将Date的瞬间信息“解码”到Calendar的各个字段中 int year calendar.get(Calendar.YEAR); int month calendar.get(Calendar.MONTH) 1; // 记得1 int day calendar.get(Calendar.DAY_OF_MONTH); // 修改Calendar calendar.add(Calendar.DAY_OF_MONTH, 7); Date nextWeek calendar.getTime(); // 再生成一个新的Date对象理解这种关系你就明白了为什么老代码里总是Date和Calendar混用。Date用于存储和传输时间点就像是一个时间戳而Calendar用于对这个时间点进行复杂的计算和字段操作。3. 核心细节解析与实操要点3.1 创建与初始化 Calendar 实例的多种姿势除了最常用的无参getInstance()根据不同的业务场景正确地初始化Calendar对象是第一步。场景一获取一个表示特定日期/时间的 Calendar如果你想表示一个非当前的时间比如用户的生日 1990年8月20日。有几种方法先获取当前实例再逐个字段设置这是最直观但最繁琐的方法且容易忘记清除其他字段如小时、分钟。Calendar birthday Calendar.getInstance(); birthday.set(Calendar.YEAR, 1990); birthday.set(Calendar.MONTH, Calendar.AUGUST); // 使用常量比直接写7更清晰 birthday.set(Calendar.DAY_OF_MONTH, 20); // 问题此时birthday的小时、分钟、秒还是当前时间这通常不是我们想要的。使用set方法的重载版本一次性设置年、月、日这个方法会自动将小时、分钟、秒、毫秒设置为0对于只关心日期的场景很友好。Calendar birthday Calendar.getInstance(); birthday.set(1990, Calendar.AUGUST, 20); // 时间部分默认为0先清空再设置最安全、最推荐的做法。clear()方法会将所有日历字段值和时间值从历元至现在的毫秒偏移量设置为未定义。然后再设置你关心的字段。Calendar birthday Calendar.getInstance(); birthday.clear(); // 关键一步清除所有字段 birthday.set(Calendar.YEAR, 1990); birthday.set(Calendar.MONTH, Calendar.AUGUST); birthday.set(Calendar.DAY_OF_MONTH, 20); // 现在birthday表示1990-08-20 00:00:00.000非常干净。实操心得在处理纯日期不关心具体时间的业务逻辑时务必使用clear()或set(year, month, day)的重载形式。否则残留的时间部分比如下午3点可能会导致你在进行日期比较或格式化时得到意想不到的结果。这是我早期踩过的一个大坑在比较两个“同一天”的日期时因为一个有时间一个没时间导致判断错误。场景二从时间戳或字符串初始化// 从时间戳毫秒初始化 long timestamp 1621234567890L; Calendar calFromTs Calendar.getInstance(); calFromTs.setTimeInMillis(timestamp); // 从Date对象初始化常见于从数据库或API获取数据 Date someDate ...; Calendar calFromDate Calendar.getInstance(); calFromDate.setTime(someDate); // 从格式化字符串初始化需要配合SimpleDateFormat这是另一个话题但很常见 String dateStr 2023-10-01; SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd); Date date sdf.parse(dateStr); Calendar calFromStr Calendar.getInstance(); calFromStr.setTime(date);3.2 日期时间的计算add 与 roll 的微妙区别Calendar提供了两个非常重要的方法来进行日期时间计算add和roll。它们功能相似但有一个关键区别理解错了会导致业务逻辑错误。add(int field, int amount):字段滚动。这个方法会对指定的日历字段进行加减操作并且会触发更大字段的进位或借位。它的行为符合我们的日常直觉。Calendar cal Calendar.getInstance(); cal.clear(); cal.set(2023, Calendar.DECEMBER, 31); // 2023-12-31 cal.add(Calendar.DAY_OF_MONTH, 1); // 加一天 // 结果2024-01-01。不仅日期变了月份和年份也自动进位了。roll(int field, int amount):字段循环。这个方法也会对指定字段进行加减操作但不会改变更大的字段。它只在当前字段的合法范围内“滚动”。Calendar cal Calendar.getInstance(); cal.clear(); cal.set(2023, Calendar.DECEMBER, 31); // 2023-12-31 cal.roll(Calendar.DAY_OF_MONTH, 1); // 滚动一天 // 结果2023-12-01。日期变成了1号但月份和年份保持不变12月只有31天从31滚动1就回到了1。如何选择绝大多数业务场景如“3天后”、“下个月”你需要的是add。只有当你明确希望字段在固定范围内循环且不影响更大单位时才使用roll。一个典型的例子是模拟一个只有月份和日期变化的时钟界面年份不变。3.3 获取信息get 方法及其衍生get方法是最基本的读取操作。但有几个衍生方法非常实用getActualMaximum(int field): 获取指定字段在当前日历设置下的实际最大值。这比死记硬背每月天数要聪明得多因为它考虑了闰年等因素。Calendar cal Calendar.getInstance(); cal.set(2024, Calendar.FEBRUARY, 1); // 2024年是闰年 int maxDay cal.getActualMaximum(Calendar.DAY_OF_MONTH); System.out.println(maxDay); // 输出29getActualMinimum(int field): 同理获取实际最小值对于DAY_OF_MONTH总是1。getTimeInMillis(): 直接获取自历元1970-01-01 00:00:00 GMT以来的毫秒数。这比getTime().getTime()更高效常用于性能要求高的计算或存储。4. 实操过程与核心环节实现4.1 场景一计算两个日期之间的天数差这是一个高频需求比如计算会员有效期、项目周期等。用Calendar实现需要一点技巧因为直接相减毫秒数会受时区和夏令时影响。最可靠的方法是将两个日期都规范化到当天的起始时刻00:00:00.000再计算毫秒差。public static int daysBetween(Calendar start, Calendar end) { // 创建两个副本避免修改原始对象 Calendar cal1 (Calendar) start.clone(); Calendar cal2 (Calendar) end.clone(); // 将时间部分清零只保留日期 clearTime(cal1); clearTime(cal2); // 计算毫秒差 long diffMs cal2.getTimeInMillis() - cal1.getTimeInMillis(); // 将毫秒差转换为天数 (1000ms * 60s * 60min * 24h) long diffDays diffMs / (1000 * 60 * 60 * 24); return Math.toIntExact(diffDays); } private static void clearTime(Calendar calendar) { calendar.set(Calendar.HOUR_OF_DAY, 0); calendar.set(Calendar.MINUTE, 0); calendar.set(Calendar.SECOND, 0); calendar.set(Calendar.MILLISECOND, 0); } // 使用示例 Calendar start Calendar.getInstance(); start.set(2023, Calendar.OCTOBER, 1); Calendar end Calendar.getInstance(); end.set(2023, Calendar.OCTOBER, 10); int days daysBetween(start, end); // 结果为 9注意事项这里必须使用clone()创建副本。因为clearTime方法会修改Calendar对象的状态。如果不克隆传入的原始start和end对象的时间部分就会被意外清空这违反了方法的“无副作用”原则是潜在的Bug来源。在涉及Calendar计算的工具方法中养成先clone的习惯。4.2 场景二获取某个月的第一天和最后一天在生成报表、统计月度数据时非常常用。public static Calendar getFirstDayOfMonth(Calendar calendar) { Calendar result (Calendar) calendar.clone(); result.set(Calendar.DAY_OF_MONTH, 1); // 设置为当月1号 clearTime(result); // 通常我们只关心日期不关心时间 return result; } public static Calendar getLastDayOfMonth(Calendar calendar) { Calendar result (Calendar) calendar.clone(); // 先设置为下个月1号 result.add(Calendar.MONTH, 1); result.set(Calendar.DAY_OF_MONTH, 1); // 再往回减一天就是本月最后一天 result.add(Calendar.DAY_OF_MONTH, -1); clearTime(result); return result; } // 使用示例 Calendar anyDay Calendar.getInstance(); anyDay.set(2023, Calendar.FEBRUARY, 15); // 2023-02-15 Calendar firstDay getFirstDayOfMonth(anyDay); // 2023-02-01 Calendar lastDay getLastDayOfMonth(anyDay); // 2023-02-284.3 场景三判断某个日期是星期几Calendar.DAY_OF_WEEK字段直接给出了星期几的数字从Calendar.SUNDAY(1) 到Calendar.SATURDAY(7)。但通常我们需要更友好的显示。public static String getDayOfWeekChinese(Calendar calendar) { int dayOfWeek calendar.get(Calendar.DAY_OF_WEEK); switch (dayOfWeek) { case Calendar.SUNDAY: return 星期日; case Calendar.MONDAY: return 星期一; case Calendar.TUESDAY: return 星期二; case Calendar.WEDNESDAY: return 星期三; case Calendar.THURSDAY: return 星期四; case Calendar.FRIDAY: return 星期五; case Calendar.SATURDAY: return 星期六; default: return 未知; } } // 更通用的做法利用Locale public static String getDayOfWeekDisplayName(Calendar calendar, Locale locale) { int dayOfWeek calendar.get(Calendar.DAY_OF_WEEK); // Calendar 提供了获取字段显示名称的方法 return calendar.getDisplayName(Calendar.DAY_OF_WEEK, Calendar.LONG, locale); } // 使用getDayOfWeekDisplayName(cal, Locale.CHINA) - “星期一”4.4 场景四与 SimpleDateFormat 配合进行格式化输出Calendar本身没有toString()成友好字符串的方法需要借助SimpleDateFormat。关键是调用calendar.getTime()获取Date对象。Calendar calendar Calendar.getInstance(); calendar.set(2023, Calendar.OCTOBER, 27, 14, 30, 15); SimpleDateFormat sdf1 new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); System.out.println(sdf1.format(calendar.getTime())); // 输出2023-10-27 14:30:15 SimpleDateFormat sdf2 new SimpleDateFormat(yyyy年MM月dd日 EEEE); System.out.println(sdf2.format(calendar.getTime())); // 输出2023年10月27日 星期五 // 重要SimpleDateFormat 是非线程安全的 // 如果在Web应用等多线程环境使用务必不要将其定义为静态变量。 // 推荐每次使用new一个实例或使用ThreadLocal包装。5. 常见问题与排查技巧实录即使理解了原理在实际编码中Calendar依然有很多“坑”。下面是我总结的常见问题清单和解决方法。5.1 月份总是差1月份从0开始问题现象设置的月份或获取的月份比预期少1或多1。根本原因Calendar.MONTH字段从0开始计数0一月11十二月。解决方案设置时使用Calendar提供的常量如Calendar.JANUARY,Calendar.FEBRUARY等它们已经是正确的数值。calendar.set(Calendar.MONTH, Calendar.MAY); // 正确设置为5月获取时对结果进行1操作。int month calendar.get(Calendar.MONTH) 1; // 得到人类可读的月份1-12格式化输出时交给SimpleDateFormat处理它的 “MM” 模式会输出正确的月份数字。排查技巧当你发现日期相关逻辑出现莫名其妙的“偏移一个月”错误时第一个怀疑点就是MONTH字段。在调试时打印calendar.get(Calendar.MONTH)的值看它是不是你心里想的那个数字。5.2 日期比较结果不符合预期问题现象两个看起来是同一天的Calendar用before()、after()或compareTo()比较时结果却显示不同。根本原因比较的是完整的日期时间包括时、分、秒、毫秒。如果两个对象的时间部分不同即使日期相同比较结果也会不同。解决方案在比较前规范化日期即清除时间部分。public static boolean isSameDay(Calendar cal1, Calendar cal2) { if (cal1 null || cal2 null) { return false; } return cal1.get(Calendar.YEAR) cal2.get(Calendar.YEAR) cal1.get(Calendar.MONTH) cal2.get(Calendar.MONTH) cal1.get(Calendar.DAY_OF_MONTH) cal2.get(Calendar.DAY_OF_MONTH); } // 或者使用上面定义的 clearTime 方法后再比较 getTimeInMillis()。5.3 add 和 set 操作后其他字段发生意外变化问题现象只修改了日期但时间却变了或者修改了时间日期却错了。根本原因Calendar的set方法在某些情况下不会立即重新计算所有字段。它的内部有一个isTimeSet的标志和字段值数组。连续调用多个set方法或者调用set后不立即调用get、getTime、getTimeInMillis、add或roll可能导致字段间的不一致。虽然现代JVM实现中这个问题不那么明显但为了代码健壮性最佳实践是调用set方法后如果涉及多个字段最好紧接着调用一次getTimeInMillis()来强制重新计算。更推荐使用set(year, month, day)或set(year, month, day, hour, minute)等重载方法它们内部会处理同步。对于复杂操作先clear()再按顺序设置字段。5.4 时区TimeZone和夏令时DST导致的诡异问题问题现象在跨时区的系统里计算出的日期差少一天或多一小时。根本原因Calendar.getInstance()默认使用系统默认时区。如果用户处在不同时区或者涉及夏令时切换日期计算就可能出错。解决方案明确时区在创建Calendar实例时如果业务涉及特定时区务必使用Calendar.getInstance(TimeZone zone)。// 处理总是以UTC时间为准的业务逻辑 Calendar utcCal Calendar.getInstance(TimeZone.getTimeZone(UTC));日期计算考虑时区像“计算两天间隔”这种操作必须在同一时区下进行。将输入时间转换到同一时区比如UTC后再计算是稳妥的做法。格式化时指定时区SimpleDateFormat也有时区概念。确保它的时区和你Calendar的时区一致或者都设置为UTC。SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss Z); sdf.setTimeZone(calendar.getTimeZone()); // 保持时区一致 System.out.println(sdf.format(calendar.getTime()));5.5 性能问题与线程安全问题现象在高并发场景下日期处理出错或成为性能瓶颈。根本原因性能Calendar对象的创建和计算特别是涉及时区转换开销相对较大。在循环或高频调用中频繁创建Calendar实例会影响性能。线程安全Calendar本身不是线程安全的。它的内部状态可变如果多个线程共享同一个实例并修改它会导致数据错乱。SimpleDateFormat同样非线程安全。解决方案对象复用对于非关键路径可以考虑使用ThreadLocal来为每个线程缓存一个Calendar实例避免频繁创建。private static final ThreadLocalCalendar CALENDAR_CACHE ThreadLocal.withInitial(() - { Calendar cal Calendar.getInstance(); cal.clear(); // 初始化为一个干净状态 return cal; }); public static Calendar getThreadLocalCalendar() { Calendar cal CALENDAR_CACHE.get(); cal.clear(); // 每次使用前清空避免旧数据干扰 return cal; } // 注意使用完后在线程结束时最好调用 CALENDAR_CACHE.remove() 防止内存泄漏。升级到 java.time对于新项目或重构部分这是终极解决方案。java.time包下的类如LocalDate,ZonedDateTime不可变且线程安全API设计更清晰性能也更好。同步控制如果必须在线程间共享Calendar或SimpleDateFormat那么访问它们时必须进行同步synchronized但这会严重影响并发性能不推荐。5.6 内存泄漏隐患问题现象在Web应用如使用Tomcat中部署或重启时报告内存溢出堆栈跟踪指向Calendar或TimeZone相关代码。根本原因Calendar.getInstance()和TimeZone.getDefault()可能会触发对sun.util.calendar.ZoneInfo等资源的加载。在某些应用服务器中如果 WebApp 的类加载器管理不当这些资源可能无法被正常垃圾回收。排查与缓解这通常不是应用代码的直接错误而是容器级别的类加载器问题。确保你的应用正确清理静态的ThreadLocal变量。考虑在应用关闭的钩子Shutdown Hook中清理可能持有这些资源的缓存。对于新系统直接采用java.time是避免此类历史遗留问题的最佳途径。6. 从 Calendar 平滑迁移到 java.time 的建议虽然本文重点在Calendar但作为负责任的指南必须指出未来的方向。如果你正在开发新功能或重构旧模块强烈建议使用 Java 8 引入的java.timeAPI。对应关系与迁移示例Calendar 操作java.time 对应操作 (推荐)说明Calendar.getInstance()ZonedDateTime.now()获取当前带时区的日期时间calendar.set(2023, Calendar.OCTOBER, 27)LocalDate.of(2023, 10, 27)创建特定日期注意月份是1-12calendar.add(Calendar.DAY_OF_MONTH, 7)localDate.plusDays(7)日期加减API更直观calendar.get(Calendar.DAY_OF_WEEK)localDate.getDayOfWeek()返回DayOfWeek枚举如MONDAYcalendar.getTime()localDateTime.atZone(zone).toInstant()转换为Instant(时间戳)new SimpleDateFormat(...)DateTimeFormatter.ofPattern(...)格式化器线程安全迁移策略渐进式迁移不要试图一次性重写所有代码。对于新增功能直接使用java.time。对于修改的旧功能在理解清楚逻辑后可以将其中的Calendar逻辑替换为java.time。利用适配代码在需要与老API如JDBC、旧的第三方库交互时使用java.time提供的转换方法。// java.time - java.util.Date (用于兼容老API) Date oldDate Date.from(instant); // java.util.Date - java.time Instant instant oldDate.toInstant(); LocalDateTime ldt LocalDateTime.ofInstant(instant, ZoneId.systemDefault());重新设计利用java.time更丰富的类Period,Duration,TemporalAdjusters等重新思考你的日期时间逻辑往往能写出更简洁、健壮的代码。理解Calendar的复杂性和缺陷会让你在拥抱java.time时更加坚定和愉悦。它就像一本老旧的说明书虽然还能用但我们已经有了更清晰、更强大的新工具。掌握它是为了更好地读懂过去然后 confidently 地走向未来。