Java WeekFields 怎样配置一周起点与首周规则

我在做按周汇总的 Java 报表时，最容易被忽略的不是日期格式，而是“这一周从哪天开始”和“新年的第一周至少要有几天”。WeekFields 正好把这两个规则收在一起：用 of(DayOfWeek, int) 明确配置，或从 Locale、ISO 等入口取得既有定义。

这两个参数只要换一个，年初的周号就可能变化。下面用一组边界样例说明配置方法，重点放在 weekOfYear 与 weekOfWeekBasedYear 不应混用这一点。

先把一周起点和首周门槛拆开

firstDayOfWeek 表示一周的第 1 天，例如周一或周日；minimalDaysInFirstWeek 表示新月份或新年份要拥有多少天，才把这一段算作第 1 周。官方 API 将第二个参数限制在 1 到 7 之间，ISO 规则是周一开周、首周至少 4 天。

这两个值不是性能开关，也不是简单的“把日期加几天”。它们会共同决定 1 月 1 日附近是否出现 week 0，以及某个日期属于日历年还是 week-based-year。先把规则写进配置表，后面的统计口径才不会漂移。

固定规则时使用 WeekFields.of

如果业务约定不会跟着服务器地区变化，我更倾向于直接写出两个参数。这样代码审查时能一眼看出周一开周还是周日开周，也不会因为默认 Locale 改变而产生难以解释的报表差异。

import java.time.DayOfWeek;
import java.time.LocalDate;
import java.time.temporal.WeekFields;

public class WeekFieldsDemo {
    public static void main(String[] args) {
        // 固定为周一开周，并要求新年首周至少包含 4 天。
        WeekFields isoLike = WeekFields.of(DayOfWeek.MONDAY, 4);

        // 用 TemporalField 读取日期所在的周号。
        LocalDate date = LocalDate.of(2025, 1, 1);
        int weekOfYear = date.get(isoLike.weekOfYear());
        int weekOfWeekBasedYear = date.get(isoLike.weekOfWeekBasedYear());
        int weekBasedYear = date.get(isoLike.weekBasedYear());

        // 三个值分别服务日历年周号、周基准年周号和周基准年。
        System.out.printf("weekOfYear=%d, weekOfWeekBasedYear=%d, weekBasedYear=%d%n",
                weekOfYear, weekOfWeekBasedYear, weekBasedYear);
    }
}

这里的关键不是打印结果，而是字段选择：固定规则对象可以复用，日期对象只负责按该规则读取字段。WeekFields 是不可变且线程安全的，适合放在共享配置或静态常量中。

地区化场景从 Locale 或内置常量取规则

界面需要跟随用户地区显示周信息时，可以用 WeekFields.of(locale)。它会从本地化数据中取得周定义；Oracle 文档还说明，Locale 的 Unicode 扩展 fw 可以显式指定首日，若同时存在地区覆盖扩展，显式的 fw 优先。

import java.time.DayOfWeek;
import java.time.LocalDate;
import java.time.temporal.WeekFields;
import java.util.Locale;

public class LocaleWeekDemo {
    public static void main(String[] args) {
        // 用 Locale 取得地区化周规则；不把默认地区偷偷写死进业务判断。
        WeekFields localRules = WeekFields.of(Locale.US);

        // 用 Unicode 扩展要求英文环境也按周一开周。
        Locale mondayLocale = Locale.forLanguageTag("en-u-fw-mon");
        WeekFields mondayRules = WeekFields.of(mondayLocale);

        LocalDate date = LocalDate.of(2025, 1, 1);
        DayOfWeek firstDay = mondayRules.getFirstDayOfWeek();
        int localWeek = date.get(localRules.weekOfYear());

        // 记录规则来源，便于排查不同地区的周号差异。
        System.out.printf("firstDay=%s, usWeek=%d%n", firstDay, localWeek);
    }
}

如果产品要求所有用户看到同一套财务周，Locale 就不应作为隐含输入；应该回到上一节的固定参数。反过来，如果是本地化日历，先明确“显示给用户”还是“落库用于聚合”，两者不一定使用同一规则。

weekOfYear 和 week-based-year 不是同一个口径

weekOfYear() 保证周不会跨越日历年边界，年初不满足首周门槛的部分可以是 week 0。weekOfWeekBasedYear() 则把每一周完整地归给一个周基准年，年初几天可能属于上一年的最后一周。

因此，按“2025 年的周”做业务汇总时，先问清楚年是日历年还是周基准年：

用年初和年末边界做验收

我会固定检查 1 月 1 日前后至少 3 个日期：上一年最后几天、1 月 1 日、首个完整工作周。对 ISO-like 规则，可以把 weekBasedYear 与 weekOfWeekBasedYear 一起输出，不要只保存一个周号。

import java.time.LocalDate;
import java.time.temporal.WeekFields;

public class WeekBoundaryCheck {
    public static void main(String[] args) {
        WeekFields rules = WeekFields.ISO;
        LocalDate[] samples = {
                LocalDate.of(2024, 12, 30),
                LocalDate.of(2025, 1, 1),
                LocalDate.of(2025, 1, 6)
        };

        for (LocalDate date : samples) {
            // 同时输出周基准年和周号，避免跨年时只看 week=1 而丢失年份。
            int year = date.get(rules.weekBasedYear());
            int week = date.get(rules.weekOfWeekBasedYear());
            System.out.printf("%s -> %d-W%02d%n", date, year, week);
        }
    }
}

验收时重点看“边界日期是否落入业务期待的年”和“同一套规则是否贯穿查询、展示、导出”。如果结果不符合需求，先检查起始日和最少天数，再检查是不是误用了 weekOfYear()。

最后保留一份周规则决策

固定周口径可以归纳为三条：第一，跨地区业务明确写出 DayOfWeek 与最少天数；第二，本地化展示才从 Locale 读取；第三，跨年统计把 weekBasedYear 和 weekOfWeekBasedYear 成对保存。这样排查周号差异时，先看规则输入，再看字段语义，定位会比盯着格式化字符串更快。

相关问题：为什么同一天在两个系统里周号不同？通常是首日或首周门槛不同。为什么出现第 0 周？日历年模式下，年初那段日期尚未满足首周最少天数。什么时候用 WeekFields.ISO？当业务明确采用 ISO-8601 周定义时最直接。