Java DateTimeFormatterBuilder 怎么兼容多种日期输入：parseBest、默认值与失败提示

接口里的日期字段经常不是一种格式：老客户端只传 2026-08-26，新客户端会补上时间，部分调用方还会带 +08:00。如果直接把所有输入交给 LocalDateTime.parse，日期-only 会失败；如果一上来就转成 OffsetDateTime，没有偏移量的请求又无法落地。DateTimeFormatterBuilder 配合可选片段和 parseBest，可以在一个解析入口里保留输入实际提供的精度。

先把三种输入边界说清楚

这个场景的关键不是“让格式越宽松越好”，而是把输入携带的信息分级。日期-only 只有日历日期；本地日期时间多了时分秒，但没有时区；偏移日期时间既有时间又明确告诉了偏移量。三者不能无条件互转，否则会在接口层悄悄丢掉信息。

用可选片段构造一个严格解析器

optionalStart() 和 optionalEnd() 让时间、秒和偏移量成为可选片段。下面的格式只接受 ISO 风格的数字日期，不把任意分隔符都吞掉；严格模式是默认行为，这里显式写出来是为了让意图更清楚。

private static final DateTimeFormatter INPUT_FORMATTER = new DateTimeFormatterBuilder()
        .parseCaseSensitive()
        .appendPattern("uuuu-MM-dd")
        .optionalStart()
        .appendLiteral('T')
        .appendPattern("HH:mm")
        .optionalStart()
        .appendPattern(":ss")
        .optionalEnd()
        .optionalEnd()
        .optionalStart()
        .appendOffsetId()
        .optionalEnd()
        .toFormatter(Locale.ROOT)
        .withResolverStyle(ResolverStyle.STRICT);

这里有一个容易忽略的边界：偏移量不能脱离时间单独出现。格式器虽然把偏移片段设成可选，但输入仍然必须先满足前面的日期和时间结构。不要为了兼容脏数据把 parseLenient() 当成默认修复方案，先明确允许的输入集合。

parseBest 的顺序决定保留多少信息

parseBest 会按查询顺序尝试结果类型，并返回第一个能够完整承接解析字段的对象。因此应把最完整的 OffsetDateTime 放在前面，再放 LocalDateTime，最后才是 LocalDate。顺序反过来时，带时间的输入可能先被截成日期，后续类型就没有机会接住原始信息。

static TemporalAccessor parseInput(String text) {
    return INPUT_FORMATTER.parseBest(
            text,
            OffsetDateTime::from,
            LocalDateTime::from,
            LocalDate::from);
}

static String describe(String text) {
    TemporalAccessor parsed = parseInput(text);
    if (parsed instanceof OffsetDateTime value) {
        return "offset=" + value;
    }
    if (parsed instanceof LocalDateTime value) {
        return "local-time=" + value;
    }
    return "date=" + LocalDate.from(parsed);
}

业务层可以保留这个三态结果，也可以在边界层统一成一个带“精度”字段的值对象。不要直接调用 LocalDateTime.from(parsed)，因为日期-only 的结果没有时分字段，强行转换会再次抛异常。

缺省值应该补在哪里

有些接口明确规定“只传日期时按当天零点解释”，这时可以在解析器里补 HOUR_OF_DAY、MINUTE_OF_HOUR 和 SECOND_OF_MINUTE。但这只是业务约定，不代表原始输入真的带有时间。

DateTimeFormatter dateAtStartOfDay = new DateTimeFormatterBuilder()
        .appendPattern("uuuu-MM-dd")
        .parseDefaulting(ChronoField.HOUR_OF_DAY, 0)
        .parseDefaulting(ChronoField.MINUTE_OF_HOUR, 0)
        .parseDefaulting(ChronoField.SECOND_OF_MINUTE, 0)
        .toFormatter(Locale.ROOT)
        .withResolverStyle(ResolverStyle.STRICT);

LocalDateTime start = LocalDateTime.parse("2026-08-26", dateAtStartOfDay);

时区要单独处理。parseDefaulting 可以补字段值，但不应该凭空补一个业务未确认的 ZoneOffset。如果接口约定统一使用北京时间，应在调用边界明确写出 ZoneId.of("Asia/Shanghai")，并在数据模型里区分“客户端提供的偏移”和“服务端补的时区”。

失败提示要保留输入和错误位置

解析异常不是只能记录一句“日期格式错误”。DateTimeParseException 提供了原始文本和错误索引，可以把它们转成日志字段或接口校验信息。生产日志里建议对输入做长度限制和必要的脱敏，避免把整段用户内容无控制地写入日志。

try {
    return describe(text);
} catch (DateTimeParseException ex) {
    int index = ex.getErrorIndex();
    throw new IllegalArgumentException(
            "日期字段格式不正确，错误位置=" + index + ", 原始值=" + text, ex);
}

测试至少覆盖四种结果：日期-only 返回 LocalDate，带分钟返回 LocalDateTime，带偏移返回 OffsetDateTime，非法日期如 2026-02-30 进入失败分支。再加一条尾部多余字符的用例，确认解析器没有只读前缀就当成功。

常见问题

为什么 parseBest 要把 OffsetDateTime 放在第一位？

因为查询顺序就是优先级。带偏移量的输入信息最完整，先尝试它才能避免被较弱的本地类型截断。

parseDefaulting 能不能补默认时区？

可以补字段，但不建议把未约定的时区当成输入事实。统一时区应由业务规则明确指定，并记录它是服务端补充的。

为什么日期-only 不能直接转 LocalDateTime？

日期-only 没有时、分、秒字段。若业务确实规定按零点处理，应使用显式的默认字段格式器，而不是在解析后强转。

如何判断输入是不是完整读完了？

使用格式器的完整解析入口，并用尾部多余字符做测试。解析未消费完整文本时，Java 会以 DateTimeParseException 报错。

落地前的检查清单

• 列出接口允许的日期、时间和偏移量组合，并为每种组合指定目标类型。
• 在 parseBest 中按信息完整度排列查询顺序。
• 只为有明确业务含义的字段使用 parseDefaulting。
• 为非法日期、尾部字符、缺失偏移量分别写回归测试。
• 记录 getErrorIndex()，让调用方能修正具体位置。