Java DateTimeFormatter 使用 YYYY 解析年末日期为什么错

如果 Java 日期在 12 月末突然显示成下一年，先检查格式串里是否写了大写 YYYY。它不是普通的日历年，而是 week-based-year（周基准年）；周基准年的边界由周规则决定，所以一周跨过公历新年时，日期和年份可能不属于同一个“年”。订单、账单、日志等按日历归档的日期应使用 uuuu-MM-dd，而不是 YYYY-MM-dd。

年末日期为什么会被 YYYY 推到下一年

LocalDate 保存的仍是原来的公历日期，变化发生在格式化器读取的字段上。Oracle 的 DateTimeFormatter 模式表把大写 Y 定义为 week-based-year，把小写 y 定义为 year-of-era；u 则是 proleptic-year。周基准年关注“这一周属于哪个周年度”，不等价于日期所在的公历年。

例如，某个 Locale 的周规则把 12 月最后几天归入下一周年度时，ofPattern("YYYY-MM-dd") 可能输出一个看起来像“年份变了、月日没变”的结果。这个格式串把周基准年和月、日历日拼到了一起，字段语义不完整，既不适合展示普通日期，也不适合作为稳定的日期交换格式。

普通日期应该改成 uuuu 或 yyyy

面向数据库、接口、文件名和日志的公历日期，推荐先确定是否需要“公元前”等年-of-era 语义。绝大多数 ISO 日期直接使用 uuuu-MM-dd，它能覆盖完整的有符号年；只处理常规公元年且沿用年-of-era 语义时，也可以使用 yyyy-MM-dd。

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

public class CalendarYearDemo {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2021, 12, 31);
        DateTimeFormatter calendar = DateTimeFormatter.ofPattern("uuuu-MM-dd");

        // uuuu 表示日历年，适合订单、账单和接口中的普通日期。
        String text = date.format(calendar);
        // 解析时继续使用同一个格式，避免格式化和解析的字段语义不一致。
        LocalDate restored = LocalDate.parse(text, calendar);

        System.out.println(text);
        System.out.println(restored);
    }
}

格式化与解析最好共用同一个明确的 formatter。不要先用 YYYY-MM-dd 生成文本，再期待用普通日历年规则无损还原；如果业务协议就是公历日期，协议、示例和测试都应统一为 uuuu-MM-dd。

确实要表达周日期时，YYYY 必须和周字段成组

周报、ISO 周计划或按周统计的键可以使用周基准年，但不能只拿 YYYY 替换普通日期中的 yyyy。完整周日期至少要表达周基准年、周数和星期几，例如 YYYY-'W'ww-e。同时，WeekFields 的第一天和首周最少天数会影响边界判断，因此应固定 Locale，不能让服务器默认 Locale 决定协议含义。

import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.util.Locale;

public class WeekDateDemo {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2021, 12, 31);
        // 周日期必须把 YYYY、ww、e 放在同一语义中，并固定 Locale。
        DateTimeFormatter isoWeek = DateTimeFormatter
                .ofPattern("YYYY-'W'ww-e", Locale.ROOT);

        System.out.println(date.format(isoWeek));
    }
}

如果只想得到普通的年、月、日，不要使用这段周日期格式。只有报表的维度本身是“第几周”时，周基准年才是正确字段。

把年末边界加入代码评审和测试

排查时优先搜索格式串中的大写 Y，再确认文本用途是公历日期还是周日期。测试数据不要只选 6 月或 7 月，至少覆盖 12 月末、1 月初、周一与周日，并在 CI 中显式设置 Locale。对外接口还应固定格式协议，不要依赖开发机和生产机的默认区域设置。

常见问题

为什么同一个 YYYY 格式在不同机器上结果不同？周字段可能受到 Locale 的周起始日和首周规则影响。把 Locale 写进 formatter，并在边界日期上测试，才能让结果稳定。

yyyy 和 uuuu 应该怎么选？yyyy 是 year-of-era，uuuu 是完整的 proleptic-year。普通 ISO 日期优先使用 uuuu，需要传统公元纪年展示时再选择 yyyy。

只把 YYYY 改成 yyyy 就一定正确吗？对常规公历展示通常还不够严谨；若是接口或文件协议，建议直接统一成 uuuu-MM-dd，并检查解析端、测试数据和时区转换是否也使用相同语义。