Go time.Time JSON 格式不符合接口约定的适配方式

Go 的 time.Time 默认 JSON 表示与接口约定不一致时，应在接口 DTO 上使用独立命名时间类型，并实现 MarshalJSON；接口也接收这种时间时，再配套实现 UnmarshalJSON。不要试图用字段标签里的格式字符串改掉 time.Time 的序列化规则，也不要全局替换 JSON 文本。

官方地址：https://pkg.go.dev/time

例如，一个接口明确要求 "2030-04-18 02:25:00"，而不是带 T 和时区偏移的表示。真正需要适配的不只是标点，还包括这串数字采用哪个时区、是否允许小数秒，以及未提供时间该用什么值。

把接口时间规则写成四项明确约定

time.Time.MarshalJSON 官方文档说明默认 JSON 是带引号的 RFC 3339 时间字符串，并支持小数秒。换成自定义格式意味着接口必须另外承担丢失的信息，特别是没有时区偏移的字符串。

这是一套示例接口契约，不是所有 Go 项目的统一标准。若你能控制新接口，保留明确偏移的标准时间格式通常能减少歧义；如果必须对接既有格式，就把解释规则写进字段说明，不能只贴一条示例字符串。

用命名类型接管JSON编码和解码

实现分为三层：WireTime 保存时间值；MarshalJSON 和 UnmarshalJSON 处理 JSON 边界；wireLayout 与 UTC 共同定义文本含义。NoticeDTO 只负责字段组合。完整程序如下，可以放入独立 main.go 阅读或自行运行；下文结果为代码推导，本文不声称已经执行。

package main

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

const wireLayout = "2006-01-02 15:04:05"

// WireTime 是独立定义类型，不嵌入 time.Time，避免提升其其他方法。
type WireTime time.Time

func (w WireTime) MarshalJSON() ([]byte, error) {
    t := time.Time(w)
    // 本接口把零时间约定为缺失值，输出 JSON null 而不是空字符串。
    if t.IsZero() {
        return []byte("null"), nil
    }
    t = t.UTC()
    // 不静默丢弃精度；调用方应先决定是否允许截断小数秒。
    if t.Year()  9999 || t.Nanosecond() != 0 {
        return nil, fmt.Errorf("时间必须是1至9999年范围内的UTC整秒值")
    }
    // 让标准编码器生成带引号的JSON字符串，不能返回裸时间文本。
    return json.Marshal(t.Format(wireLayout))
}

