Java DateTimeFormatter 严格解析日期：ResolverStyle、时区与无效输入验收

表单里的“2024-02-30”如果直接交给宽松解析，程序可能把它调整成三月的一天，错误就会一路流到订单、账期或报表。Java 的 DateTimeFormatter 可以把格式、解析风格和时区拆开控制：日期字段用 ResolverStyle.STRICT，带时区的时间先明确输入偏移，再决定是否转换到业务时区。

先确定输入到底是日期还是时间点

“生日”“账单日”通常只有日历含义，适合 LocalDate；“支付完成时间”代表时间线上的一个点，应该带偏移或时区。两者都写成字符串再交给一个通用方法，最容易在接口边界混淆语义。

可以先按下面的约束做选择：

用 uuuu 和 STRICT 拒绝不存在的日期

yyyy 是 year-of-era 字段，遇到严格解析时还需要 era 才能完成解析；面向普通公历日期，uuuu 更直接。下面的格式器只接受四位年份、两位月份和两位日期，并且不允许把 2 月 30 日自动滚动到 3 月。

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.format.ResolverStyle;

static final DateTimeFormatter DATE_FORMATTER =
        DateTimeFormatter.ofPattern("uuuu-MM-dd")
                .withResolverStyle(ResolverStyle.STRICT);

static LocalDate parseBusinessDate(String text) {
    try {
        return LocalDate.parse(text, DATE_FORMATTER);
    } catch (DateTimeParseException ex) {
        throw new IllegalArgumentException("日期格式或日期值无效: " + text, ex);
    }
}

parseBusinessDate("2024-02-29"); // 成功
parseBusinessDate("2023-02-29"); // 拒绝
parseBusinessDate("2024-02-30"); // 拒绝

这里有两个独立门槛：格式器先判断分隔符和位数，解析风格再判断日历是否成立。把异常转换成业务异常时保留原始输入即可，不要把完整堆栈或内部路径直接返回给前端。

格式正确不等于业务日期一定可用

严格解析只能回答“这是不是一个真实的公历日期”。它不能判断营业日、节假日、账期截止日，也不会自动理解“月底”。例如 2024-02-29 在日历上有效，但如果业务规定结算日不能落在周末，仍要在解析后追加业务校验。

LocalDate date = parseBusinessDate(input);
if (date.isBefore(LocalDate.of(2020, 1, 1))) {
    throw new IllegalArgumentException("日期早于业务允许范围");
}
if (date.getDayOfWeek().getValue() >= 6) {
    throw new IllegalArgumentException("结算日期不能是周末");
}

建议把“文本解析”和“业务范围判断”留在两个方法里。这样测试失败时能立刻知道是格式问题，还是规则表需要更新。

有偏移的时间先保留原始事实

接口收到 2026-08-26T09:30:00+08:00 时，+08:00 是输入事实；如果直接解析成 LocalDateTime，偏移就丢了。需要跨地区排序或记录事件时，先使用 OffsetDateTime：

import java.time.OffsetDateTime;
import java.time.ZoneId;

OffsetDateTime source = OffsetDateTime.parse("2026-08-26T09:30:00+08:00");
OffsetDateTime utc = source.withOffsetSameInstant(java.time.ZoneOffset.UTC);
var shanghai = source.atZoneSameInstant(ZoneId.of("Asia/Shanghai"));

System.out.println(source);   // 保留输入偏移
System.out.println(utc);      // 同一时刻的 UTC 表示
System.out.println(shanghai); // 按地区规则展示

withOffsetSameInstant 保持时间点不变，只改变显示偏移；若业务要改变“墙上时钟”的数值，调用前必须先确认那不是一次时区转换。这个区别在跨地区报表中尤其重要。

一组小测试覆盖最容易漏掉的边界

不要只测一个正常日期。下面的检查表可以直接转成参数化测试：

• 2024-02-29 成功，2023-02-29 失败。
• 2024-2-9 失败，避免输入格式悄悄变宽。
• 2024-01-01x 失败，防止尾随内容被忽略。
• 日期范围上下界各测一次，并单独测试周末和节假日规则。
• 带偏移的时间验证同一瞬间在 UTC 与业务地区显示一致。

如果输入来自 JSON，字段为空、缺失、前后空格也要在进入时间 API 前明确处理。是否允许自动 trim 是接口契约，不要让不同控制器各自决定。

常见问题：严格解析和时区怎么选

为什么推荐 uuuu-MM-dd 而不是 yyyy-MM-dd？

uuuu 表示连续的年份字段，和 ResolverStyle.STRICT 配合时不需要额外的 era 信息，适合普通公历日期输入。

ResolverStyle.STRICT 会检查周末吗？

不会。它只负责解析字段和日历合法性，周末、节假日、业务上下界要在得到 LocalDate 后单独判断。

什么时候应该用 ZonedDateTime？

当业务需要地区时区规则，例如夏令时或按地区展示时间时使用它；如果输入只有数字偏移，先用 OffsetDateTime 保留事实更稳妥。

解析失败时是否可以自动改成下一个有效日期？

一般不应自动改。账期、生日和订单时间都可能因为一次“修正”产生不同业务结果，应该拒绝并让调用方修正输入。

把解析规则收进可维护的验收清单

最终落地时，格式器常量、文本解析、业务范围校验和时区转换最好各自有测试。先确认输入语义，再选择 LocalDate、OffsetDateTime 或 ZonedDateTime；用 STRICT 守住日历边界，最后用业务规则守住可接受范围。这样日期错误会在接口边界暴露，而不是在报表或结算结果里才出现。