在指定时区计算自然日窗口并处理夏令时跳变

在 Go 中计算“某个时区的某一天”，正确答案不是把一个时间截断后固定加 24*time.Hour，而是先进入目标时区，取出当地年月日，构造当地零点，再用 AddDate(0, 0, 1) 得到下一日零点。最终采用左闭右开的 [start, end) 区间，并把两个边界转换成 UTC 查询数据库。

Go time 标准库官方地址：https://pkg.go.dev/time

事故症状：同一段查询只在换时日出错

一个按用户时区生成日报的服务，平时查询结果完全正常，到了春季切换夏令时的周日却多带入下一天的一小时；秋季回拨时又漏掉重复出现的一小时。数据库里的时间戳没有损坏，SQL 也没有改变，问题只发生在少数日期。

根因是代码把“自然日”误当成“固定 24 小时”。自然日属于日历语义：从当地某日零点开始，到当地下一日零点结束。绝对持续时间则属于时长语义。在采用夏令时的地区，两者并不总是相等：春季时钟向前跳时可能只有 23 小时，秋季回拨时可能有 25 小时。

Go 的 time 包特意没有提供 Day 常量，因为一个日历日并非总是固定时长。修复的第一步，就是把业务需要的“某地日历边界”和底层存储使用的“绝对时刻”分开。

用日历边界代替固定 24 小时

下面的函数接收任意锚点时刻和 IANA 时区名，返回包含起点、不包含终点的自然日窗口：

package daywindow

import (
    "fmt"
    "time"
)

type DayWindow struct {
    Start time.Time
    End   time.Time
}

func NaturalDayWindow(anchor time.Time, zone string) (DayWindow, error) {
    // 加载完整的地区时区规则，而不是固定偏移量。
    loc, err := time.LoadLocation(zone)
    if err != nil {
        return DayWindow{}, fmt.Errorf("加载时区 %q: %w", zone, err)
    }

    // 保持同一个绝对时刻，只改变它在目标时区中的日历表示。
    local := anchor.In(loc)
    year, month, day := local.Date()

    // 以当地零点作为起点，并按日历推进到下一天零点。
    start := time.Date(year, month, day, 0, 0, 0, 0, loc)
    end := start.AddDate(0, 0, 1)
    return DayWindow{Start: start, End: end}, nil
}

anchor.In(loc) 不会改变绝对时刻，它只把这个时刻换成目标 Location 下的日历表示。随后使用 Date() 取出当地年月日，才能确定用户所说的“今天”究竟是哪一天。

time.Date 负责构造当地零点，AddDate 则按这个 Time 携带的 Location 推进一个日历日。这里绝不能替换成 start.Add(24 * time.Hour)：后者增加的是固定的绝对时长，会在夏令时切换日越过或达不到下一日零点。

采用左闭右开区间

窗口统一表达为 [start, end)，也就是包含起点、不包含下一日零点。不要把结束值改成“23:59:59”，也不要减去一纳秒来制造“当天最后一刻”。不同数据库和字段的时间精度可能是秒、毫秒或微秒，人工制造闭区间很容易出现边界遗漏。

半开区间还有一个直接收益：相邻两天可以无缝拼接。第一天的 end 正好等于第二天的 start，同一个记录不会同时属于两天，也不会落在两个窗口之间。

转换成 UTC 查询数据库

如果数据库按 UTC 保存时间戳，应先在业务时区中算完边界，再把边界转换成 UTC。不要先在 UTC 中截断日期，否则用户所在时区的午夜可能对应 UTC 的前一天或后一天。

window, err := NaturalDayWindow(anchor, "America/New_York")
if err != nil {
    // 调用方决定记录日志、返回参数错误或使用明确的回退策略。
    return err
}