func (w *WireTime) UnmarshalJSON(data []byte) error {
    if w == nil {
        return fmt.Errorf("时间接收目标不能为nil")
    }
    if bytes.Equal(bytes.TrimSpace(data), []byte("null")) {
        *w = WireTime(time.Time{})
        return nil
    }
    var text string
    // 先解析JSON字符串，正确处理转义；数字和布尔值等类型会报错。
    if err := json.Unmarshal(data, &text); err != nil {
        return fmt.Errorf("时间字段必须是字符串或null: %w", err)
    }
    if len(text) != len(wireLayout) {
        return fmt.Errorf("时间格式必须为YYYY-MM-DD HH:mm:ss")
    }
    parsed, err := time.ParseInLocation(wireLayout, text, time.UTC)
    if err != nil {
        return fmt.Errorf("时间内容无效: %w", err)
    }
    // 往返比对收紧可接受写法，同时保留零时间给null使用。
    if parsed.Format(wireLayout) != text || parsed.Year() 

其中 type WireTime time.Time 是新定义类型，不是 type WireTime = time.Time 别名。它不直接继承原类型的方法集，调用 time.Time 的方法时先显式转换。编码方法使用值接收者，解码方法使用指针接收者，两者都针对本文自己的类型。

encoding/json 的自定义编码接口提供了这种接入点。MarshalJSON 返回值必须是一段有效 JSON；Format 的结果只是文本，因此代码再调用 json.Marshal 编码该 string。手工用双引号拼接容易漏掉转义，也容易让“返回 JSON”误变成“返回普通文本”。

用一个完整DTO例子说明时区和结果

main 中的原时刻为东八区10:25，编码规则统一成 UTC，因此 sent_at 的预期文本是当天02:25。In 或 UTC 选择的是同一时刻的展示方式；直接给时间加减八小时会改变时刻，不能拿它代替时区转换。

程序第一行预期为以下 JSON，第二行预期为 true。这里输入恰好为整秒，因而解码后可以用 Equal 比较同一时刻；若接口主动丢失小数精度，就不能继续承诺与原始高精度时刻完全相同。

{"id":"N-42","sent_at":"2030-04-18 02:25:00"}

JSON 中 id 是示例标识，sent_at 按前面的契约解释为 UTC。不要把它送给一个只接受本地时间或 RFC 3339 的解析器后，再期待对方自行猜出正确规则。这个字符串本身没有携带 UTC 标记，依赖的是接口文档与配套解码器。

UnmarshalJSON 使用临时 parsed 值，只有全部条件满足才赋回接收者。但这不意味着整个 DTO 的解码具有事务回滚能力：一个对象其他字段可能先被赋值，之后时间字段才出错。因此请求入口应先解码到全新局部 DTO，错误时整体拒绝，不要继续使用部分对象。

按接口差异选择精度、空值与字段策略

本文类型把零时间、JSON null 归在同一个业务状态；空字符串则明确报错。缺少 sent_at 字段时，自定义解码方法不会替你做必填判断，全新 DTO 会保留字段零值。若需要区分“字段未出现”“显式清空”和“实际时间”，应另建带存在状态的请求模型，而不是让一个时间零值同时表达三个含义。

输入边界中的 JSON 字符串、JSON null、空字符串，与存储边界中的 WireTime、零时间、错误结果，需要分别理解。null 会重置为零时间；空字符串属于错误输入，不写入接收值；有效字符串经过格式和 UTC 规则解析后才成为 WireTime。

如需业务时区，应把 UTC 替换成已经成功加载且非 nil 的显式 Location，并保证编码与解码采用同一约定。不要在 MarshalJSON 内每次临时读取系统时区，也不要忽略 LoadLocation 的错误。本例选用 UTC，不需要引入额外时区数据，不能由此推导其他地区的无偏移时间永远无歧义。

如需毫秒，可以另定义明确精度的协议类型。修改布局同时要更新长度规则、精度检查和往返约定，不能只把 .000 加进格式后留下“非零纳秒全部拒绝”的旧条件。对于 Unix 时间戳，应另约定数字类型和秒/毫秒单位，不能让同一个字段时而字符串、时而数字。

排除递归调用和方法提升等常见误区

整个类型应放在接口适配层，而不是无差别替换领域模型中的所有 time.Time。两个接口若格式不同，可以有两个各自命名的协议类型，避免用全局可变 layout 在并发请求中切换规则。复制这段程序之前，先确认自己的接口是否真的采用 UTC、整秒与 null 三项约定。

只改 JSON tag 能指定日期布局吗？

标准 encoding/json 的字段标签不是 time.Time 的日期格式配置。格式属于类型的编码行为或 DTO 组装行为，字段名映射与时间格式应分开处理。

只需要输出，不接收请求，也要写解码方法吗？

不必。只读响应可只实现编码，也可以在组装响应时把时间明确格式化成 string。本文双向类型是为了让同一协议的输入输出规则成对可见，不是要求所有响应类型都支持反序列化。

为什么不让空字符串也等于 null？

可以选择兼容，但那是接口决策，不是标准库强制。本文拒绝空字符串，便于区分合法缺失与上游格式错误；若业务必须兼容，应在协议说明与例子中明确，而不是悄悄吞掉错误。

适配的关键是把格式、时区、精度与缺失状态一起固定下来。只改变日期外观，而没有一致的解码与错误规则，通常会把一个序列化问题变成下一次接口对接歧义。