当前版本:JDK 21|最后更新:2026年3月|返回顶部

java 日历类|日期处理权威指南

java 日历类|全面解析Java日期与时间处理体系

从Calendar到java.time包,系统梳理Java中日期时间API的演进脉络、核心类使用细节、典型场景实现与高频踩坑点,助您写出健壮、高效、可维护的时间处理代码

⚡ java 日历类体系概览

在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的隐式边界处理易引发认知偏差。

java 日历类的不可忽视缺陷

  • 可变性:所有Calendar实例均可变,多线程环境下需手动同步,易导致状态污染
  • 月份偏移:0基月份(0=一月)违反直觉,是历史遗留错误
  • 时区处理笨拙:需显式调用setTimeZone(),且getTimeZone()返回TimeZone对象可变
  • 格式化线程不安全:SimpleDateFormat非线程安全,单例需加锁或用ThreadLocal
  • API冗余:set/add/roll语义模糊,组合操作复杂

Java官方明确建议:自JDK 8起,优先使用java.time包处理日期时间;Calendar仅作为兼容性兜底方案。

🚀 JDK 8+ java 日历类新标准:java.time包

java 日历类体系在JDK 8中迎来革命性重构。JSR-310规范以java.time包为核心,提供了一套不可变、线程安全、领域驱动的日期时间API,彻底解决了旧版设计缺陷。

〈 LocalDate 〉

表示无时区的日期(如生日、节假日),支持日期计算、比较、格式化。

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 〉

表示无时区的日期+时间(如活动开始时间),支持秒级精度。

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
日期+时间

〈 ZonedDateTime 〉

带时区的完整时间(如纽约会议、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包提供丰富的辅助类:

示例:计算本月最后一天的星期五:

LocalDate lastFriday = LocalDate.now()
    .with(TemporalAdjusters.lastInMonth(DayOfWeek.FRIDAY));
System.out.println(lastFriday); // 2026-03-27

此类链式调用使代码高度可读,显著优于Calendar的嵌套add/set。

📊 java 日历类:旧版 vs 新版核心差异

维度 Calendar(旧版) java.time(新版)
可变性 可变对象 不可变对象
月份索引 0基(0=一月) 1基(1=一月)
时区支持 需手动切换TimeZone 原生ZoneId/ZoneOffset
格式化器 SimpleDateFormat(非线程安全) DateTimeFormatter(线程安全)
夏令时处理 需手动判断 自动处理(如ZonedDateTime)
API链式调用 不支持 全面支持

何时用哪类?

  • 仅日期操作(如计算天数差):用LocalDate + Period
  • 业务时间(如订单创建时间):用LocalDateTime(服务器时区统一)
  • 跨时区应用(如国际会议安排):用ZonedDateTime + ZoneId
  • 需精确到纳秒(如金融交易):用OffsetDateTime或Instant
  • 旧系统兼容(如读取DB中java.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());

⚠️ java 日历类高频踩坑点与解决方案

坑点①:月份索引混淆

现象:用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

🔧 java 日历类实用工具类推荐

〔 日期工具类 〕

Apache Commons Lang的DateUtils提供便捷操作:

  • DateUtils.addDays(date, 7)
  • DateUtils.truncate(date, Calendar.DAY)
  • DateUtils.isSameDay(date1, date2)

但需注意其仍基于java.util.Date,存在旧版缺陷。

〈 Joda-Time 〉

JDK 8前最流行的第三方库,其设计直接影响java.time。支持:

  • 不可变时间类(LocalDate、DateTime)
  • 时区计算、夏令时处理
  • 格式化器线程安全

⚠️ 官方建议:JDK 8+应优先用java.time,而非Joda-Time。

〈 Hutool 〕

国产工具包,封装java.time为易用API:

DateUtil.now(); // 当前时间字符串
DateUtil.date(); // LocalDate对象
DateUtil.range(DateEnum.DAY, start, end); // 日期范围

适合快速开发,但需引入额外依赖。

❓ java 日历类常见问题(FAQ)

Q1:为何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
Q2:如何计算两个日期间的天数?

旧版:long diff = (date2.getTime() - date1.getTime()) / (1000 * 60 * 60 * 24);(可能因夏令时误差)

新版:long days = ChronoUnit.DAYS.between(date1, date2);(精确)

Q3:如何获取本周一的日期?
LocalDate today = LocalDate.now();
LocalDate monday = today.with(TemporalAdjusters.previousOrSame(DayOfWeek.MONDAY));
Q4:如何处理UTC时间戳?

用Instant表示时间点:

Instant now = Instant.now();
ZonedDateTime utc = now.atZone(ZoneId.of("UTC"));
ZonedDateTime local = now.atZone(ZoneId.systemDefault());