Java IsoFields.WEEK_BASED_YEAR 为什么与普通年份不同

Java 里看到 IsoFields.WEEK_BASED_YEAR 与 LocalDate.getYear() 返回不同年份，并不代表日期计算出错。前者属于 ISO-8601 的“周年”字段：一周从星期一开始，新年的第一周必须包含至少 4 天；后者是普通公历年份，固定在 1 月 1 日切换。年末跨年周因此可能同时出现“普通年份还是 2025、ISO 周年已经是 2026”的结果。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/temporal/IsoFields.html

年末报表出现“年份不一致”时，先看影响面

这类问题通常出现在周报文件名、按周分组的数据库键、日志归档目录或接口返回字段里。开发者先用 date.getYear() 得到 2025，再用 IsoFields.WEEK_BASED_YEAR 得到 2026，如果把两个值拼到同一个业务字段，结果就会像是同一天同时属于两个年份。

真正需要先确认的是：业务要的是自然年，还是“某一年的第几周”。自然年报表应使用普通的 YEAR；周报、按 ISO 周聚合的指标，则应把 ISO 周年、周序号和星期几作为一个整体。只取其中一个字段，无法表达完整的周日期。

用一组跨年日期复现问题

下面的例子选取 2025 年最后一周附近的日期。代码同时读取普通年份、ISO 周年和 ISO 周序号，输出的差异正好对应标题中的症状。

import java.time.LocalDate;
import java.time.temporal.IsoFields;

public class IsoYearDemo {
    public static void main(String[] args) {
        LocalDate[] dates = {
                LocalDate.of(2025, 12, 28),
                LocalDate.of(2025, 12, 29),
                LocalDate.of(2025, 12, 31),
                LocalDate.of(2026, 1, 1),
                LocalDate.of(2026, 1, 4)
        };

        for (LocalDate date : dates) {
            // getYear() 是普通公历年份，WEEK_BASED_YEAR 是 ISO 周年。
            int calendarYear = date.getYear();
            int weekYear = date.get(IsoFields.WEEK_BASED_YEAR);
            int week = date.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR);
            int day = date.get(IsoFields.DAY_OF_WEEK);
            System.out.printf("%s -> YEAR=%d, WEEK_BASED_YEAR=%d, week=%d, day=%d%n",
                    date, calendarYear, weekYear, week, day);
        }
    }
}

关键现象是：12 月 29 日到 12 月 31 日已经落在下一个 ISO 周年的第 1 周，而普通日期的年份仍然是 2025。1 月 1 日和 1 月 4 日继续属于 2026 年的第 1 周；1 月 5 日才进入第 2 周。生产代码不应根据“月份大于 12 月”这样的直觉手工修正，而应直接使用同一套周历字段。

根因是 ISO 周年不在 1 月 1 日简单切换

IsoFields 为 ISO 日历系统提供周相关字段。官方规则定义了三个相互配套的值：DAY_OF_WEEK 是星期一到星期日的 1 到 7，WEEK_OF_WEEK_BASED_YEAR 是周序号，WEEK_BASED_YEAR 是这组周所属的周年。

ISO 周年的第 1 周必须是“以星期一为起点，并且在新年中至少有 4 天”的那一周。于是，当 1 月 1 日落在星期二、星期三或星期四时，上一年 12 月末的几天可能属于新 ISO 周年；反过来，当 1 月 1 日落在星期五、星期六或星期日时，1 月初的日期仍可能属于上一 ISO 周年的最后一周。

读取周报键时，要把三个字段一起保存

如果接口或数据表需要一个稳定的周键，推荐显式保存 ISO 周年、周序号和星期几，或者保存一个明确标注为 ISO 周的字符串。不要只保存 week，因为第 1 周每年都会重复；也不要只保存普通年份和周序号，否则跨年周仍会被分到错误的年度。

import java.time.LocalDate;
import java.time.temporal.IsoFields;

record IsoWeekKey(int year, int week, int dayOfWeek) {}

public class IsoWeekKeyDemo {
    static IsoWeekKey keyOf(LocalDate date) {
        // 三个字段必须来自同一个日期，避免跨年周被拆成混合键。
        return new IsoWeekKey(
                date.get(IsoFields.WEEK_BASED_YEAR),
                date.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR),
                date.get(IsoFields.DAY_OF_WEEK));
    }

    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2025, 12, 31);
        IsoWeekKey key = keyOf(date);
        // 业务层可将 year 和 week 组合成 2026-W01，再按需要保留星期几。
        System.out.printf("%d-W%02d-%d%n", key.year(), key.week(), key.dayOfWeek());
    }
}

