应根据业务需求选择period或duration:需考虑日历规则(如闰年、每月天数)用period,计算固定纳秒级跨度用duration;混用或类型不匹配会引发异常。

计算两个日期时间差,关键在于分清“期间”(Period)和“时长”(Duration)——前者关注日历意义上的变化(如“过了几个月几天”),后者关注精确的纳秒级跨度(如“总共多少小时、分钟”)。选错类型会导致结果不符合业务预期,比如跨月计算天数、闰年处理、时区偏移等都可能出错。
用 Period 算“日历差”:适合看年月日变化
Period 表示基于日历规则的年、月、日差异,会自动处理月份天数不均、闰年等。适用于“用户注册满3个月”“合同到期前2个月提醒”这类场景。
- 创建方式:用 Period.between(startDate, endDate),参数必须是 LocalDate、LocalDateTime 或 YearMonth(不能含时分秒精度差异)
- 注意:若传入 LocalDateTime,会先截断为 LocalDate(丢弃时间部分),所以想算“从今天9点到后天15点”这种带时间的周期差,Period 不适用
- 获取结果:调用 period.getYears()、period.getMonths()、period.getDays(),返回的是“净变化”,比如 2023-01-30 到 2023-03-02 得到 P0Y1M3D(1个月零3天)
用 Duration 算“精确时长”:适合算秒、毫秒、纳秒级跨度
Duration 表示两点之间固定的纳秒数,不关心日历,只做线性减法。适用于“任务执行耗时”“缓存过期倒计时”“API响应延迟统计”等。
- 创建方式:用 Duration.between(startInstant, endInstant) 或 Duration.between(startDateTime, endDateTime),推荐用 Instant(带时区信息,避免歧义)
- 注意:LocalDateTime 没有时区,跨夏令时或系统时区变更时可能出错;Instant 是时间轴上的绝对点,更安全
- 获取结果:用 duration.toMinutes()、duration.toHours()、duration.toMillis() 等;也可用 duration.toString() 得到 PT2H30M 格式(ISO-8601)
别混用!常见错误和规避方法
把 LocalDate 和 Instant 直接传给同一个方法、或用 Period 去减带时间的 LocalDateTime,都会抛 DateTimeException 或返回意外结果。
- 想算“2024-02-28 14:00 到 2024-03-03 10:00 的日历差?”→ 先提取日期部分用 Period,再单独算时间部分用 Duration,最后合并逻辑
- 想算“距离某个 UTC 时间还有多久?”→ 统一转成 Instant:zonedDateTime.toInstant(),再用 Duration.between(Instant.now(), target)
- 需要格式化输出(如“2天3小时”)?不要拼 Period + Duration 字符串,用 java.time.format.DateTimeFormatter 配合自定义逻辑,或借助第三方库如 Time4J
一句话总结选择逻辑
问自己:这个差值是否要随日历变动?比如“1个月”在1月是31天、2月可能只有28天——要,就用 Period;如果只是固定长度的时间跨度(比如定时任务每3600秒触发),就用 Duration。










