1. 项目概述为什么我们还在讨论Calendar如果你是一个Java初学者或者刚从其他语言转过来第一次接触Java的日期时间处理大概率会先遇到java.util.Date然后很快就会被它的各种“反人类”设计搞得晕头转向。接着你可能会在搜索引擎或者老项目的代码里发现一个叫Calendar的类。它看起来比Date强大能加减年月日能获取星期几似乎解决了Date的不少问题。但我要告诉你一个可能会让你惊讶的事实在今天的Java开发中Calendar类已经是一个“不推荐在新代码中使用”的遗留类了。从Java 8开始官方就推出了全新的日期时间APIjava.time包它更清晰、更强大、更不易出错。那为什么我们还要花时间学习Calendar呢原因很现实存量代码和面试八股文。大量的老系统、遗留框架比如一些老版本的Spring、Hibernate配置以及第三方库的内部实现依然在使用Calendar。作为开发者你不可避免地需要阅读、维护甚至修改这些代码。同时Calendar的诸多“坑点”和设计缺陷是Java面试中经久不衰的经典题目理解它有助于你更深刻地理解为什么新的java.timeAPI如此设计。所以这篇指南的目的不是鼓励你在新项目中使用Calendar而是帮你彻底搞懂这个“历史文物”让你能从容应对老代码并在面试中游刃有余。我们会从它的核心设计缺陷讲起再到每一个关键方法的使用和陷阱最后对比现代API让你知其然更知其所以然。2. Calendar的核心设计可变性与反直觉的月份Calendar是一个抽象类你不能直接new Calendar()。最常用的实现是GregorianCalendar即公历日历。它的核心设计思想在今天看来有两个非常突出的问题。2.1 可变性Mutability一切错误的根源Calendar对象是可变的mutable。这意味着你调用一个方法比如add,set后对象内部的状态就被永久改变了。这在多线程环境下是灾难性的也违背了函数式编程中“不可变对象更安全”的理念。Calendar cal1 Calendar.getInstance(); cal1.set(2023, Calendar.DECEMBER, 25); // 设置圣诞节 Calendar cal2 cal1; // cal2 和 cal1 指向同一个对象 cal2.add(Calendar.DATE, 7); // 给 cal2 加7天 System.out.println(cal1.getTime()); // 输出Mon Jan 01 00:00:00 CST 2024 // 你只是想操作cal2结果cal1也被意外修改了注意这是Calendar最经典的坑之一。如果你需要基于一个现有日期进行计算并保留原日期必须先克隆clone一个副本。Calendar cal1 Calendar.getInstance(); cal1.set(2023, Calendar.DECEMBER, 25); Calendar cal2 (Calendar) cal1.clone(); // 关键克隆 cal2.add(Calendar.DATE, 7); // 此时cal1仍然是圣诞节cal2是新年2.2 反直觉的常量月份从0开始这是另一个让无数新手甚至老手抓狂的设计。在Calendar中表示月份的常量Calendar.JANUARY的值是0Calendar.DECEMBER的值是11。Calendar cal Calendar.getInstance(); cal.set(2023, 11, 25); // 你想设置12月25日错了这里11代表12月。 // 更清晰的写法但仍然容易忘 cal.set(2023, Calendar.DECEMBER, 25); // 使用常量可读性稍好当你用cal.set(2023, 12, 25)时你心里想的是12月25日但程序实际会将其解释为“2023年第13个月的第25天”。Calendar内部有自动规范化normalization机制它会将“第13个月”转换为“下一年的第1个月”所以最终日期会变成2024年1月25日。这个静默的转换是许多隐蔽Bug的来源。实操心得在set年、月、日时强烈建议使用Calendar提供的月份常量如Calendar.JANUARY这能极大减少因数字混淆导致的错误。虽然写起来长一点但代码的意图清晰得多。3. Calendar的实战操作获取、设置与计算理解了核心设计缺陷我们来看具体怎么用它。首先如何获取一个Calendar实例3.1 实例化与初始状态Calendar.getInstance()是工厂方法它会根据你的默认时区TimeZone.getDefault()和区域设置Locale.getDefault()返回一个Calendar实例通常是GregorianCalendar。Calendar calendar Calendar.getInstance(); // 这个calendar对象被创建时其内部字段已经被设置为当前时刻。 // 注意这个“当前时刻”包含了年、月、日、时、分、秒、毫秒所有信息。刚获取的实例就代表了“现在”。你可以通过getTime()方法将其转换回那个古老的Date对象或者用getTimeInMillis()获取毫秒时间戳。3.2 字段的获取get与解读Calendar将日期时间分解为多个字段field如年、月、日、时、分、秒、星期等。使用get(int field)方法获取。Calendar cal Calendar.getInstance(); cal.set(2023, Calendar.DECEMBER, 25, 14, 30, 0); // 2023-12-25 14:30:00 int year cal.get(Calendar.YEAR); // 2023 int month cal.get(Calendar.MONTH); // 11 (记住DECEMBER常量就是11) int dayOfMonth cal.get(Calendar.DAY_OF_MONTH); // 25 int hourOfDay cal.get(Calendar.HOUR_OF_DAY); // 14 (24小时制) int hour cal.get(Calendar.HOUR); // 2 (12小时制需要配合AM_PM) int minute cal.get(Calendar.MINUTE); // 30 int second cal.get(Calendar.SECOND); // 0 int dayOfWeek cal.get(Calendar.DAY_OF_WEEK); // 2 (注意SUNDAY是1, MONDAY是2... SATURDAY是7) int weekOfYear cal.get(Calendar.WEEK_OF_YEAR); // 52 (这一周是今年的第几周)这里有几个关键点DAY_OF_WEEK星期几。Calendar.SUNDAY 1,Calendar.MONDAY 2, ...,Calendar.SATURDAY 7。这个设计也和很多人的直觉周一为1不符。WEEK_OF_YEAR和WEEK_OF_MONTH这两个字段的计算依赖于Calendar的“一周起始日”和“最小天数在首周”的设置通过setFirstDayOfWeek和setMinimalDaysInFirstWeek控制。不同区域对“第一周”的定义可能不同例如是包含1月1日的那周还是第一个完整的周这会导致跨年跨周的周数计算出现不一致是另一个著名的坑。HOURvsHOUR_OF_DAYHOUR是12小时制0-11需要结合Calendar.AM_PM字段0AM, 1PM才能确定具体是上午还是下午的几点。在绝大多数需要明确时间的业务场景中你应该使用HOUR_OF_DAY。3.3 字段的设置set与叠加计算add, roll设置字段主要用set方法。它可以一次设置多个字段也可以单独设置。Calendar cal Calendar.getInstance(); // 方法1分别设置年、月、日 cal.set(Calendar.YEAR, 2024); cal.set(Calendar.MONTH, Calendar.JANUARY); // 月份用常量 cal.set(Calendar.DAY_OF_MONTH, 1); // 方法2一次性设置年、月、日 cal.set(2024, Calendar.JANUARY, 1); // 方法3一次性设置年、月、日、时、分、秒 cal.set(2024, Calendar.JANUARY, 1, 10, 30, 15);更强大的功能是日期计算主要靠add和roll方法。add(int field, int amount)对指定时间字段进行加减。这个方法会触发规范化。例如给月份加13个月年份会自动进位。cal.set(2023, Calendar.DECEMBER, 31); cal.add(Calendar.MONTH, 1); // 加一个月 // 结果2024-01-31。它智能地处理了跨年。 cal.add(Calendar.DAY_OF_MONTH, -1); // 减一天 // 结果2024-01-30。roll(int field, int amount)在指定字段上“滚动”但不会影响更大的字段。这是add和roll最大的区别。cal.set(2023, Calendar.DECEMBER, 31); cal.roll(Calendar.MONTH, 1); // 在月份上滚动1 // 结果2023-01-31。年份不变月份从12月11滚动到了1月0。 // 注意因为1月31日有效所以日期保持31。如果从1月31日roll到2月日期会被规范化为2月的最后一天28或29日。避坑指南add方法是最常用也最符合直觉的日期计算方式。而roll的行为非常特殊除非你明确需要“只在当前字段循环而不影响上级字段”的场景这种场景极少否则请避免使用roll它的结果常常出乎意料。4. 格式化输出与字符串解析Calendar本身没有toString()方法能直接输出可读的日期字符串。你需要借助DateFormat或其子类SimpleDateFormat。4.1 使用SimpleDateFormat格式化Calendar cal Calendar.getInstance(); cal.set(2023, Calendar.DECEMBER, 25, 14, 30, 5); SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); String formattedDate sdf.format(cal.getTime()); // 先将Calendar转为Date System.out.println(formattedDate); // 输出2023-12-25 14:30:05这里又引出了Calendar以及Date的另一个大问题时区信息是附着在Calendar实例和DateFormat实例上的。上面的代码使用了默认时区。如果你的服务器时区是UTC而你需要显示东八区时间就需要显式设置。SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); sdf.setTimeZone(TimeZone.getTimeZone(Asia/Shanghai)); // 设置为上海时区 String shanghaiTime sdf.format(cal.getTime());4.2 从字符串解析到Calendar解析过程是格式化的逆过程但陷阱更多。String dateStr 2023-12-25 14:30:05; SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd HH:mm:ss); try { Date parsedDate sdf.parse(dateStr); // 1. 先解析成Date Calendar cal Calendar.getInstance(); cal.setTime(parsedDate); // 2. 用setTime方法将Date设置给Calendar // 现在cal就代表了字符串对应的日期时间 } catch (ParseException e) { e.printStackTrace(); }重大警告SimpleDateFormat是非线程安全的绝对不要在多线程环境下共享同一个SimpleDateFormat实例否则会导致解析结果错乱或抛出异常。这是Java遗留日期API中著名的“线程杀手”。常见的解决方案有每次使用都创建新实例性能差。使用ThreadLocal为每个线程分配一个独立的实例推荐。使用第三方库如Apache Commons Lang的FastDateFormat线程安全。 当然最好的办法是升级到Java 8使用线程安全的DateTimeFormatter。5. 常见陷阱与面试题深度剖析结合网络热词和常见面试问题我们来深入剖析几个Calendar的经典陷阱。5.1 陷阱一月份数字的坑再现面试常问“cal.set(2023, 12, 25)得到的日期是什么” 我们现在知道月份12会被当作第13个月内部规范化后日期变为2024年1月25日。永远记住用常量别用数字。5.2 陷阱二星期的开始Calendar.DAY_OF_WEEK周日是1周一是2。如果你需要按中国习惯周一为每周第一天进行周计算你需要cal.setFirstDayOfWeek(Calendar.MONDAY); // 设置周一为一周的第一天 // 然后再获取WEEK_OF_YEAR等结果才会符合中国习惯。很多国际化应用在这里栽跟头因为不同地区的周起始日不同。5.3 陷阱三get方法的延迟计算与set的副作用Calendar内部有一个boolean[] isSet字段来标记哪些字段被显式设置过还有一个boolean isTimeSet标记时间是否被计算过。当你调用一系列set方法后并不会立即重新计算所有字段如时间戳。直到你调用getTime()、getTimeInMillis()或get某个字段时它才会进行“计算”和“规范化”。这个延迟计算机制在某些连续set操作时会因为内部状态不一致导致意外结果。一个经典的例子是清除字段Calendar cal Calendar.getInstance(); cal.set(2023, Calendar.JULY, 31); // 2023-07-31 cal.set(Calendar.MONTH, Calendar.AUGUST); // 你想改成8月31日 // 但8月只有31天吗不8月有31天所以这里没问题结果是2023-08-31。 // 但如果是从1月31日改成2月呢 cal.set(2023, Calendar.JANUARY, 31); cal.set(Calendar.MONTH, Calendar.FEBRUARY); // 2月没有31号 // 此时Calendar不会立即报错。它会进行“规范化”将日期调整为2023-03-03因为2023年2月只有28天31-283溢出到3月3日。 System.out.println(cal.getTime()); // 输出Fri Mar 03 ... 这很可能不是你想要的结果。正确的做法是在更改月份等可能引起日期无效的字段时使用set方法的重载版本一次性设置或者使用add/roll方法或者更安全地在设置后检查日期是否有效。5.4 面试题“如何获取某个月的最后一天”这是一个高频问题。利用Calendar的规范化机制可以巧妙地实现Calendar cal Calendar.getInstance(); cal.set(Calendar.YEAR, 2023); cal.set(Calendar.MONTH, Calendar.FEBRUARY); // 设置为2月 // 关键步骤将日期设置为0 cal.set(Calendar.DAY_OF_MONTH, 0); // 内部规范化0日意味着上个月的最后一天。所以这里会变成2023-01-31。 // 但这不对我们要的是2月的最后一天。 // 正确做法先将日期设为1号然后月份加1再日期减1。 cal.set(Calendar.DAY_OF_MONTH, 1); // 设为当月1号 cal.add(Calendar.MONTH, 1); // 月份加1变成3月1号 cal.add(Calendar.DAY_OF_MONTH, -1); // 日期减1变成2月最后一天 int lastDay cal.get(Calendar.DAY_OF_MONTH); // 得到28或29更简单的办法如果你知道是2月是判断闰年但上述方法是通用的。而在Java 8中一行代码搞定LocalDate.of(2023, 2, 1).lengthOfMonth()。6. 与现代java.time API的对比与迁移建议理解了Calendar的种种不便你就能明白java.timeJSR-310的伟大。这里做一个快速对比作为你未来代码迁移的指南。特性java.util.Calendar/Datejava.time(Java 8)核心类Date,Calendar,GregorianCalendarInstant,LocalDate,LocalTime,LocalDateTime,ZonedDateTime可变性可变线程不安全不可变线程安全设计清晰度糟糕。Date代表瞬间Calendar处理日历职责混乱。优秀。明确区分了时刻、日期、时间、时区。月份0-11反直觉1-12符合直觉星期周日1Calendar.SUNDAY周一1DayOfWeek.MONDAY符合ISO标准创建方式Calendar.getInstance()new Date()工厂方法LocalDate.now(),LocalDate.of(...)计算与修改cal.add(field, amount)(原地修改)date.plusDays(1)(返回新对象)格式化/解析SimpleDateFormat非线程安全DateTimeFormatter线程安全时区处理繁琐通过TimeZone和Calendar结合清晰ZonedDateTime,withZoneSameInstant周期计算非常困难简单Period,Duration类迁移建议新项目毫不犹豫地使用java.time包。它是现代Java日期时间处理的唯一选择。老项目维护如果只是小范围修改继续用Calendar但务必注意本文提到的所有陷阱。如果进行较大规模重构或者新增模块强烈建议在新代码中使用java.time。两者可以通过以下方式桥接// Calendar - java.time Calendar cal Calendar.getInstance(); Instant instant cal.toInstant(); // 转换为Instant ZonedDateTime zdt instant.atZone(cal.getTimeZone().toZoneId()); LocalDate localDate zdt.toLocalDate(); // java.time - Calendar (不推荐但必要时) LocalDate ld LocalDate.now(); ZonedDateTime zdt ld.atStartOfDay(ZoneId.systemDefault()); Calendar cal Calendar.getInstance(); cal.clear(); cal.setTimeInMillis(zdt.toInstant().toEpochMilli());7. 总结与最终建议回顾Calendar类它是在Date基础上的一次重要改进引入了字段化、本地化、计算等概念支撑了Java十多年的日期时间处理。然而其固有的可变性、反直觉的API设计0起始月份、非线程安全的配套类SimpleDateFormat以及时区处理的晦涩使得它在现代软件开发中显得笨拙且易错。我个人在处理遗留系统时面对Calendar代码会格外小心。我的检查清单通常是月份和星期检查所有set和get中的月份数字是否应该替换为常量。对象克隆检查是否有多个引用指向同一个Calendar实例是否需要clone()。时区检查格式化/解析时是否显式指定了时区业务逻辑是否依赖于服务器默认时区。SimpleDateFormat检查其使用范围确保没有跨线程共享。周计算如果涉及WEEK_OF_YEAR确认firstDayOfWeek和minimalDaysInFirstWeek的设置是否符合业务需求。最后对于学习者我的建议是花足够的时间理解Calendar的原理和坑是为了更好地告别它。当你深刻体会了它的种种不便你才会真正欣赏java.timeAPI的优雅与严谨。把这篇文章当作一份“考古手册”和“避坑地图”助你在面对历史代码时心中有数在面试谈论日期时间时能道出其演进的历史必然性。而当你开始编写新的代码时请径直走向java.time的世界。
)
