Go time.Parse 为什么不能写 YYYY-MM-DD：layout 要用 2006-01-02

接口收到 2026-07-17 这样的日期字符串，很多人会顺手写 time.Parse("YYYY-MM-DD", raw)，然后得到一条看起来很别扭的解析错误。根因不在日期本身，而在 Go 的 layout 不是 YYYY、MM 这类格式符；它要求你用参考时刻里的 2006-01-02 来描述年、月、日的位置。

先看错误：YYYY 被当成了普通文本

例如订单筛选接口把查询参数直接送入 time.Parse：

raw := "2026-07-17"
day, err := time.Parse("YYYY-MM-DD", raw)
if err != nil {
    log.Printf("日期解析失败: %v", err)
}
_ = day

这里先别怀疑调用方传错了日期。layout 里的 Y、M、D 并不是 Go 认识的占位写法，解析器会把它们当作需要原样出现的字符。输入是数字日期，自然无法匹配字面量 YYYY-MM-DD。

最小修复：把参考时刻写成目标形状

Go 用一个固定参考时刻表达 layout：年是 2006，月是 01，日是 02，24 小时制小时是 15，分钟和秒分别是 04、05。要解析纯日期，就只保留需要的部分。

const dateLayout = "2006-01-02"

func parseOrderDay(raw string) (time.Time, error) {
    return time.Parse(dateLayout, raw)
}

day, err := parseOrderDay("2026-07-17")
if err != nil {
    return err
}
fmt.Println(day.Format(dateLayout)) // 2026-07-17

这个写法的判断标准很短：先把参考时刻按你想要的文本顺序写一遍，再把那串文字作为 layout。常见的几种形状也可以这样记。

如果项目使用固定协议格式，优先复用标准库里的 time.RFC3339 等常量；只有业务格式确实不同，才自定义一条常量。这样筛选接口、导入任务和测试不会各自留一份近似但不相同的字符串。

能解析不代表业务日期没有偏移

日期没有时区时，另一个更隐蔽的问题才会出现。time.Parse 对缺少时区的信息按 UTC 生成 time.Time。如果 2026-07-17 表示的是上海业务日，而后续又转换到本地时区展示，日期边界附近就可能让页面和报表出现前一天或后一天。

const dateLayout = "2006-01-02"

func parseShanghaiDay(raw string) (time.Time, error) {
    loc, err := time.LoadLocation("Asia/Shanghai")
    if err != nil {
        return time.Time{}, err
    }
    return time.ParseInLocation(dateLayout, raw, loc)
}

这里的选择要由字段语义决定：日志时间戳、接口约定的 UTC 时间可以保留 time.Parse；门店营业日、对账日、预约日期这类“某地日历上的一天”，更适合用 time.ParseInLocation 明确地点。不要只因为本机时区恰好正确，就把这个选择留给部署环境。

解析报错时，先打印 layout 和 value 的差异

time.Parse 的错误通常已经给出了有用线索，但日志只写一个“日期无效”会丢掉关键上下文。短期排查时，可以识别 time.ParseError，把布局和输入中无法对应的片段记下来；不要把完整的用户敏感字段原样写进日志。

func logDateError(err error) {
    var parseErr *time.ParseError
    if errors.As(err, &parseErr) {
        log.Printf(
            "日期格式不匹配: layout=%q value=%q layoutElem=%q valueElem=%q",
            parseErr.Layout,
            parseErr.Value,
            parseErr.LayoutElem,
            parseErr.ValueElem,
        )
        return
    }
    log.Printf("日期处理失败: %v", err)
}

如果输入来自表单或 CSV，建议在进入业务逻辑前先限定允许的日期形状，并把前端提示写成 YYYY-MM-DD 这种用户熟悉的展示格式。注意：这只是给用户看的规则；Go 代码内部仍使用 2006-01-02。

用一组测试把日期和时区边界锁住

日期解析的回归测试不必做得很大。最小一组至少覆盖正确日期、错误形状和业务时区。这样改动输入校验或迁移部署时，能立刻看出是 layout 变了还是地点解释变了。

func TestParseShanghaiDay(t *testing.T) {
    got, err := parseShanghaiDay("2026-07-17")
    if err != nil {
        t.Fatal(err)
    }
    if got.Format(dateLayout) != "2026-07-17" {
        t.Fatalf("日期 = %s", got.Format(dateLayout))
    }
    if got.Location().String() != "Asia/Shanghai" {
        t.Fatalf("地点 = %s", got.Location())
    }

    if _, err := parseShanghaiDay("2026/07/17"); err == nil {
        t.Fatal("错误分隔符应解析失败")
    }
}

第一项确认日历文本没有变，第二项确认业务地点没有悄悄回落到 UTC，第三项拒绝不符合协议的分隔符。只有这三项都过，日期字段才适合再进入库存、对账或预约等后续逻辑。

延伸问答

为什么 Go 不采用 YYYY-MM-DD？

Go 选择用固定参考时刻来描述 layout，而不是用一组抽象格式符。只要记住 2006-01-02 15:04:05，大多数自定义日期格式都能直接写出来。

日期字段一定要用 ParseInLocation 吗？

不一定。带明确时区的协议时间戳通常按协议解析即可；没有时区、但语义属于某地日历日的字段，才应明确指定地点。

time.DateOnly 能替代手写 layout 吗？

如果项目使用的 Go 版本提供该常量，time.DateOnly 可以表达 2006-01-02。团队仍应统一使用一种写法，避免同一协议在不同包里出现多份格式字符串。

日期输入里有空格要先 TrimSpace 吗？

接口协议若不允许空格，直接拒绝能更早发现调用方问题；表单输入若允许用户前后留空，再在边界层清理并保留原始值的审计策略会更合适。

日期格式写对后，再决定它属于哪个时区

修复 YYYY-MM-DD 只是第一步。把 layout 换成 2006-01-02 后，还要确认这个字段究竟是 UTC 时间点还是某地的日历日期。格式和时区都在代码里写明，日期解析才不会在迁移环境或跨时区用户出现时留下隐性偏移。