编辑“︁Java Duration”︁

{{Note|本节内容基于Java 8+的日期时间API}}

= Java Duration =

'''Duration'''是Java日期时间API（java.time包）中表示'''时间量'''或'''时间跨度'''的核心类，用于精确测量两个时间点之间的间隔（以秒和纳秒为单位）。与[[Period]]不同，Duration适合处理机器时间（如纳秒、秒），而非人类时间单位（如年、月）。

== 核心特性 ==
* 测量基于时间的时间量（小时、分钟、秒、纳秒）
* 不可变且线程安全
* 最大存储范围：±146年（±10<sup>18</sup>纳秒）
* 精度可达纳秒级
* 实现{{code|TemporalAmount}}接口

== 创建Duration对象 ==

=== 工厂方法 ===
{| class="wikitable"
! 方法 !! 描述
|-
| {{code|Duration.ofDays(long)}} || 创建指定天数的Duration（转换为秒）
|-
| {{code|Duration.ofHours(long)}} || 创建指定小时的Duration
|-
| {{code|Duration.ofMinutes(long)}} || 创建指定分钟的Duration
|-
| {{code|Duration.ofSeconds(long)}} || 创建指定秒的Duration
|-
| {{code|Duration.ofMillis(long)}} || 创建指定毫秒的Duration
|-
| {{code|Duration.ofNanos(long)}} || 创建指定纳秒的Duration
|}

<syntaxhighlight lang="java">
// 创建2小时的Duration
Duration twoHours = Duration.ofHours(2);
System.out.println(twoHours); // 输出: PT2H

// 创建1500毫秒的Duration
Duration msDuration = Duration.ofMillis(1500);
System.out.println(msDuration); // 输出: PT1.5S
</syntaxhighlight>

=== 时间差计算 ===
通过{{code|between}}方法计算两个时间点的间隔：

<syntaxhighlight lang="java">
Instant start = Instant.now();
// 模拟耗时操作
Thread.sleep(1500);
Instant end = Instant.now();

Duration elapsed = Duration.between(start, end);
System.out.println("操作耗时: " + elapsed.toMillis() + "ms");
// 输出示例: 操作耗时: 1502ms
</syntaxhighlight>

== 常用操作 ==

=== 时间单位获取 ===
{| class="wikitable"
! 方法 !! 返回类型 !! 描述
|-
| {{code|toDays()}} | long | 总天数（24小时为1天）
|-
| {{code|toHours()}} | long | 总小时数
|-
| {{code|toMinutes()}} | long | 总分钟数
|-
| {{code|getSeconds()}} | long | 秒数部分
|-
| {{code|getNano()}} | int | 纳秒部分（0-999,999,999）
|}

=== 数学运算 ===
Duration支持链式调用进行时间计算：

<syntaxhighlight lang="java">
Duration duration = Duration.ofMinutes(30)
    .plusSeconds(15)    // 加15秒
    .minusMillis(500);  // 减500毫秒

System.out.println(duration); // 输出: PT30M14.5S
</syntaxhighlight>

=== 比较操作 ===
<mermaid>
flowchart TD
    A[比较两个Duration] --> B[isZero]
    A --> C[isNegative]
    A --> D[compareTo]
</mermaid>

<syntaxhighlight lang="java">
Duration d1 = Duration.ofSeconds(10);
Duration d2 = Duration.ofMinutes(1);

System.out.println(d1.compareTo(d2)); // 输出: -1 (小于)
System.out.println(d1.isNegative());  // 输出: false
</syntaxhighlight>

== 实际应用案例 ==

=== 性能测量 ===
<syntaxhighlight lang="java">
Instant processStart = Instant.now();
// 执行数据库查询
List<Record> records = database.query(...);
Instant processEnd = Instant.now();

Duration queryTime = Duration.between(processStart, processEnd);
if (queryTime.toSeconds() > 5) {
    logger.warn("慢查询警告: 耗时 {} 毫秒", queryTime.toMillis());
}
</syntaxhighlight>

=== 定时任务控制 ===
<syntaxhighlight lang="java">
Duration timeout = Duration.ofSeconds(30);
Instant deadline = Instant.now().plus(timeout);

while (conditionNotMet()) {
    if (Instant.now().isAfter(deadline)) {
        throw new TimeoutException("操作超时");
    }
    // 继续尝试...
}
</syntaxhighlight>

== 时间单位转换 ==
Duration内部使用秒和纳秒存储，但提供多种单位转换：

<math>
\text{总秒数} = \text{seconds} + \frac{\text{nanos}}{10^9}
</math>

<syntaxhighlight lang="java">
Duration complex = Duration.ofSeconds(3675, 800_000_000); // 1小时1分15.8秒

System.out.println(complex.toHoursPart());   // 1 (小时部分)
System.out.println(complex.toMinutesPart()); // 1 (分钟部分)
System.out.println(complex.toSecondsPart()); // 15 (秒部分)
</syntaxhighlight>

== 注意事项 ==
* 不要将Duration用于日期计算（应使用[[Period]]）
* 跨越夏令时转换时，Duration仍保持精确的物理时间
* 序列化格式符合ISO-8601持续时间格式（如{{code|PT8H30M}}）

{{Tip|在Java 9+中，Duration新增了{{code|to...Part}}方法（如{{code|toHoursPart}}），这些方法只返回指定单位的部分值，而非总累计值。}}

== 参见 ==
* [[Java Period]]
* [[Java Instant]]
* [[Java 日期时间API概览]]

[[Category:编程语言]]
[[Category:Java]]
[[Category:Java日期时间api]]