📋 目录
一、工具类功能
给一段逻辑按阶段打点,收尾拿到每个阶段的耗时、占比与总耗时,回答「这次请求的时间花在哪了」,时间基准是 System.nanoTime() 的单调时钟。
二、所需环境
JDK 17或以上
三、方法与调用示例(按需调用)
🔢 方法序号:1
🎯 方法用途:
- 造一个名称为 stopwatch 的匿名秒表,不自动开始计时,临时给一段逻辑打点用它
- 报告首行显示的就是这个名字,想要业务含义就换具名入口
🧩 方法定义:public static StopWatch create()
🗣️ 入参解释:public static StopWatch create()(无入参)
📤 返回值解释:StopWatch,未开始的秒表实例
💡 边界口径:
- 没有名称校验,名称写死在方法里
- 未 start 时取数不抛异常:isRunning 为 false,totalNanos 为 0
- 实例非线程安全,一个实例在单个线程内用完
🧪 方法示例:
create().name()拿到stopwatch- 没 start 的秒表
isRunning()拿到false - 同一实例的
totalNanos()拿到0
🔢 方法序号:2
🎯 方法用途:
- 造一个带业务名称的秒表,报告里显示它,同样不自动计时
- 一个进程里同时埋多处点时,具名能把报告区分开
🧩 方法定义:public static StopWatch create(String name)
🗣️ 入参解释:public static StopWatch create(秒表名称)
📤 返回值解释:StopWatch,未开始的具名秒表
💡 边界口径:
- 名称为 null 或空白抛
IllegalArgumentException - 创建完阶段数为 0,要自己调
start - 名称此后不可改
🧪 方法示例:
create("只做长度统计").name()拿到只做长度统计- 具名秒表没 start 时
stageCount()拿到0 create(null)抛秒表名称不能为null或空白- 名称给一串空白同样抛
秒表名称不能为null或空白
🔢 方法序号:3
🎯 方法用途:
- 建秒表并立刻进入以同名命名的第一个阶段,是最省事的推荐写法
- 配合 try-with-resources 使用,异常路径也能保证收尾
🧩 方法定义:public static StopWatch watch(String name)
🗣️ 入参解释:public static StopWatch watch(秒表名称)
📤 返回值解释:StopWatch,已在计时的秒表
💡 边界口径:
- 名称同时作为第一个阶段名
- 名称校验与
create(name)一致 - 后续的
start与split都会在切换时结算上一阶段
🧪 方法示例:
watch("下单链路")起表,依次start("风控")、split("落库")后stop()拿到27851700- 同一个总数交给
formatNanos拿到27.852ms - 秒表名与首阶段同名,
order.name()拿到下单链路
🔢 方法序号:4
🎯 方法用途:
- 把纳秒数按量级自动格式化成带单位的可读串,最多三位小数
- 给人看的耗时一律用它,日志采集与告警解析也按这个格式写规则
🧩 方法定义:public static String formatNanos(long nanos)
🗣️ 入参解释:public static String formatNanos(纳秒数)
📤 返回值解释:String,形如 12.345ms 的串,单位在 ns、微秒、ms、s 四档里自动选
💡 边界口径:
- 四舍五入后达到上一量级就进位,不会出现
1000.000ms这种该进位没进位的写法 - 刻意不用
String.format:它在每请求打点的热点路径上慢一个数量级,还会按默认语言环境把小数点写成逗号,把按句点解析的采集规则一起带崩 - 小数点固定是句点,输出与默认语言环境无关
- 纳秒数为负抛
IllegalArgumentException
🧪 方法示例:
formatNanos(1L)拿到1nsformatNanos(1_500L)拿到1.500μsformatNanos(1_234_567L)拿到1.235msformatNanos(1_234_567_890L)拿到1.235sformatNanos(999_999L)四舍五入后跨档进位,拿到1.000msformatNanos(999_999_999L)拿到1.000s- 把
formatNanos(1_234_567L)与写死的1.235ms比对,拿到true formatNanos(-1L)抛纳秒数不能小于0,当前为-1
🔢 方法序号:5
🎯 方法用途:
- 把纳秒换算成微秒数值,供指标上报或继续参与计算
- 要的是数字而不是字符串时用,给人看仍交给
formatNanos
🧩 方法定义:public static double toMicros(long nanos)
🗣️ 入参解释:public static double toMicros(纳秒数)
📤 返回值解释:double,微秒数,保留小数不截断
💡 边界口径:
- 按每微秒 1000 纳秒相除,不做取整
- 纳秒数为负抛
IllegalArgumentException
🧪 方法示例:
toMicros(1_500_000L)拿到1500.0
🔢 方法序号:6
🎯 方法用途:
- 把纳秒换算成毫秒数值,给监控埋点填数用
🧩 方法定义:public static double toMillis(long nanos)
🗣️ 入参解释:public static double toMillis(纳秒数)
📤 返回值解释:double,毫秒数
💡 边界口径:
- 按每毫秒 1000000 纳秒相除,不做取整
- 纳秒数为负抛
IllegalArgumentException
🧪 方法示例:
toMillis(1_500_000L)拿到1.5
🔢 方法序号:7
🎯 方法用途:
- 把纳秒换算成秒数值,长耗时任务统计吞吐时用
🧩 方法定义:public static double toSeconds(long nanos)
🗣️ 入参解释:public static double toSeconds(纳秒数)
📤 返回值解释:double,秒数
💡 边界口径:
- 按每秒 10 亿纳秒相除
- 纳秒数为负抛
IllegalArgumentException,三个换算入口同一口径
🧪 方法示例:
toSeconds(1_500_000L)拿到0.0015toSeconds(-5L)抛纳秒数不能小于0,当前为-5
🔢 方法序号:8
🎯 方法用途:
- 开一个新阶段;上一个阶段还在跑就先把它结算掉
- 一段逻辑一个阶段地往下打点时用,同名阶段会累加成同一条目
🧩 方法定义:public StopWatch start(String label)
🗣️ 入参解释:public StopWatch start(阶段名)
📤 返回值解释:StopWatch,返回自身便于链式写法
💡 边界口径:
- 阶段名为 null 或空白抛
IllegalArgumentException - 秒表已
stop再start抛IllegalStateException,要重跑先reset - 同名阶段按累加合并,
rpc打两次只会有一条rpc记录
🧪 方法示例:
retry.start("rpc").start("db").start("rpc")收尾后stageCount()拿到2- 两段 rpc 合并后的累计纳秒
stageNanos("rpc")拿到1100 start(" ")抛阶段名称不能为null或空白
🔢 方法序号:9
🎯 方法用途:
- 结算当前阶段并立刻开启下一阶段,一个调用完成切换
- 链路里连续换段时用,不用先 stop 再 start
🧩 方法定义:public StopWatch split(String nextLabel)
🗣️ 入参解释:public StopWatch split(下一阶段名)
📤 返回值解释:StopWatch,返回自身
💡 边界口径:
- 没
start过或已stop时抛IllegalStateException - 名称校验与
start一致 - 切换时结算的是上一阶段的耗时,与
start同一口径
🧪 方法示例:
watch("下单链路")起表后start("风控")、split("落库"),阶段顺序拿到[下单链路, 风控, 落库]- 没 start 就 split 抛
秒表尚未start
🔢 方法序号:10
🎯 方法用途:
- 结算当前阶段并停止计时,返回全部阶段的累计纳秒
- 一次请求结束时收口,把总数写进日志或埋点
🧩 方法定义:public long stop()
🗣️ 入参解释:public long stop()(无入参)
📤 返回值解释:long,全部阶段的累计纳秒
💡 边界口径:
- 没
start或重复stop都抛IllegalStateException - 收尾后
isRunning()为 false,正在跑的阶段被结算进来 - 要同一实例再跑一轮,先
reset
🧪 方法示例:
order.stop()三段跑完拿到27851700- 收尾后
isRunning()拿到false - 对已收尾的秒表再
stop()一次,检查是否抛IllegalStateException,拿到true - 没 start 就 stop 抛
秒表尚未start
🔢 方法序号:11
🎯 方法用途:
- 幂等收尾,让秒表能直接放进 try-with-resources,异常路径也不会漏掉结算
- 与显式
stop()共存,谁先到谁生效
🧩 方法定义:public void close()
🗣️ 入参解释:public void close()(无入参)
📤 返回值解释:void,仍在计时就结算并停止,否则什么都不做
💡 边界口径:
- 没
start过就 close 不抛异常,这是它与stop、split最大的差别 - 已
stop再 close 也不抛,直接跳过 - 实例实现了
AutoCloseable;想把结果带到块外,就把变量声明在 try 之外再写成 try 资源
🧪 方法示例:
- 把秒表声明在 try 之外写成 try-with-resources,出了块
isRunning()拿到false - 同一个秒表的
stageCount()拿到2 - 出块后总耗时是否仍大于 0,拿到
true - close 与显式 stop 共存是否安静无事,拿到
true - 还没 start 的秒表直接 close,拿到
true
🔢 方法序号:12
🎯 方法用途:
- 清空全部统计回到未开始状态,同一个实例反复跑基准
- 循环压测里每轮都要干净计数时用,省得重建实例
🧩 方法定义:public StopWatch reset()
🗣️ 入参解释:public StopWatch reset()(无入参)
📤 返回值解释:StopWatch,返回自身
💡 边界口径:
- 阶段表、当前阶段、累计总耗时、停止标记一起清掉
- reset 之后可以重新
start,不必新建实例
🧪 方法示例:
bench.reset()之后stageCount()拿到0- 同一个实例的
totalNanos()拿到0 - 同一个实例的
isRunning()拿到false - reset 前第一轮的
totalNanos()拿到3619600 - reset 后第二轮跑完的
totalNanos()拿到3300600
🔢 方法序号:13
🎯 方法用途:
- 取秒表名称,报告首行用的就是它
🧩 方法定义:public String name()
🗣️ 入参解释:public String name()(无入参)
📤 返回值解释:String,创建时定下的名称
💡 边界口径:
- 名称创建后不可改
- 匿名入口固定给
stopwatch,具名入口才做空白校验
🧪 方法示例:
order.name()拿到下单链路create().name()拿到stopwatch
🔢 方法序号:14
🎯 方法用途:
- 判秒表当前是否正处在某个阶段里计时
🧩 方法定义:public boolean isRunning()
🗣️ 入参解释:public boolean isRunning()(无入参)
📤 返回值解释:boolean,计时中为 true
💡 边界口径:
- 没 start、已 stop、已 close 都是
false - 为
true时正在跑的阶段还没结算,但已用时间计入总耗时
🧪 方法示例:
running.isRunning()计时中拿到true- 收尾后拿到
false reset()之后拿到false
🔢 方法序号:15
🎯 方法用途:
- 取已结算的阶段条目数,同名阶段算一条
🧩 方法定义:public int stageCount()
🗣️ 入参解释:public int stageCount()(无入参)
📤 返回值解释:int,已记录的阶段数
💡 边界口径:
- 正在跑、尚未结算的阶段不计入,
stop、split或下一次start之后才算 - 同名阶段合并,条目数少于打点次数
reset之后归零
🧪 方法示例:
- 三段收尾后
stageCount()拿到3 - 还在跑第一个阶段时拿到
0 - 对该阶段调用
stop之后同一阶段被结算进来,拿到1 - rpc 打两次、db 打一次时拿到
2
🔢 方法序号:16
🎯 方法用途:
- 取阶段名到纳秒的有序 Map 副本,顺序按阶段首次出现
- 要自己算占比、或者把各阶段耗时交给别的组件时用这一份
🧩 方法定义:public Map<String, Long> stageNanos()
🗣️ 入参解释:public Map<String, Long> stageNanos()(无入参)
📤 返回值解释:Map<String, Long>,阶段名到累计纳秒的有序副本
💡 边界口径:
- 返回的是新建的
LinkedHashMap,改了不影响秒表内部 - 正在跑的阶段还没进来,计时中途取到的是空表
- 同名阶段已合并成一项
🧪 方法示例:
order.stageNanos().keySet()拿到[下单链路, 风控, 落库]- 还在跑的秒表取副本,配套的阶段数拿到
0
🔢 方法序号:17
🎯 方法用途:
- 查单个阶段的累计纳秒
🧩 方法定义:public Long stageNanos(String label)
🗣️ 入参解释:public Long stageNanos(阶段名)
📤 返回值解释:Long,该阶段累计纳秒;没记录过返回 null
💡 边界口径:
- 正在跑、还没结算的阶段同样查不到,返回
null - 入参为 null 直接返回
null,不抛异常 - 同名阶段返回的是累加后的值
🧪 方法示例:
order.stageNanos("风控")拿到13653000- 查一个没打点过的阶段名拿到
null - 秒表还在跑时查当前阶段拿到
null
🔢 方法序号:18
🎯 方法用途:
- 把各阶段耗时换算成指定单位的 Map,方便和日志、监控的单位对齐
🧩 方法定义:public Map<String, Long> stages(TimeUnit unit)
🗣️ 入参解释:public Map<String, Long> stages(时间单位)
📤 返回值解释:Map<String, Long>,阶段名到耗时数值的有序副本
💡 边界口径:
- 换算走
TimeUnit.convert,整除截断,不足 1 毫秒的阶段在毫秒视图里是0 - 单位传 null 抛
IllegalArgumentException - 顺序与
stageNanos()一致
🧪 方法示例:
order.stages(TimeUnit.MILLISECONDS)拿到{下单链路=5, 风控=13, 落库=8}- 换成微秒视图后,风控一行的数值比毫秒视图大,拿到
true - 单位传 null 抛
时间单位不能为null
🔢 方法序号:19
🎯 方法用途:
- 取总耗时纳秒;仍在计时时含当前阶段已用的时间
- 中途想瞄一眼已经花了多少时间也可以用,不用等收尾
🧩 方法定义:public long totalNanos()
🗣️ 入参解释:public long totalNanos()(无入参)
📤 返回值解释:long,累计纳秒数
💡 边界口径:
- 收尾后等于各阶段之和
- 未收尾时是「已结算阶段加当前阶段已用」,正在跑的阶段虽没进阶段表,时间照样计入
- 取数不抛异常
🧪 方法示例:
order.totalNanos()与order.stageNanos()各值之和比对,拿到true- 还在计时的秒表,
totalNanos()是否已越过 5 毫秒这条线,拿到true - 出块之后总耗时仍大于 0,拿到
true - 没 start 的秒表拿到
0
🔢 方法序号:20
🎯 方法用途:
- 把总耗时按指定单位给出来,只要一个数的场合用它
🧩 方法定义:public long total(TimeUnit unit)
🗣️ 入参解释:public long total(时间单位)
📤 返回值解释:long,换算后的总耗时
💡 边界口径:
- 内部就是
totalNanos()再按单位整除截断,计时中同样可取 - 单位传 null 抛
IllegalArgumentException
🧪 方法示例:
order.total(TimeUnit.MILLISECONDS)拿到27
🔢 方法序号:21
🎯 方法用途:
- 生成可读报告:总耗时一行,各阶段耗时与占比各一行
- 排查「时间到底花在哪了」时直接把返回值整段打日志
🧩 方法定义:public String prettyPrint()
🗣️ 入参解释:public String prettyPrint()(无入参)
📤 返回值解释:String,多行文本,行分隔取系统换行符
💡 边界口径:
- 每行的量级由
formatNanos自动选,占比四舍五入成整数百分比 - 总耗时只取一次快照,首行总数与各行占比的分母是同一个值
- 收尾之后再取:还在跑时报告只有总耗时和一行
(no stage recorded)提示 - 阶段行按首次出现顺序排列
🧪 方法示例:
order.prettyPrint()的首行拿到StopWatch[下单链路] total=27.852ms- 报告里包含风控那一行
风控 : 13.653ms (49%) - 检查报告里是否有
落库这一行,拿到true - 检查报告里是否带占比列,拿到
true - 还在计时的秒表,报告里是否只有提示行
no stage recorded,拿到true
四、工具类源码(可直接复制)
📦 源码文件