在报表查询场景中，前端往往只传年份和第几周，后端必须将其还原成具体的日期区间才能拼SQL。Java 8引入的java.time包提供了完整的周历模型，不需要再依赖容易出错的Calendar。理解WeekFields与LocalDate的组合用法，是写出稳定过滤逻辑的基础。
WeekFields与周定义的核心概念
很多人以为一年第10周就是简单除以7，实际上周的划分高度依赖地区规则。ISO 8601规定每周从周一开始，且一年第一周至少包含4天，这就是WeekFields.ISO。而美国习惯周日为一周起点，且最小天数为1，对应WeekFields.SUNDAY_START。如果用错规则，算出的日期会和报表前端展示差一两天。
WeekFields本身是一个不可变对象，它包含三个要素：一周的第一天（getFirstDayOfWeek）、一年第一周最少天数（getMinimalDaysInFirstWeek）、以及周数和时间字段的映射。通过weekOfWeekBasedYear()方法可以拿到代表“基于年的周数”的TemporalField，再配合localDate.with()就能定位。
需要注意，周数有可能是跨年的。比如ISO规则下2023年第52周可能落在2024年1月，因此我们不能只拿年份直接构造1月1日再加周偏移，而必须使用LocalDate.of(year, 1, 1).with(weekField.weekOfWeekBasedYear(), week)这种基于周历的赋值方式，否则遇到边界周会直接抛DateTimeException。
从周数获取日期范围的完整代码实现
下面示例演示如何根据年份和周数，算出该周的第一天和最后一天。这里以ISO规则为例，如果你的报表面向美国用户，把WeekFields.ISO换成WeekFields.of(Locale.US)即可。
import java.time.DayOfWeek;
import java.time.LocalDate;
import java.time.temporal.WeekFields;
import java.util.Locale;
public class WeekToRange {
public static LocalDate[] getWeekRange(int year, int week) {
// 使用ISO周规则：周一为起始，最少4天算第一周
WeekFields wf = WeekFields.ISO;
// 先定位到该年的第一周第一天附近的锚点
LocalDate anchor = LocalDate.of(year, 1, 1)
.with(wf.weekOfWeekBasedYear(), week)
.with(wf.dayOfWeek(), 1);
LocalDate start = anchor;
LocalDate end = anchor.with(wf.dayOfWeek(), 7);
return new LocalDate[]{start, end};
}
public static void main(String[] args) {
LocalDate[] range = getWeekRange(2023, 10);
System.out.println("开始: " + range[0]);
System.out.println("结束: " + range[1]);
}
}
上面的代码里，with(wf.dayOfWeek(), 1)表示把日期调整到本周第一天（ISO下是周一），with(wf.dayOfWeek(), 7)则是周日。由于WeekFields已经处理了跨年逻辑，即使week是53或者1也能正确返回对应日期。
如果数据库里存的是带时分秒的Timestamp，建议把end再加一天然后做小于判断，避免漏掉周日23点59分的数据。例如endDate.plusDays(1).atStartOfDay()作为上限，用create_time >= start and create_time < nextDay的半开区间，这是报表过滤最稳妥的写法。
在报表过滤中的实际应用与避坑
当我们将算出的LocalDate转成SQL参数时，必须先明确数据库时区。假设应用服务器是UTC+8，而MySQL使用UTC，直接传字符串“2023-03-06”会被视作UTC零点，实际查询窗口会偏移八小时。解决办法是在JDBC连接串统一serverTimezone=Asia/Shanghai，或者在代码里用ZonedDateTime显式转换。
另一个常见坑是前端传的“周数”到底是自然周还是商业周。电商报表常用“周日为起点”的本地化规则，而政府统计多用ISO。如果前后端没有约定清楚，后端用WeekFields.ISO算，前端用Sunday起点的日历选，用户就会看到某周数据少了一天。建议接口文档明确写死使用的Locale，并在后端用断言校验week范围在1到53之间。
对于超大数据表，直接在SQL里对create_time套函数算周数会导致索引失效。正确做法是后端算好起止日期，用between类的范围查询，让B+树索引生效。如果必须按周分组统计，可以冗余一个week_start_date字段，写入时由上述Java逻辑计算并存储，查询时直接等值匹配，性能提升非常明显。
旧API与新API的对比总结
在java.time出现之前，开发者只能用Calendar设置Calendar.WEEK_OF_YEAR，但Calendar是可变对象且周规则隐式依赖默认时区，多线程下极易出错。新API把“周规则”抽象成WeekFields，把“日期”抽象成不可变的LocalDate，从语言层面消除了这类隐患。
此外，WeekFields支持任意Locale，做国际化报表时只需换参数，核心算法不变。配合DateTimeFormatter还能直接格式化输出“2023-W10”这样的标准周标识。对于需要长期维护的报表系统，全面迁移到java.time几乎是必选项。
最后提醒，如果项目还停留在Java 7及以下，可以通过ThreeTen-Backport库引入相同的API，不要为了兼容继续手写复杂的周数换算公式，那样既难读又难测。写好单元测试覆盖跨年和闰年的边界周，才能保证报表过滤逻辑常年不出错。
java_timeWeekFields报表过滤修改时间：2026-08-16 17:42:35