概述

在 Java 8 引入的新时间 API 中，java.time.Duration 是专门用于处理基于时间的时间量的主要类。它提供了纳秒级别的精度、不可变且线程安全的特性，还有丰富的算术和转换方法。

常见痛点：

• 在混用 Duration 与 Period 时容易产生错误，导致日期计算不准确。
• 跨时区计算时忽略了时区信息，出现意外偏差。
• 大数值运算可能导致溢出或精度丢失。
• API 使用不当导致代码可读性差，例如直接使用毫秒构造而不明确单位。

主要特性

✅ Duration 的自己的优势

• 纳秒级精度支持最高纳秒粒度的时间测量。说起来，
• 不可变&线程安全所有实例都是 immutable。天然适用于并发环境，不过，
• 流畅 API 设计链式调用让代码更简洁直观。
• 单位转换便捷提供多种 .toXxx/.ofXxx 方法。
• ISO‑8601 标准兼容可以直接解析/格式化符合标准的字符串。

创建 Duration 实例

. 静态工厂方法

// 基本单位创建
Duration d30s = Duration.ofSeconds;// 30 秒
Duration d15m = Duration.ofMinutes;// 15 分钟
Duration d2h = Duration.ofHours;// 2 小时
Duration d500ms = Duration.ofMillis;// 500 毫秒
Duration d1ns = Duration.ofNanos;// 1 毫秒
// 组合创建
Duration complex = Duration.ofHours
.plusMinutes
.plusSeconds;// 1 小时 30 分钟 45 秒

. 时间点差值计算

// 基于 Instant
Instant start = Instant.now;Thread.sleep;Instant end = Instant.now;说起来，Duration elapsed = Duration.娱乐ween;说起来，// 基于 LocalDateTime
LocalDateTime meetingStart = LocalDateTime.of;LocalDateTime meetingEnd = LocalDateTime.of;Duration meetingDuration = Duration.娱乐ween;// 基于 LocalTime
LocalTime workStart = LocalTime.of;LocalTime workEnd = LocalTime.of;老实说，Duration workDuration = Duration.娱乐ween;

. 字符串解析——解决“手写字符串易出错”痛点

Duration pt20s = Duration.parse;// 20 秒
Duration pt15m = Duration.parse;// 15 分钟
Duration pt10h = Duration.parse;// 10 小时
Duration p2d = Duration.parse;话说回来，// 2 天
Duration pt1h30m= Duration.parse;// 1 小时30分钟

主要操作教程

🔢 时间值获取与转换

Duration d = Duration.ofHours.plusMinutes;// 2 小时30 分钟
// 转换为不同单位
long totalHours = d.toHours;// → 2
long totalMinutes = d.toMinutes;// →150
long totalSeconds = d.toSeconds;// →9_000
long totalMillis = d.toMillis;// →9_000_000
// 获取各部分
long hoursPart = d.toHoursPart;// →2
long minutesPart = d.toMinutesPart;// →30
long secondsPart = d.toSecondsPart;// →0
long nanosPart = d.toNanosPart;// →0

➕ 数学运算操作

Duration base = Duration.ofHours;// 加法 & 减法
Duration afterAdd = base.plusHours.plusMinutes.plusSeconds;Duration afterSubtract= base.minusMinutes;// 缩放——注意除以零会抛异常
Duration doubled = base.multipliedBy;Duration halved = base.dividedBy;// 正负号处理
Duration negative = Duration.ofHours;Duration absolute = negative.abs;// →5 小时正数

⚖️ 比较与判断

Duration shortTask= Duration.ofMinutes;Duration longTask = Duration.ofHours;boolean isShorter = shortTask.compareTo <0;   // true
boolean isZero       = shortTask.isZero;                  // false
boolean isNegative   = shortTask.isNegative;              // false
boolean equal         = shortTask.equals); // true

实战使用场景 & 痛点对策

🎯 场景1：性能监控与执行时间测量 🛑 痛点：手动记录起止时间容易遗漏异常方法导致统计不完整。

public class PerformanceMonitor {
public static  T measureExecution(String taskName,Supplier task) {
Instant start = Instant.now;其实，try {
T result = task.get;log，按理说，return result;} catch {
log",start);throw e，}
}
private static void log {
Instant end = Instant.now;Duration elapsed= Duration.娱乐ween;System.out.printf("任务 '%s' 执行时间: %d 毫秒%n"。name,elapsed.toMillis);}
public static void main {
String r= measureExecution -> {
try { Thread.sleep;} catch {}
return "查询结果";})，}
}

🎯 场景2：超时控制与限流管理 🛑 痛点：失误”。不过，

public class TimeoutManager {
private final Duration timeout;private final Duration retryInterval;public TimeoutManager(Duration timeout,Duration retryInterval) {
this.timeout = timeout;this.retryInterval= retryInterval;}
public  T executeWithTimeout
throws TimeoutException {
Instant deadline= Instant.now.plus;while .isBefore) {
try { return task.call;}
catch {
if .isAfter)
throw new TimeoutException;long waitMs=Math.min。Duration.娱乐ween(
Instant.now,deadline)
.toMillis);try { Thread.sleep;}
catch {
Thread.currentThread.interrupt;
throw new RuntimeException;}
}
}
throw new TimeoutException;}
}
// 使用示例：
TimeoutManager manager=new TimeoutManager(
Duration.ofSeconds,// 超时时间
Duration.ofSeconds);// 重试间隔
// manager.executeWithTimeout -> ... );

