Java 时间格式兼容多个输入格式的方法

接口接收时间字符串时，最常见的麻烦不是“不会写格式串”，而是同一个字段可能出现几种稳定形状：只有日期、日期加分钟、日期加分钟和秒，甚至日期与时间之间分别使用 T 或空格。处理这类输入时，先把一条格式里的可选部分交给 DateTimeFormatterBuilder，再把真正不同的格式分支拆成多个格式器，代码会更容易维护。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/

本文的核心选择是：可选秒数属于同一条格式，可以使用 optionalStart() 和 optionalEnd()；T 与空格属于不同分隔符，不要把两个字面量都做成可选，而应使用两个候选格式器。最终再用 parseBest 得到 LocalDateTime 或 LocalDate，并对非法输入保留明确异常。

先把固定日期和可选时间段拆开

optionalStart() 标记可选段的开始，optionalEnd() 标记结束。解析时，整个段可以从输入中一起缺席；格式化时，只有该段需要的字段都可用，才会输出这段内容。它适合描述“日期后面可能有时间”或“时间后面可能有秒数”这种线性变化。

下面这个格式器支持四种输入：2026-10-18、2026-10-18T09:30、2026-10-18T09:30:15，以及同样带空格的时间形式会在后文单独处理。

import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.ResolverStyle;

public final class DateTimeFormats {
    private DateTimeFormats() {
        // 工具类不需要被实例化。
    }

    public static final DateTimeFormatter T_FORMAT = new DateTimeFormatterBuilder()
            .appendPattern("uuuu-MM-dd")
            .optionalStart()
            .appendLiteral('T')
            .appendPattern("HH:mm")
            .optionalStart()
            .appendPattern(":ss")
            .optionalEnd()
            .optionalEnd()
            // 严格模式负责拒绝不存在的日期和超范围时间。
            .toFormatter()
            .withResolverStyle(ResolverStyle.STRICT);
}

这里的 uuuu 表示年字段，配合严格解析更适合构造可校验的 ISO 风格输入。注意可选段包含了分隔符和时间字段：如果只把秒数做成可选，分钟部分仍然必须成组出现；这样不会接受一个孤立的冒号。

可选段不是格式分支，分隔符不同要拆开

把 T 和空格都分别写成可选字面量，看起来像“兼容更多输入”，实际会产生不该接受的组合，例如没有分隔符或同时出现两个分隔符。optionalStart 描述的是一段整体可有可无，不是正则表达式里的任意分支。

因此，输入契约如果明确允许 T 和空格两种分隔符，就建立两个格式器。它们共享“日期、分钟、可选秒”的结构，但每个格式器只接受自己的分隔符。

import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.ResolverStyle;

final class FormatCatalog {
    private FormatCatalog() {
        // 只提供格式器，不创建目录对象。
    }

    static DateTimeFormatter build(char separator) {
        return new DateTimeFormatterBuilder()
                .appendPattern("uuuu-MM-dd")
                .appendLiteral(separator)
                .appendPattern("HH:mm")
                .optionalStart()
                .appendPattern(":ss")
                .optionalEnd()
                // 每个候选格式器都保持严格解析，避免分支之间规则不一致。
                .toFormatter()
                .withResolverStyle(ResolverStyle.STRICT);
    }
}

如果来源只有一种格式，保留一个格式器即可；只有在输入协议真的允许多种形状时，才维护候选集合。分支越多，越应该在接口边界先规范化，而不是把所有可能的日期写进一个“万能格式器”。

用 parseBest 把日期和日期时间统一成结果

格式器可以解析出字段，但调用方还要决定返回什么类型。parseBest 接收多个查询器，会优先尝试更具体的结果；带时间的输入可以得到 LocalDateTime，只有日期的输入则得到 LocalDate。在业务层如果必须返回统一类型，可以把纯日期明确映射为当天零点，但这一步要写成业务约定，不要假装输入里本来就有时间。

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

public final class FlexibleDateTimeParser {
    private static final List INPUT_FORMATS = List.of(
            FormatCatalog.build('T'),
            FormatCatalog.build(' ')
    );

    private FlexibleDateTimeParser() {
        // 解析器只提供静态入口。
    }

    public static LocalDateTime parse(String text) {
        DateTimeParseException last = null;
        for (DateTimeFormatter formatter : INPUT_FORMATS) {
            try {
                // 先尝试更具体的日期时间，再接受只有日期的结果。
                TemporalAccessor parsed = formatter.parseBest(
                        text, LocalDateTime::from, LocalDate::from);
                if (parsed instanceof LocalDateTime) {
                    return (LocalDateTime) parsed;
                }
                // 纯日期归一到当天零点，这是本示例明确约定的业务默认值。
                return ((LocalDate) parsed).atStartOfDay();
            } catch (DateTimeParseException ex) {
                // 记录本次候选的真实解析错误，继续尝试下一个格式。
                last = ex;
            }
        }
        // 所有候选都失败时保留最后一次异常，便于调用方记录输入问题。
        throw last;
    }
}

这段代码把“格式分支”和“结果类型”分开了：候选格式器只负责输入形状，parseBest 只负责从已解析字段中选择类型。若业务不允许纯日期，应该删除 LocalDate::from 和零点归一化，而不是默默补时间。

按输入契约选择方案，别把解析器做成黑箱

还要留意三点：第一，DateTimeFormatter 是不可变且线程安全的，可以缓存格式器；第二，DateTimeFormatterBuilder 本身是可变构建器，通常在初始化阶段构造，不要在多个线程中共享同一个正在追加字段的 Builder；第三，严格解析解决的是日期合法性，不会替你判断时区、业务营业日或夏令时规则。

落地前的检查清单

• 可选的是完整字段组，还是仅仅一个字符？分隔符通常应和后续时间一起出现。
• 不同输入分隔符是否真的在接口契约中被允许？没有契约就不要继续增加候选格式。
• 是否使用 uuuu 和 ResolverStyle.STRICT 处理严格日期？
• 纯日期是否应该返回 LocalDate，还是有明确理由归一到当天零点？
• 所有候选失败时，是否保留异常而不是返回 null 或一个猜测的时间？

归纳起来：optionalStart 适合表达同一格式内部的可选段，appendOptional 适合复用一个可选格式器；真正不同的分隔符和输入形状应该拆成候选格式器，再用 parseBest 选择返回类型。这样既能兼容历史输入，也不会把非法组合悄悄放进系统。

相关问题

为什么不直接用一个正则表达式处理所有时间？

正则可以识别字符形状，却不会自然完成日期字段解析、严格范围检查和 TemporalAccessor 到目标类型的解析。格式器更适合承担时间语义。

optionalStart 可以代替多个格式器吗？

不能。它描述的是一条格式里的可选连续片段；当分隔符或字段顺序真的不同，应保留多个候选格式器。

解析失败时要不要返回 null？

不建议。输入不符合契约时抛出或转换为明确的业务异常，通常比返回 null 更容易定位，也不会把错误推迟到后续代码。