如果业务只关心“这一周”，可以把星期几排除在展示键之外，但仍然要用同一个 ISO 周年和周序号计算分组。对数据库字段来说，建议把 calendar_year 与 iso_week_year 命名区分开，避免后续维护者把两者当成同一含义。

格式化时不要把 YYYY 当成 yyyy

DateTimeFormatter 的模式字母有明确语义：小写 y 表示 year-of-era，大写 Y 表示 week-based-year，w 表示 ISO 周序号。也就是说，YYYY-MM-dd 并不是“普通年份-月份-日期”的安全写法；它把周年度和普通月日拼在了一起，跨年时很容易生成让人误解的字符串。

输出自然日期时使用 uuuu-MM-dd 或预定义的 ISO_LOCAL_DATE；输出周日期时使用 ISO_WEEK_DATE，让周年、周序号和星期几保持匹配。

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

public class FormatterDemo {
    public static void main(String[] args) {
        LocalDate date = LocalDate.of(2025, 12, 31);

        // 普通日期使用 uuuu，避免把周年度误当成公历年份。
        String calendarText = date.format(DateTimeFormatter.ISO_LOCAL_DATE);
        // 周日期让周年、周序号和星期几成套输出。
        String isoWeekText = date.format(DateTimeFormatter.ISO_WEEK_DATE);

        System.out.println(calendarText);
        System.out.println(isoWeekText);
    }
}

解析也要遵循同样的配对原则：普通日期用普通日期格式解析，ISO 周日期用 ISO_WEEK_DATE 解析。若必须自定义格式，先确认输入确实是周日期，再组合 YYYY、ww 和星期字段；不要把 YYYY 单独塞进普通日期格式。

用测试锁住两个“年”的边界

这类问题最适合用边界日期测试，而不是只测试 6 月中旬。至少覆盖 12 月最后一周、1 月第一周、52 周和可能的 53 周，并明确业务字段究竟采用自然年还是 ISO 周年。

import static org.junit.jupiter.api.Assertions.assertEquals;
import java.time.LocalDate;
import java.time.temporal.IsoFields;
import org.junit.jupiter.api.Test;

class IsoFieldsTest {
    @Test
    void yearAndWeekYearCanBeDifferentAtYearEnd() {
        LocalDate date = LocalDate.of(2025, 12, 31);

        // 断言两个字段的差异是预期规则，而不是把它们强行改成相同值。
        assertEquals(2025, date.getYear());
        assertEquals(2026, date.get(IsoFields.WEEK_BASED_YEAR));
        assertEquals(1, date.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR));
    }
}

如果产品需求说“2025 年第 1 周”，要回头确认它指的是自然年中的周，还是 ISO 周年的第 1 周。这两个定义不相同，不能靠格式化字符串临时决定。把字段含义写进接口文档、数据库注释和测试名称，能减少下一次排查成本。

常见问题

为什么 12 月 31 日的 WEEK_BASED_YEAR 可能是下一年？

因为 ISO 第 1 周按星期一开始，并要求新年中至少有 4 天。某些年份的最后一个星期一开始的那一周，虽然日期大多在 12 月，却已经满足下一 ISO 周年的规则。

YYYY 和 yyyy 可以互换吗？

不能。大写 Y 是 week-based-year，小写 y 是 year-of-era。普通日期展示应优先使用 uuuu 或预定义 ISO 日期格式。

只保存周序号够吗？

不够。周序号必须和同一套 ISO 周年一起保存；否则每年的第 1 周、第 2 周都会互相冲突。

IsoFields.WEEK_BASED_YEAR 是否会改变 LocalDate 本身？

不会。LocalDate 是不可变日期对象，读取字段只是查询值；通过 with 设置字段会返回调整后的新日期，原对象不变。业务代码应明确保存返回值，避免误以为原日期已经被修改。

归根结底，普通年份和 ISO 周年不是两个算法实现，而是两种不同的日期坐标系。自然年统计使用 YEAR，周统计使用 WEEK_BASED_YEAR + WEEK_OF_WEEK_BASED_YEAR + DAY_OF_WEEK，格式化时让字段组保持一致，跨年报表就不会再把“日期所属年”和“周所属年”混在一起。