timeutil —— 统一东八区的时间工具
time.Now()拿的是服务器本地时区。容器里通常是 UTC, 于是"今日"跨天点跟业务预期差 8 小时 —— 报表口径、每日重置、冷却期判断全都会偏。
功能
timeutil 提供三个函数 + 一个时区常量,把"业务时间"统一到东八区:
| 符号 | 说明 |
|---|---|
timeutil.AsiaShanghai |
固定东八区时区(time.FixedZone("CST", 8*3600)) |
timeutil.Now() |
当前时间(东八区) |
timeutil.Today() |
今日,"2006-01-02" 字符串 |
timeutil.ParseShanghai(layout, value) |
按东八区解析时间串 |
不解决:时区配置(东八区是写死的)、定时任务调度(在 cronx,
那边有独立的 job.timezone 配置)。
配置
本包无 yaml 配置 —— 东八区是写死的常量。
注:定时任务那一层的时区是可配的(
job.timezone,默认Asia/Shanghai, 见configs/config.example.yaml),与本包不是同一套东西。
使用方法
now := timeutil.Now() // 东八区的时间点
today := timeutil.Today() // "2026-11-01"
t, err := timeutil.ParseShanghai("2006-01-02 15:04:05", "2026-11-01 08:30:00")
// t.Format(time.RFC3339) == "2026-11-01T08:30:00+08:00"
跨时区比较:同一时刻,UTC 和东八区表示不同,但 unix 时间戳相同。
t.Unix() // 同一个数
t.UTC().Format("2006-01-02 15:04:05")
存量数据里那些不带时区的时间串,按东八区口径解释:
t, err := timeutil.ParseShanghai("2006-01-02 15:04:05", raw)
模型层已经在用这套口径(internal/model/time.go 的 MarshalJSON /
UnmarshalJSON 都按 timeutil.AsiaShanghai 换算)。
完整示例见 examples/timeutil/main.go。
注意事项
- ⚠️
AsiaShanghai是time.FixedZone,不是time.LoadLocation("Asia/Shanghai")。 固定偏移 +8,不带历史时区规则(中国自 1991 年起无夏令时,所以实际上无差别); 但它也不会读 tzdata。 - ⚠️
Today()返回的是字符串,不是time.Time。 要拿"今日零点"做时间比较,得自己timeutil.ParseShanghai("2006-01-02", timeutil.Today())。 - ⚠️
ParseShanghai只在"输入不带时区"时才是东八区。time.ParseInLocation的语义是:输入串里带了偏移量就以它为准, 没带才用AsiaShanghai。传 RFC3339(带Z或+08:00)进去,结果是那个偏移量, 不是东八区。 - ⚠️
Now()是"时间点 + 固定时区",不是把 UTC 换算一下。Now().UTC()与Now()是同一个瞬间的两种表示 —— 存库 / 传输用time.Time本来就带时区,别手动Format成不带时区的字符串再存。 - ⚠️ 本包不提供格式化函数。要"东八区的
2006-01-02 15:04:05"得自己timeutil.Now().Format("2006-01-02 15:04:05")(先Now()拿到东八区时间点)。 - ⚠️ 别把本包和定时任务的时区混为一谈。
cronx/job有自己的job.timezone配置(缺省会告警),改那个不影响本包,反之亦然。