从Calendar到java.time包,系统梳理Java中日期时间API的演进脉络、核心类使用细节、典型场景实现与高频踩坑点,助您写出健壮、高效、可维护的时间处理代码
在Java开发中,java 日历类是处理时间与日期的核心工具。从JDK 1.1起,java.util.Calendar和java.util.GregorianCalendar长期作为标准日期处理类;而自JDK 8起,java.time包(JSR-310规范)引入了全新的LocalDate、LocalDateTime、ZonedDateTime等不可变线程安全类,彻底革新了日期处理方式。
以下为当前主流java 日历类的分类与职责定位:
| 类名 | 所在包 | 版本 | 是否可变 | 线程安全 | 核心用途 |
|---|---|---|---|---|---|
Calendar |
java.util |
JDK 1.1+ | 是 | 否 | 抽象基类,提供统一日期操作接口 |
GregorianCalendar |
java.util |
JDK 1.1+ | 是 | 否 | java 日历类具体实现(公历) |
SimpleDateFormat |
java.text |
JDK 1.1+ | 是 | 否 | 日期格式化(非线程安全) |
LocalDate |
java.time |
JDK 8+ | 否 | 是 | 仅日期(无时区) |
LocalDateTime |
java.time |
JDK 8+ | 否 | 是 | 日期+时间(无时区) |
ZonedDateTime |
java.time |
JDK 8+ | 否 | 是 | 带时区的完整时间 |
DateTimeFormatter |
java.time.format |
JDK 8+ | 否 | 是 | 线程安全格式化器 |
值得注意的是:java 日历类中Calendar的月份字段从0开始(0=一月),而java.time包中的月份从1开始(1=一月)。这一差异是导致“8月显示为7月”等经典Bug的根源之一,需格外警惕。
Calendar与GregorianCalendar深度剖析Calendar核心操作方法getInstance():获取当前系统默认时区的Calendar实例(实际返回GregorianCalendar)get(int field):获取指定字段值(如Calendar.MONTH、Calendar.DAY_OF_MONTH)set(int field, int value):设置指定字段值(注意:set后需调用computeFields()或getTime()生效)add(int field, int amount):对指定字段增减(如add(Calendar.DAY_OF_MONTH, -7))roll(int field, int amount):滚动字段值(不进位,如月份滚动不改变年份)getTime():返回Date对象;setTime(Date):从Date设置时间⚠️ 关键细节:Calendar是抽象类,不能直接实例化;其子类GregorianCalendar是唯一公开实现类(JDK 8后还引入JapaneseCalendar等)。因此推荐直接使用GregorianCalendar以明确语义。
GregorianCalendar用例GregorianCalendar cal = new GregorianCalendar(2026, Calendar.MARCH, 15); // 注意:MARCH=2(实际为3月) cal.set(GregorianCalendar.HOUR_OF_DAY, 14); cal.add(GregorianCalendar.DAY_OF_MONTH, 10); // 加10天 → 3月25日 cal.roll(GregorianCalendar.MONTH, 13); // 月份滚动+13 → 仍为3月(因2026年3+13=16→16%12=4→5月?错误!roll不进位,仅在1-12循环) System.out.println(cal.getTime()); // 输出:Sun Mar 25 14:00:00 CST 2026
上述代码中,roll(MONTH, 13)行为需特别注意:由于Calendar.MARCH=2,2+13=15,但roll在[0,11]范围内循环,15 mod 12 = 3 → Calendar.APRIL(4月),而非5月!
实际运行结果为:2026年4月25日。此例揭示了Calendar的隐式边界处理易引发认知偏差。
Calendar实例均可变,多线程环境下需手动同步,易导致状态污染setTimeZone(),且getTimeZone()返回TimeZone对象可变SimpleDateFormat非线程安全,单例需加锁或用ThreadLocalset/add/roll语义模糊,组合操作复杂Java官方明确建议:自JDK 8起,优先使用java.time包处理日期时间;Calendar仅作为兼容性兜底方案。
java.time包java 日历类体系在JDK 8中迎来革命性重构。JSR-310规范以java.time包为核心,提供了一套不可变、线程安全、领域驱动的日期时间API,彻底解决了旧版设计缺陷。
表示无时区的日期(如生日、节假日),支持日期计算、比较、格式化。
LocalDate today = LocalDate.now(); LocalDate birthday = LocalDate.of(1990, 12, 25); // 12月25日(非偏移) LocalDate nextWeek = today.plusWeeks(1); // 加1周 System.out.println(today.format(DateTimeFormatter.BASIC_ISO_DATE)); // 20260315
表示无时区的日期+时间(如活动开始时间),支持秒级精度。
LocalDateTime meeting = LocalDateTime.of(2026, Month.MARCH, 15, 14, 30); meeting = meeting.plusHours(2).minusMinutes(15); // 16:15 System.out.println(meeting.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)); // 2026-03-15T16:15:00
带时区的完整时间(如纽约会议、UTC日志),支持夏令时自动处理。
ZonedDateTime nyTime = ZonedDateTime.of(2026, 3, 8, 2, 30, 0, 0, ZoneId.of("America/New_York"));
// 美国2026年3月8日2:30进入夏令时(时钟拨快1小时)
System.out.println(nyTime); // 2026-03-08T03:30-04:00[America/New_York]
java 日历类中java.time包的格式化器DateTimeFormatter完全线程安全,且支持模式字符串与预定义格式:
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy年MM月dd日 HH:mm:ss");
LocalDateTime now = LocalDateTime.now();
System.out.println(now.format(formatter)); // 2026年03月15日 14:30:00
此外,java.time包提供丰富的辅助类:
Period:日期差(年/月/日),如Period.between(date1, date2)Duration:时间差(秒/纳秒),如Duration.between(time1, time2)TemporalAdjusters:日期调整器,如firstDayOfMonth()、lastDayOfMonth()示例:计算本月最后一天的星期五:
LocalDate lastFriday = LocalDate.now()
.with(TemporalAdjusters.lastInMonth(DayOfWeek.FRIDAY));
System.out.println(lastFriday); // 2026-03-27
此类链式调用使代码高度可读,显著优于Calendar的嵌套add/set。
| 维度 | Calendar(旧版) |
java.time(新版) |
|---|---|---|
| 可变性 | 可变对象 | 不可变对象 |
| 月份索引 | 0基(0=一月) | 1基(1=一月) |
| 时区支持 | 需手动切换TimeZone |
原生ZoneId/ZoneOffset |
| 格式化器 | SimpleDateFormat(非线程安全) |
DateTimeFormatter(线程安全) |
| 夏令时处理 | 需手动判断 | 自动处理(如ZonedDateTime) |
| API链式调用 | 不支持 | 全面支持 |
LocalDate + PeriodLocalDateTime(服务器时区统一)ZonedDateTime + ZoneIdOffsetDateTime或Instantjava.util.Date):用LocalDate.ofInstant(date.toInstant(), ZoneId.systemDefault())new Date() → LocalDateTime.now()Calendar.getInstance() → LocalDate.now()new SimpleDateFormat(...) → DateTimeFormatter.ofPattern(...)date.getTime()(毫秒) → instant.toEpochMilli()date.before(date2) → date1.isBefore(date2)注意:java.util.Date与Instant可互转,但Calendar与ZonedDateTime转换需经Instant中转:
Calendar cal = Calendar.getInstance(); ZonedDateTime zdt = cal.toInstant().atZone(ZoneId.systemDefault());
现象:用Calendar.MARCH(值为2)设置日期,结果显示为2月而非3月。
原因:Calendar月份字段为0基(0=一月),而java.time为1基。
解法:
Calendar.MARCH而非数字,或改用Month.MARCH(JDK 8+)Month.MARCH枚举,或数字1-12(1=一月)SimpleDateFormat线程安全现象:多线程环境下日期格式化结果错乱(如2026年显示为1970年)。
解法:
DateTimeFormatter(JDK 8+)ThreadLocal<SimpleDateFormat>隔离private static final ThreadLocal<SimpleDateFormat> formatter = ThreadLocal.withInitial(() ->
new SimpleDateFormat("yyyy-MM-dd"));
set未生效现象:调用cal.set(Calendar.DAY_OF_MONTH, 1)后,getTime()未更新。
原因:Calendar延迟计算,需触发computeFields()或getTime()。
解法:在set后立即调用getTime()或getTimeInMillis()。
现象:美国2026年3月8日2:30调表,GregorianCalendar可能生成无效时间(如2:30→3:30)。
解法:
ZonedDateTime自动处理跳变setLenient(false)拒绝无效时间GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone("America/New_York"));
cal.setLenient(false);
cal.set(2026, Calendar.MARCH, 8, 2, 30); // 抛出IllegalArgumentException
Apache Commons Lang的DateUtils提供便捷操作:
DateUtils.addDays(date, 7)DateUtils.truncate(date, Calendar.DAY)DateUtils.isSameDay(date1, date2)但需注意其仍基于java.util.Date,存在旧版缺陷。
JDK 8前最流行的第三方库,其设计直接影响java.time。支持:
LocalDate、DateTime)⚠️ 官方建议:JDK 8+应优先用java.time,而非Joda-Time。
国产工具包,封装java.time为易用API:
DateUtil.now(); // 当前时间字符串 DateUtil.date(); // LocalDate对象 DateUtil.range(DateEnum.DAY, start, end); // 日期范围
适合快速开发,但需引入额外依赖。
Calendar.get(Calendar.DAY_OF_WEEK)返回1表示周日?这是历史约定(美国标准),SUNDAY=1,MONDAY=2...SATURDAY=7。而java.time中DayOfWeek.SUNDAY=7(ISO 8601),需注意转换:
int javaWeek = cal.get(Calendar.DAY_OF_WEEK) - 1; // 1→0(但0非有效) DayOfWeek isoDow = DayOfWeek.of((javaWeek % 7) + 1); // 修正为ISO
旧版:long diff = (date2.getTime() - date1.getTime()) / (1000 * 60 * 60 * 24);(可能因夏令时误差)
新版:long days = ChronoUnit.DAYS.between(date1, date2);(精确)
LocalDate today = LocalDate.now(); LocalDate monday = today.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY));
用Instant表示时间点:
Instant now = Instant.now();
ZonedDateTime utc = now.atZone(ZoneId.of("UTC"));
ZonedDateTime local = now.atZone(ZoneId.systemDefault());