Go Time.ISOWeek 返回的年份为什么与 Year 不同

如果你发现 t.Year() 和 t.ISOWeek() 返回的年份不同，通常不是 Go 计算错误，而是两个方法回答了不同的问题：Year() 返回日期所在的公历年，ISOWeek() 返回 ISO 8601 规则下的“周所属年”和周号。年初的 1 月 1 日到 1 月 3 日可能仍属于上一年的第 52 或 53 周，年末的 12 月 29 日到 12 月 31 日也可能已经属于下一年的第 1 周。

官方地址：https://pkg.go.dev/time#Time.ISOWeek

周报、按周计费、周维度看板等场景，应当把 ISOWeek() 返回的两个值一起作为周键。不要把 t.Year() 与 ISO 周号拼在一起，否则跨年时会把同一周拆到错误的统计桶里。

先看清两个年份的语义

Time.Year() 只关心当前时间按公历解释后属于哪一年；Time.ISOWeek() 则按 ISO 8601 的周规则返回 year 和 week。ISO 周从星期一开始，第 1 周是包含当年 1 月 4 日的那一周，因此周所属年不一定等于日期显示出来的公历年。

年初年末为什么会跨年

可以把 ISO 周理解成连续的“周块”，而不是把每个公历年的 1 月 1 日强行当成新周的开始。只要某个周块的大部分日期落在上一年或下一年的规则范围内，周所属年就可能与日期的公历年错开。

例如，2021-01-01 的公历年是 2021，但它属于 ISO 2020 年的第 53 周；反过来，某些年份的 12 月 31 日会落在下一 ISO 年的第 1 周。官方文档也特别提示：1 月 1 日到 1 月 3 日可能属于前一年的第 52 或 53 周，12 月 29 日到 12 月 31 日可能属于下一年的第 1 周。

因此，看到下面的输出时不要把它当作异常：

package main

import (
	"fmt"
	"time"
)

func main() {
	// 用 UTC 固定示例，避免本机时区影响这个边界日期的解释。
	t := time.Date(2021, time.January, 1, 12, 0, 0, 0, time.UTC)
	isoYear, week := t.ISOWeek()

	// Year 是公历年；ISOWeek 的第一个返回值是周所属年。
	fmt.Printf("date=%s calendarYear=%d isoYear=%d week=%02d\\n",
		t.Format("2006-01-02"), t.Year(), isoYear, week)
}

date=2021-01-01 calendarYear=2021 isoYear=2020 week=53

基线对照：Year 加周号为什么会错桶

把日期按周聚合时，最容易出现的错误是分别调用 Year() 和 ISOWeek()，然后拼出 2021-W53 这样的键。这个键看起来合理，实际上把公历年 2021 与 ISO 2020 年的第 53 周混在了一起。

这个问题通常不会在年中暴露，因而容易被误认为偶发数据问题。真正需要关注的指标是年边界周的错桶数量：如果统计键来自两个不同的年份语义，跨年周就会被拆散或落入错误的分组。

正确写法：把 ISO 年和周号一起封装

推荐把周键定义成结构体，字段名直接说明语义。这样比把两个整数拼成字符串更不容易在后续维护中误用 Year()。

package main

import (
	"fmt"
	"time"
)

// ISOWeekKey 只表达一个 ISO 周，不混用公历年。
type ISOWeekKey struct {
	Year int
	Week int
}

func weekKey(t time.Time) ISOWeekKey {
	// 两个字段必须来自同一次 ISOWeek 调用，保持同一套周规则。
	year, week := t.ISOWeek()
	return ISOWeekKey{Year: year, Week: week}
}

func main() {
	// 这个日期虽然是公历 2021 年，但周键属于 ISO 2020-W53。
	t := time.Date(2021, time.January, 1, 12, 0, 0, 0, time.UTC)
	key := weekKey(t)

	// 用结构体作为 map 键，避免把公历年误拼到 ISO 周号前面。
	counts := map[ISOWeekKey]int{key: 1}
	fmt.Printf("%04d-W%02d => %d\\n", key.Year, key.Week, counts[key])
}

2020-W53 => 1

回归测试：至少覆盖两侧边界

不要只测试普通日期。测试表至少放入一个 1 月初样例和一个 12 月末样例，并同时断言公历年与 ISO 周所属年。测试的目标是锁定“键由 ISO 年和周号组成”这一业务规则。

package main

import (
	"testing"
	"time"
)

func TestWeekKeyKeepsISOYear(t *testing.T) {
	tests := []struct {
		name string
		date time.Time
		want ISOWeekKey
	}{
		{
			name: "January belongs to previous ISO year",
			date: time.Date(2021, time.January, 1, 12, 0, 0, 0, time.UTC),
			want: ISOWeekKey{Year: 2020, Week: 53},
		},
		{
			name: "ordinary date keeps same year",
			date: time.Date(2021, time.July, 1, 12, 0, 0, 0, time.UTC),
			want: ISOWeekKey{Year: 2021, Week: 26},
		},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// 断言周键整体相等，防止只检查 week 而遗漏 ISO 年。
			if got := weekKey(tt.date); got != tt.want {
				t.Fatalf("weekKey(%s) = %#v, want %#v", tt.date.Format("2006-01-02"), got, tt.want)
			}
		})
	}
}

示例里的普通日期用于对照，真正容易出错的是年初和年末。你的业务如果需要处理更多边界，可以继续补充相邻年份的 12 月 29 日到 1 月 3 日，但不要改变“同一个 ISO 周的年份和周号必须来自同一调用”的原则。

结论与迁移清单

1. 需要公历年份时使用 t.Year()；需要周统计时使用 t.ISOWeek() 返回的两个值。
2. 不要用 t.Year() 和 ISO 周号组合周键，因为它们可能属于不同的年份体系。
3. 推荐使用 ISOWeekKey{Year: isoYear, Week: week} 这类结构体表达键。
4. 回归测试至少覆盖 1 月初的前一年 ISO 周，避免年边界数据进入错误分组。

可以把这条规则记成一句话：日期的公历年看 Year，日期的 ISO 周年看 ISOWeek 的第一个返回值；做周聚合时两个值必须成对使用。

相关问题

ISOWeek 的 week 会超过 52 吗？

会。Go 文档规定周号范围是 1 到 53，某些年份的最后一周就是第 53 周。

只保存 week，不保存 isoYear 可以吗？

不建议。不同年份都会出现第 1 周到第 52 周，单独保存周号无法区分跨年数据；至少要保存 isoYear 和 week。

时区会改变 ISOWeek 的结果吗？

会影响“这个瞬间在当地是哪一天”的解释。本文只讨论公历年与 ISO 周所属年的差异；业务上应先确定时间使用的地点，再对同一地点下的 time.Time 调用 ISOWeek()。