Go JSON 时间字段不是 RFC3339 格式时怎么解析

接口把时间写成 2026-09-06 14:30:00，而 Go 结构体字段却声明成 time.Time，反序列化时报 cannot parse，原因通常不是 JSON 坏了，而是格式契约不一致。标准库的 time.Time.UnmarshalJSON 只接受带引号的 RFC3339 字符串；遇到旧接口的空格分隔时间，应先接收字符串，再用明确的 layout 解析。

为什么 time.Time 读不了非 RFC3339 时间

encoding/json 发现目标字段实现了 json.Unmarshaler，就会把该字段交给它处理。time.Time 已经实现了 UnmarshalJSON，它要求输入是带引号的 RFC3339，例如 2026-09-06T14:30:00+08:00。下面这段 JSON 语法完全正确，但时间布局不符合标准库的约定：

{"created_at":"2026-09-06 14:30:00"}

所以要先判断错误发生在哪一层：若提示 JSON syntax error，是 JSON 语法问题；若提示 parsing time，通常是字符串已经取到了，但布局、时区或小数秒部分不匹配。

固定格式先接收字符串，再按样例写 layout

如果上游格式稳定，最容易维护的做法是把传输对象的时间字段声明为 string，在转换函数中显式解析。Go 的 layout 不是抽象的“年-月-日”模板，而是用参考时间 2006-01-02 15:04:05 写出目标样子。

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type payload struct {
	CreatedAt string `json:"created_at"`
}

func main() {
	data := []byte(`{"created_at":"2026-09-06 14:30:00"}`)
	var in payload
	if err := json.Unmarshal(data, &in); err != nil {
		// JSON 结构错误应在这里直接返回，避免继续使用半成品数据。
		panic(err)
	}

	createdAt, err := time.Parse("2006-01-02 15:04:05", in.CreatedAt)
	if err != nil {
		// layout 不匹配时保留原始错误，便于定位上游契约变化。
		panic(err)
	}
	fmt.Println(createdAt.Format(time.RFC3339))
}

这段代码把“接收成功”和“时间有效”分成两步，错误位置更清楚。注意：没有时区的字符串被 time.Parse 按 UTC 解释；如果业务约定它实际是东八区，应使用 time.ParseInLocation，并把这个决定写进接口说明。

用自定义类型把格式约束放在字段边界

当同一种非标准格式在多个请求中重复出现，可以定义 FlexTime。它让结构体继续拥有时间语义，同时把字符串布局、空字符串策略和错误包装集中到一个地方：

type FlexTime struct {
	time.Time
}

func (t *FlexTime) UnmarshalJSON(data []byte) error {
	var raw string
	if err := json.Unmarshal(data, &raw); err != nil {
		// 先确认输入是 JSON 字符串，不把 null 或数字悄悄当日期。
		return fmt.Errorf("created_at must be a string: %w", err)
	}
	if raw == "" {
		// 空值是否允许是业务决策；这里选择保留零值并接受它。
		t.Time = time.Time{}
		return nil
	}
	parsed, err := time.ParseInLocation("2006-01-02 15:04:05", raw, time.FixedZone("CST", 8*60*60))
	if err != nil {
		// 包装字段名和原始错误，日志里能直接看出哪种格式失配。
		return fmt.Errorf("parse business time %q: %w", raw, err)
	}
	t.Time = parsed
	return nil
}

示例中的固定时区只是演示，生产代码应依据上游合同选择 Asia/Shanghai、UTC 或带偏移的输入。若字段表示“某天”而不是时间点，更适合保留 string 或定义只包含日期的类型，避免给它附会一个没有业务依据的午夜时刻。

多个格式和上线排查怎么做

如果确实要兼容两个历史格式，可以只列出允许的 layout，并按明确顺序尝试；不要使用“删掉非数字字符”之类的宽松清洗，因为它会把时区和日月顺序错误变成看似成功的时间。

func parseLegacyTime(value string) (time.Time, error) {
	layouts := []string{
		"2006-01-02 15:04:05",
		"2006/01/02 15:04:05",
	}
	for _, layout := range layouts {
		// 只允许已登记的历史格式，避免无边界猜测。
		if parsed, err := time.ParseInLocation(layout, value, time.UTC); err == nil {
			return parsed, nil
		}
	}
	return time.Time{}, fmt.Errorf("unsupported time format: %q", value)
}

上线前至少核对四件事：字段是否可能为 null 或空字符串；没有偏移时默认哪个时区；小数秒是否存在以及精度上限；解析后的值再序列化时是否要统一输出 RFC3339。最后用表驱动测试覆盖每一种合法样例和一种故意非法样例，避免上游改成斜杠、丢秒或改变时区后才在生产日志里发现。

常见问题

把 layout 写成 yyyy-MM-dd 为什么不行？

Go 使用固定参考时间表示布局，正确写法是 2006-01-02；yyyy-MM-dd 会被当成普通字符。

只缺少时区时，应该用 UTC 还是本地时区？

没有统一答案。按接口契约选择；若契约没有说明，应先推动上游补充时区，而不是在代码里依赖部署机器的本地时区。

能不能直接把字段改成 interface{}？

可以暂存原始数据，但会把格式判断推迟到业务各处，通常不如字符串加集中解析，或自定义时间类型清晰。

判断这类问题的关键，不是寻找一个“万能时间解析器”，而是先确认字段代表日期还是瞬时刻，再把允许的字符串格式和时区写成代码边界。这样即使上游暂时不能改成 RFC3339，Go 服务也能稳定接入并在契约变化时快速报错。