System.nanoTime() 是 JVM 提供的纳秒级单调计时器，其返回值仅保证单个 JVM 进程内严格递增（不回拨、不跳跃），但不可用于表示绝对时间，也不跨进程/重启可比；它天然免疫 NTP 校准、手动调时等系统时钟扰动。
`system.nanotime()` 是 jvm 提供的纳秒级单调计时器，其返回值仅保证单个 jvm 进程内严格递增（不回拨、不跳跃），但不可用于表示绝对时间，也不跨进程/重启可比；它天然免疫 ntp 校准、手动调时等系统时钟扰动。
在高并发、低延迟或分布式系统开发中，精准、稳定的时间测量是超时控制、性能分析、ID 生成等关键逻辑的基础。而 System.currentTimeMillis() 作为“墙上时钟”（wall-clock time），虽语义清晰（自 Unix 纪元起的毫秒数），却极易受系统时钟干预影响：NTP 同步可能造成毫秒级甚至秒级回拨或前跳，运维误操作手动改时更会导致严重逻辑异常（如定时任务批量触发、会话提前过期）。此时，System.nanoTime() 成为不可替代的底层计时基石。
✅ 单调性：只进不退，但有边界条件
System.nanoTime() 的核心特性是单调递增（monotonic）——它基于硬件高精度计数器（如 x86 的 TSC、Linux 的 CLOCK_MONOTONIC），由 JVM 在启动时选定一个未公开的起始原点（origin），此后值持续累加，不受系统时间重置、NTP 调整、闰秒插入等任何外部干预影响。这意味着：
- ✅ 在同一 JVM 生命周期内，nanoTime() 永远不会“回拨”（leap backward）或“突跳”（leap forward）；
- ✅ t2 - t1（两次调用差值）恒为非负整数，且精确反映真实经过时间（分辨率通常为 1–15 微秒，远优于 currentTimeMillis() 的毫秒级抖动）；
- ❌ 但该值无全局意义：不同 JVM、不同机器、甚至同一机器重启后，nanoTime() 的数值不可比、不连续、不映射真实时间。
? 补充冷知识：nanoTime() 返回值可能为负数——并非错误，而是因 JVM 启动时原点被设在“未来”（如为对齐硬件周期），或 long 类型溢出（约 292 年后）。但这完全不影响差值计算的正确性。
java-api-doc-generator下载分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
⚠️ 常见误区与安全实践
| 场景 | 是否安全 | 说明 |
|---|---|---|
| 超时等待循环 | ✅ 推荐 | java long start = System.nanoTime(); int timeoutNs = 500_000_000; // 500ms while (!done && (System.nanoTime() - start) |
| 跨 JVM 时间比较 | ❌ 禁止 | nanoTime() 在不同进程间起点不同，直接比较无意义。需用 currentTimeMillis() 或分布式授时服务（如 NTP+PTP）对齐。 |
| 生成分布式 ID | ⚠️ 仅作辅助 | 不可替代毫秒时间戳，但可用作微秒级扰动因子：sequence = (int)(System.nanoTime() % 1_000_000)，配合 currentTimeMillis() 和原子计数器兜底。 |
| 记录日志时间戳 | ❌ 错误用途 | nanoTime() 值无法转换为可读时间，应使用 Instant.now() 或 System.currentTimeMillis()。 |
? 最佳实践建议
- 测耗时，必用 nanoTime()：性能压测、算法 benchmark、GC 暂停监控等场景，始终采用 start/end 差值模式；
- 做超时，禁用 currentTimeMillis()：网络请求、锁等待、异步回调等生命周期敏感逻辑，统一基于 nanoTime() 实现单调超时；
- 跨节点协调，回归墙钟：分布式事务、事件排序、审计日志等需全局时间语义的场景，必须依赖校准后的 currentTimeMillis() 或 Instant.now()，并主动容忍时钟漂移（如使用逻辑时钟、向量时钟补充）；
- 警惕虚拟化环境：在 VM suspend/resume、CPU 频率动态调整（如 Intel SpeedStep）等极端情况下，nanoTime() 可能短暂暂停（非回退），JDK 会尽力平滑，但高精度要求场景建议结合 Thread.onSpinWait() 或降级策略。
总之，System.nanoTime() 不是“更准的当前时间”，而是“最稳的流逝刻度”。理解其设计契约——单 JVM 内单调、差值即真理、绝对值无业务含义——是写出鲁棒、高性能 Java 时间敏感代码的第一课。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
