Go time.Parse解析Unix时间与RFC3339的格式选择

时间字段先看协议，再决定解析器。接口给的是 Unix 秒值，就用 time.Unix；给的是带 Z 或数字偏移量的 RFC3339 文本，就用 time.Parse(time.RFC3339, value)。不要把数字时间戳当成布局字符串，也不要把毫秒值直接当秒值。

一、先按输入协议判断时间形态

我在接第三方接口时，最先确认的不是“该用哪个函数”，而是字段契约：1704067200 代表秒，还是 1704067200000 代表毫秒？文本是 2024-01-01T00:00:00Z，还是只给了日期？这一步决定了解析路径。

可以把边界规则压缩成下面这张表：

二、用 time.Parse 解析 RFC3339 文本

time.Parse 的第一个参数是布局，第二个参数是待解析值。RFC3339 同时允许 UTC 的 Z 和带冒号的数值偏移量，所以优先使用标准常量，不要手写一个看起来相近的布局。

package main

import (
    "fmt"
    "time"
)

func parseRFC3339(value string) (time.Time, error) {
    // 标准布局能同时处理 Z 和带冒号的时区偏移。
    parsed, err := time.Parse(time.RFC3339, value)
    if err != nil {
        // 将原始输入留在错误链路中，调用方才能定位协议问题。
        return time.Time{}, fmt.Errorf("解析 RFC3339 时间失败: %w", err)
    }
    // 统一到 UTC 只改变展示位置，不改变时间点。
    return parsed.UTC(), nil
}

如果文本没有时区信息，time.Parse 会按 UTC 解释；这不等于“自动使用服务器时区”。需要把无时区日期当作某个业务地点的本地时间时，改用 time.ParseInLocation，并把地点作为显式配置。

三、用 time.Unix 处理秒值并统一时区

Unix 时间是从 1970-01-01 UTC 起算的整数时间，不需要 time.Parse。Go 还提供 UnixMilli 和 UnixMicro，它们适合协议已经明确单位的场景；如果版本或依赖环境需要兼容，也可以用 time.Unix(sec, nsec) 自己组合。

package main

import (
    "fmt"
    "time"
)

func parseUnixSeconds(raw int64) (time.Time, error) {
    // 这里的参数契约固定为 Unix 秒，毫秒值必须走另一条入口。
    if raw 

四、把选择规则落到接口边界

真正稳妥的做法是让接口层接收已经约定好的字段类型，而不是在业务深处猜测一个数字的单位。若不得不接收混合输入，应同时接收 value 与 unit，解析器只负责执行明确规则，失败就返回错误，不要偷偷回退到当前时间。

type TimeInput struct {
    Value string
    Unit  string // RFC3339、s、ms 或 us
}

func parseInput(input TimeInput) (time.Time, error) {
    // 先按协议分支，禁止用字符串长度猜测单位。
    switch input.Unit {
    case "RFC3339":
        return parseRFC3339(input.Value)
    case "s":
        // 真实项目中应使用 strconv.ParseInt 并返回转换错误。
        return time.Time{}, fmt.Errorf("示例省略字符串到 Unix 秒的转换")
    case "ms", "us":
        return time.Time{}, fmt.Errorf("示例要求为 %s 提供独立单位解析器", input.Unit)
    default:
        return time.Time{}, fmt.Errorf("不支持的时间单位: %s", input.Unit)
    }
}

接口文档至少写清四件事：数字的单位、是否允许负值、文本是否必须带时区、输出是否统一为 UTC。这样调用方看到 parsing time 错误时，能先检查协议而不是盲目更换布局。

相关问题

RFC3339 的 Z 和 +08:00 有什么区别？

它们都携带时区信息，分别表示 UTC 和数值偏移量。解析后可以用 UTC() 统一展示，时间点本身不会因此改变。

为什么 Unix 毫秒值解析后年份不对？

最常见原因是把毫秒整数传给了秒级函数。先确认协议单位，再使用 time.UnixMilli 或拆分为秒与纳秒。

没有时区的字符串应该用哪个函数？

若业务规定它就是 UTC，可用 time.Parse；若它表示某个地区的本地钟表时间，应使用 time.ParseInLocation 显式指定地点。