Java DateTimeFormatterBuilder.appendFraction 怎样控制时间小数位

如果你要控制 Java 时间字符串的小数位，优先使用 DateTimeFormatterBuilder.appendFraction，不要把纳秒字段当成普通整数直接拼接。最常用的组合是 ChronoField.NANO_OF_SECOND 配合 minWidth 和 maxWidth：两者都设为 3 就得到固定三位小数，设为 0 和 9 则允许按实际精度输出。需要特别注意，超过 maxWidth 的数字只会被截断，不会四舍五入。

官方参考：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/format/DateTimeFormatterBuilder.html

把小数位看成“秒字段的分数”：minWidth 决定最低位数，maxWidth 决定上限，decimalPoint 决定是否由格式器输出本地化小数点。格式化要固定几位就把最小值和最大值设成相同数字；解析外部输入则先明确 strict 还是 lenient。

1. 先把四个参数对应到输出行为

appendFraction(field, minWidth, maxWidth, decimalPoint) 的第一个参数必须是有效值范围固定的时间字段。对常见的 NANO_OF_SECOND 来说，字段值范围是 0 到 999999999，正好可以表达秒的小数部分。

当 decimalPoint 为 true 时，小数点由格式器负责；当 minWidth 为 0 时，零分数可以不输出任何内容。输出中的尾随零会被省略，但如果最小位数大于 0，格式器会补足到最小宽度。

2. 用 NANO_OF_SECOND 固定输出毫秒

日志或接口协议要求固定三位毫秒时，把最小和最大宽度都设为 3。下面的时间带有 123456789 纳秒，最终只保留前三位：

import java.time.LocalTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.temporal.ChronoField;

public class MillisFormatDemo {
    public static void main(String[] args) {
        DateTimeFormatter formatter = new DateTimeFormatterBuilder()
                .appendPattern("HH:mm:ss") // 先输出时分秒，避免把整数秒当成小数
                .appendFraction(ChronoField.NANO_OF_SECOND, 3, 3, true) // 固定三位并自动输出小数点
                .toFormatter();

        LocalTime time = LocalTime.of(9, 7, 5, 123_456_789);
        System.out.println(formatter.format(time)); // 预期为 09:07:05.123
    }
}

这里的 123 不是四舍五入结果，而是从纳秒分数中直接取出的前三位。如果业务需要四舍五入到毫秒，应先在时间值或业务数值层完成舍入，再交给格式器输出；不要把 appendFraction 当成舍入器。

3. 用可变宽度兼顾微秒和纳秒

展示型日志通常不希望出现多余的零，可以把宽度设为 0 到 9。格式器会在允许的范围内保留必要数字，并省略尾随零；非零分数为 0.123456789 时会完整输出，分数为 0.120000000 时不会强行输出九位。

DateTimeFormatter compactFormatter = new DateTimeFormatterBuilder()
        .appendPattern("HH:mm:ss") // 主体时间保持固定格式
        .appendFraction(ChronoField.NANO_OF_SECOND, 0, 9, true) // 允许没有小数，也允许到纳秒
        .toFormatter();

LocalTime first = LocalTime.of(9, 7, 5, 120_000_000);
LocalTime second = LocalTime.of(9, 7, 5, 123_456_789);
System.out.println(compactFormatter.format(first)); // 09:07:05.12
System.out.println(compactFormatter.format(second)); // 09:07:05.123456789

如果协议要求“有小数就必须带点”，将 decimalPoint 设为 true 更稳妥；如果小数点已经由前一个格式组件或固定字面量处理，则不要重复添加，否则会得到两个点或解析不一致。

4. 严格解析和宽松解析要分开看

格式化和解析共享同一组宽度参数，但含义不完全一样。默认解析是严格模式，输入的小数位数必须落在 minWidth 到 maxWidth 之间；例如设置为 3 到 6 时，.123 可以解析，.12 会被拒绝。调用 parseLenient() 后，最小位数按 0 处理，最大位数按 9 处理，适合输入来源不稳定但仍然只允许纳秒精度的场景。

DateTimeFormatter inputFormatter = new DateTimeFormatterBuilder()
        .appendPattern("HH:mm:ss") // 解析时先匹配时分秒
        .appendFraction(ChronoField.NANO_OF_SECOND, 3, 6, true) // 严格接受 3 到 6 位小数
        .toFormatter();

LocalTime parsed = LocalTime.parse("09:07:05.123456", inputFormatter); // 可以解析
// LocalTime.parse("09:07:05.12", inputFormatter); // 位数不足，严格模式会失败

DateTimeFormatter flexibleFormatter = new DateTimeFormatterBuilder()
        .appendPattern("HH:mm:ss") // 保持主体字段不变
        .parseLenient() // 后续分数字段允许 0 到 9 位
        .appendFraction(ChronoField.NANO_OF_SECOND, 3, 6, true)
        .toFormatter();

parseLenient() 不是“什么格式都接受”：它只放宽解析宽度和符号等规则，字段本身仍需是有效的时间分数。对固定协议，建议保留默认严格模式，让错误尽早暴露。

5. 记住三个边界再复用格式器

第一，minWidth 只能在 0 到 9 之间，maxWidth 在 1 到 9 之间，且最大值不能小于最小值；参数不合法会在构建格式器时抛出 IllegalArgumentException。第二，字段必须有固定的有效值集合，不能随意传入可变范围字段。第三，DateTimeFormatterBuilder 是可变构建器，完成 toFormatter() 后得到的格式器适合复用，构建过程本身不要跨线程共享。

实际项目可以按下面的选择落地：

• 接口固定毫秒：appendFraction(NANO_OF_SECOND, 3, 3, true)。
• 日志按需展示：appendFraction(NANO_OF_SECOND, 0, 9, true)。
• 外部协议校验：固定 minWidth/maxWidth，默认使用 strict 解析。

常见追问

appendFraction 会四舍五入吗？不会。达到最大位数后直接丢弃后面的数字，需要舍入时先处理时间值。

为什么输出里没有小数点？检查 decimalPoint 是否为 true，以及是否把小数部分放在了可选区段中；当最小宽度为 0 且分数为零时，整个小数部分可能不输出。