Java DateTimeFormatterBuilder 怎样兼容多种日期格式

接口接收日期字符串时，最稳妥的做法不是把所有分隔符塞进一个超长模式，而是用 DateTimeFormatterBuilder 分别构造允许的格式，再按“具体格式优先”的顺序解析。这样既能兼容 2026-10-29、2026/10/29 和带秒的日期时间，也能把非法日期明确拦截。

官方地址：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/format/DateTimeFormatterBuilder.html

本文示例使用 Java 8 及以上的 java.time API。重点是多格式输入的构造、尝试顺序和结果类型，不把不同含义的文本强行归并成一个模糊模式。

先把允许的格式拆成独立构造器

DateTimeFormatterBuilder 是可变构造器，官方文档明确说明它适合单线程使用；完成后通过 toFormatter 得到格式器。多种格式应各自完成构造，避免后续追加内容时相互污染。

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.DateTimeParseException;
import java.time.temporal.TemporalAccessor;
import java.util.List;
import java.util.Locale;

final class MultiDateParser {
    private static DateTimeFormatter pattern(String value) {
        // 每次使用独立 Builder，避免可变状态被不同格式共享。
        return new DateTimeFormatterBuilder()
                .appendPattern(value)
                .toFormatter(Locale.ROOT);
    }

    private static final List FORMATTERS = List.of(
            pattern("uuuu-MM-dd HH:mm:ss"), // 信息最完整，放在前面
            pattern("uuuu/MM/dd"),          // 兼容斜杠日期
            pattern("uuuu-MM-dd")           // 最后匹配纯日期
    );

    static TemporalAccessor parse(String text) {
        for (DateTimeFormatter formatter : FORMATTERS) {
            try {
                // 先尝试日期时间，再退回到纯日期，保留结果的真实精度。
                return formatter.parseBest(
                        text, LocalDateTime::from, LocalDate::from);
            } catch (DateTimeParseException ignored) {
                // 当前格式不匹配时继续尝试下一种，不吞掉最终错误。
            }
        }
        throw new IllegalArgumentException("不支持的日期格式: " + text);
    }
}

这里使用 uuuu 而不是 yyyy，是为了让基于 ISO 年的严格解析语义更清晰。解析成功后返回值可能是 LocalDateTime 或 LocalDate，调用方应先判断类型，再决定是否补充时间。

为什么要按具体格式优先

格式顺序会影响可维护性。带时分秒的模式信息最完整，应先尝试；纯日期模式只处理日期，放在后面。不要把 parseLenient() 当成“万能兼容开关”，它可能放宽数字宽度和符号规则，却不能替你定义业务上真正允许的格式。

严格模式下，日期本身的合法性也会参与判断，因此 2026-02-30 不应被静默纠正。若产品确实允许缺省秒或缺省月份，应该增加对应的独立格式，并在接口契约中写清默认值。

用 parseBest 保留日期与日期时间的差异

parseBest 适合一个格式器能产生不同时间对象的场景。本文的每个格式器只有一个明确结构，但仍可用同一组查询器先尝试 LocalDateTime，再尝试 LocalDate，从而避免把纯日期错误地扩展成带时区的时间点。

TemporalAccessor value = MultiDateParser.parse(input);
if (value instanceof LocalDateTime dateTime) {
    // 只有输入真的包含时间时，才进入时间精度相关的业务分支。
    handleDateTime(dateTime);
} else if (value instanceof LocalDate date) {
    // 纯日期不擅自补时区或当前时间，避免改变原始语义。
    handleDate(date);
}

如果下游接口必须统一成某一种对象，应在这一层显式制定策略，例如纯日期统一按业务时区的零点转换；不要在解析器内部偷偷使用系统默认时区。

常见边界与排查方式

• 格式新增：先新增一个独立 Builder 和样例，再决定它在列表中的位置。
• 结果类型混淆：不要对 TemporalAccessor 直接调用某个日期方法，先用 instanceof 判断。
• 共享 Builder：Builder 是可变对象，初始化阶段完成构造后只共享最终的 DateTimeFormatter。
• 错误信息：对外返回统一的参数错误，对内记录原始输入和尝试过的格式编号，但不要把异常堆栈直接暴露给接口调用方。

一组可执行的回归样例至少应覆盖三种成功格式、一个非法日期、一个缺少秒的近似格式，以及空字符串。这样格式集合调整后，能够快速判断是新增能力还是意外放宽。

结论

用 DateTimeFormatterBuilder 兼容多种日期格式的核心，是“一个业务格式一个构造器、具体格式优先、严格解析、结果类型不丢失”。appendOptional 更适合同一语法中确实可选的片段；当分隔符和整体结构都不同，维护独立格式列表更直观，也更容易测试和回滚。

相关问答

能不能用一个模式同时匹配横杠和斜杠？ 不建议把不同分隔符硬塞进同一个模式；分别构造格式并按顺序尝试更清晰。

为什么不直接使用 DateTimeFormatter.ofPattern？ 单一格式当然可以使用它；本文选择 Builder 是为了集中表达格式片段、严格策略和未来的可选字段扩展。