// SQL 使用左闭右开条件，传入的两个参数都是绝对 UTC 时刻。
startUTC := window.Start.UTC()
endUTC := window.End.UTC()
rows, err := db.QueryContext(
    ctx,
    "SELECT id, created_at FROM events WHERE created_at >= ? AND created_at 

转换成 UTC 后，Start 与 End 的显示时区变了，但代表的仍是刚才确定的两个瞬间。这样业务层负责解释“纽约当地这一天”，存储层只负责比较统一的绝对时间。

用跳变日测试 23、24、25 小时

普通日期的测试只会证明最容易的 24 小时情况。至少应加入一个春季跳变日和一个秋季回拨日，并同时断言本地日历边界与绝对时长。以 America/New_York 为例，2026 年 3 月 8 日为春季跳变日，11 月 1 日为秋季回拨日。

func TestNaturalDayWindow(t *testing.T) {
    tests := []struct {
        name string
        zone string
        date string
        want time.Duration
    }{
        // 普通日期仍然是 24 小时。
        {"普通日", "America/New_York", "2026-02-10", 24 * time.Hour},
        // 春季向前跳过一小时，因此自然日只有 23 小时。
        {"春季跳变", "America/New_York", "2026-03-08", 23 * time.Hour},
        // 秋季回拨重复一小时，因此自然日共有 25 小时。
        {"秋季回拨", "America/New_York", "2026-11-01", 25 * time.Hour},
        // UTC 没有夏令时切换，始终是 24 小时。
        {"UTC", "UTC", "2026-03-08", 24 * time.Hour},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            // 用中午作为锚点，避免测试输入本身落在跳变附近。
            loc, err := time.LoadLocation(tt.zone)
            if err != nil {
                t.Fatal(err)
            }
            anchor, err := time.ParseInLocation("2006-01-02 15:04", tt.date+" 12:00", loc)
            if err != nil {
                t.Fatal(err)
            }

            got, err := NaturalDayWindow(anchor, tt.zone)
            if err != nil {
                t.Fatal(err)
            }
            if got.End.Sub(got.Start) != tt.want {
                t.Fatalf("持续时间=%v，期望=%v", got.End.Sub(got.Start), tt.want)
            }
            if got.Start.Hour() != 0 || got.End.Hour() != 0 {
                t.Fatalf("边界必须是当地零点：%v 至 %v", got.Start, got.End)
            }
        })
    }
}

测试的关键不是只比较 Sub 结果，还要确认起点与终点都处于同一个目标 Location 的当地零点。这样才能同时验证“日历边界正确”和“绝对时长允许变化”两个性质。

部署时保留完整时区规则

地理时区必须使用类似 Asia/Shanghai、Europe/Zurich、America/New_York 的 IANA 名称。time.FixedZone 只表示固定偏移量，不包含历史和未来的夏令时规则，因此不适合表达一个会调整时钟的地区。

极简容器中如果没有系统 zoneinfo，LoadLocation 可能失败。可在程序中引入 Go 随附的时区数据库：

import (
    // 把 IANA 时区数据库嵌入程序，避免依赖宿主机 zoneinfo。
    _ "time/tzdata"
)

序列化时也要注意：很多时间格式会保留数值偏移，却不会保留完整 Location 名称和未来规则。若业务需要日后按同一地区重新计算自然日，应单独保存 IANA 时区名，而不是只保存当时的 -05:00 或 -04:00。

复盘：把规则固定在一个边界函数里

这次故障的表面现象是“换时日差一小时”，真正根因是把日历语义与持续时间语义混在了一起。修复后，所有日报、账单、统计和清理任务都应复用同一个自然日窗口函数，不再各自拼接 24 小时。

最终检查清单很短：输入必须带明确目标时区；边界必须在该 Location 中构造；结束值必须由 AddDate 产生；查询必须使用 >= start AND ；存储层比较前再转换 UTC；测试必须覆盖 23、24、25 小时三种日期。只要这六点一致，夏令时就不再是一个靠运气躲过的边界条件。

相关问题

为什么不能直接使用 time.Truncate(24*time.Hour)？

Truncate 按绝对持续时间对齐，不理解某个 Location 的当地午夜。目标时区不是 UTC 时，它通常不会得到用户自然日的零点。

为什么不用当天 23:59:59 作为结束值？

数据库字段精度不一致，秒级结束值会漏掉更细粒度的记录。使用下一日零点作为排他上界，与精度无关，也能让相邻窗口无缝衔接。

只保存 UTC 偏移量够不够？

不够。固定偏移量不能表达未来的夏令时切换规则。需要重新计算地区自然日时，应保存 IANA 时区名，并通过 LoadLocation 恢复规则。

不存在或重复的当地时间该怎么处理？

跳变附近的任意墙上时间可能不存在或出现两次。自然日边界应优先使用当地零点；若业务还要解释用户输入的 02:15 等具体时间，则必须另行制定歧义和缺失时间策略，不能只依赖一个固定偏移。