🎯 场景3：缓存过期策略实现 🛑 痛点：错误」。

public class TimedCache {
private final Map cache=new ConcurrentHashMap<>;private final Duration defaultTtl;public TimedCache { this.defaultTtl=defaultTtl;}
public void put{ put;怎么说呢，}
public void put{
Instant expiry=Instant.now.plus;cache.put)，}
public V get{
CacheEntry entry=cache.get;if return null;if.isAfter){
cache.remove;return null，老实说，}
return entry.value;}
/** 定期清理，可交给后台线程执行 */
public void cleanup{
Instant now=Instant.now;cache.entrySet.removeIf.expiry));}
private static class CacheEntry{
final V value;final Instant expiry;话说回来，CacheEntry{ this.value=v;this.expiry=e;}
}
}

🎯 场景4：任务调度与延迟执行 🛑 痛点：使用旧版 Date/TimerTask** 会出现线程安全和精度问题。

public class TaskScheduler {
private final ScheduledExecutorService scheduler=
Executors.newScheduledThreadPool.availableProcessors);public ScheduledFuture scheduleWithFixedDelay(Runnable task,Duration initialDelay。Duration delay){
return scheduler.scheduleWithFixedDelay(task,initialDelay.toMillis,delay.toMillis,TimeUnit.MILLISECONDS);}
public ScheduledFuture scheduleAtFixedRate(Runnable task,Dimension initialDelay。Dimension period){
return scheduler.scheduleAtFixedRate(task,initialDelay.toMillis,period.toMillis,TimeUnit.MILLISECONDS);}
/** 示例：每隔30秒执行一次健康检查 */
public void startMonitoring{
scheduleAtFixedRate(this::healthCheck。Duration.ofSeconds,Duration.ofSeconds);}
private void healthCheck{
System.out.println);}
}

🎯 场景5：速率限制器实现 🛑 痛点：自己写计数器往往忘记「令牌补充」的边界检查，导致突发流量突破限制。

public class RateLimiter {
private final Duration refillInterval;private final int maxTokens;private int tokens;private Instant lastRefill;public RateLimiter{
this.refillInterval=refillInterval;this.maxTokens=maxTokens;this.tokens=maxTokens;this.lastRefill=Instant.now;}
/** 尝试获取一个令牌 */
public synchronized boolean tryAcquire{
refillTokens;说起来，if{
tokens--;话说回来，return true;话说回来，}
return false;}
/** 尝试获取 n 个令牌 */
public synchronized boolean tryAcquire{
refillTokens;if{
tokens -= permits;话说回来，return true;其实，}
return false;}
/** 补充令牌 */
private void refillTokens{
Instant now=Instant.now;long intervals=
Duration.娱乐ween.dividedBy;if{
tokens=Math.min(maxTokens,tokens+intervals);lastRefill=lastRefill.plus);}
}
/** 距离下次补充还有多少时间 */
public Duration getTimeUntilNextRefill{
return Duration.娱乐ween(
Instant.now,lastRefill.plus);}
}
// 示例：
RateLimiter limiter=new RateLimiter,10);if){
System.out.println;}else{
System.out.println.toMillis+" ms");}

常用方法与注意事项 ✅⚠️

✅ 常用方法

• #语义化变量名： `requestTimeout`、`cacheTtl`、`sessionLength` 等，让阅读者一眼看出含义。
• #优先使用工厂方法： `Duration.ofMinutes` 而非构造函数，以免产生歧义。
• #合理拆分大数值： If you need years，请先转为 {@link java.time.Period}。再配合 {@link java.time.Duration}.
• #选取合适精度： 
  • Nano 精度仅在计时器/性能分析需要；普通业务推荐毫秒级，
• #统一异常处理： Avoid swallowing InterruptedException；保持线程中断状态，

⚠️ 注意事项

• #不要在日期层面使用 Date/Calendar/Period混用:

  
  LocalDate today = LocalDate.now;LocalDate nextMonth = today.plusMonths;// ✅ 正确，用 Period 或 plusMonths
  LocalDate wrong =
  today.plus);// ❌ 潜在跨月错误，建议改为 Period。<\/codе>

• #跨时区计算要用带有 Zone 信息的类：

  
  ZonedDateTime zStart=ZonedDateTime.now;ZonedDateTime zEnd
  =&zStart.plus);// ✅ 正确保留 Zone 信息。<\/codе>

• #大数值可能溢出：

  
  try{
  Duration huge=Duration.ofDays;话说回来，long days =huge.toDays;// ⚠️ May overflow.
  }catch{
  // 捕获并处理溢出情况。}
  <\/codе>

• #避免在循环中频繁创建大量临时对象： 使用单例或缓存已解析好的 {@link java.time.Duration},如配置文件中的超时时间可以提前解析一次再复用。按理说，
• #谨慎使用负数 duration：负数会影响比较和加减运算。需要显式调用 .abs 转为正值后再做业务判断。

​《Java Durаtion》​ 在以下场景中是首选工具 ：

• ✅ 高精度计时
• ✅ 超時控制 与 限流
• ✅ 缓存 与 会话 TTL
• ✅ 任务调度 与 延迟执行
• ✅ 速率限制

掌握上述技巧后你将能够轻松应对各种时间敏感业务需求，让程序既可靠又高效。