统一序列化业务时间、持续时长与数据库时间戳

我见过最难排查的一类时间问题，不是“不会用 time.Time”，而是同一个接口里同时出现三套规则：创建时间是本地时区字符串，超时时长是一个没有单位的整数，数据库的完成时间又可能是 NULL。代码每一行都能运行，调用方却必须靠猜。

这篇文章从零搭一个小型任务接口，只保留三条约定：业务时刻用 time.Time，持续时长用 time.Duration，数据库可空时间用 sql.NullTime。对外 JSON 统一输出 UTC 时间和可读的 Duration 字符串，所有转换集中在 DTO 与仓储边界。

先把三种时间语义分开

time.Time 表示“某个时刻”，time.Duration 表示“两点之间的长度”，两者不能因为都能转成整数就共用一套协议。Go 标准库把 Duration 定义为纳秒计数的 int64，所以直接交给 encoding/json 会得到一个数字；这个数字没有字段后缀时，调用方无法判断它是秒、毫秒还是纳秒。

time.Time 已实现 JSON 编解码，适合保留为类型而不是提前变成字符串。还有一个容易被忽略的边界：进程内的 time.Now() 可能携带单调时钟读数，但 JSON、文本与二进制序列化不会保留它。跨进程传输的应该是墙上时钟表示，而不是进程内测量信息。

先做一个可复用的 Duration JSON 类型

我的做法是给接口层定义一个很薄的包装类型：编码时调用 Duration.String()，解码时调用 time.ParseDuration。这样协议天然携带单位，也能复用 Go 已有的解析规则。

package api

import (
	"encoding/json"
	"time"
)

type JSONDuration time.Duration

func (d JSONDuration) MarshalJSON() ([]byte, error) {
	// 输出带单位的字符串，避免把底层纳秒数泄漏到接口协议。
	return json.Marshal(time.Duration(d).String())
}

func (d *JSONDuration) UnmarshalJSON(data []byte) error {
	// 先按 JSON 字符串读取，再交给标准库解析 500ms、2s 等格式。
	var raw string
	if err := json.Unmarshal(data, &raw); err != nil {
		return err
	}
	parsed, err := time.ParseDuration(raw)
	if err != nil {
		return err
	}
	*d = JSONDuration(parsed)
	return nil
}

如果既有协议必须使用整数，也不要叫 timeout 后让人猜单位，至少写成 timeout_ms，并在边界处调用 Milliseconds()。字符串和显式后缀整数都可以，最怕的是同一系统里混着用。

定义领域模型、数据库行和接口 DTO

接下来把三层结构体拆开。领域对象只表达业务事实；数据库行负责接住可空列；DTO 负责协议格式。多写两个小结构体，换来的是每一层都不再背负其他层的特殊情况。

package task

import (
	"database/sql"
	"time"
)

type Task struct {
	ID        int64
	CreatedAt time.Time
	Timeout   time.Duration
	DoneAt    *time.Time
}

type taskRow struct {
	ID        int64
	CreatedAt time.Time
	TimeoutMS int64
	DoneAt    sql.NullTime
}

type TaskDTO struct {
	ID        int64        `json:"id"`
	CreatedAt time.Time    `json:"created_at"`
	Timeout   JSONDuration `json:"timeout"`
	DoneAt    *time.Time   `json:"done_at"`
}

数据库中的持续时长列这里明确命名为 timeout_ms，因为很多数据库没有统一的 Duration 类型。时刻列仍交给驱动读写 time.Time，避免把数据库会话时区、字符串格式与业务代码绑在一起。

把转换收口到仓储边界

过去我会在 handler、SQL 和日志里各写一次时间转换，修复一个时区问题后另外两处仍然旧样。更稳妥的方式是只保留两个映射函数：数据库行转领域对象，领域对象转接口 DTO。

func rowToTask(row taskRow) Task {
	var doneAt *time.Time
	if row.DoneAt.Valid {
		// 复制值，避免把 sql.NullTime 的持久层语义带进领域层。
		value := row.DoneAt.Time
		doneAt = &value
	}
	return Task{
		ID:        row.ID,
		CreatedAt: row.CreatedAt,
		Timeout:   time.Duration(row.TimeoutMS) * time.Millisecond,
		DoneAt:    doneAt,
	}
}

func toDTO(task Task) TaskDTO {
	var doneAt *time.Time
	if task.DoneAt != nil {
		// 对外统一成 UTC；UTC() 也会去掉进程内单调时钟读数。
		value := task.DoneAt.UTC()
		doneAt = &value
	}
	return TaskDTO{
		ID:        task.ID,
		CreatedAt: task.CreatedAt.UTC(),
		Timeout:   JSONDuration(task.Timeout),
		DoneAt:    doneAt,
	}
}

写数据库时同样保持类型：ExecContext 的参数传 time.Time 或 nil，不要先 Format。读数据库时让 Scan 把普通时间列放进 time.Time，把可空时间列放进 sql.NullTime。数据库驱动和列类型仍需在项目中确认，但转换位置不应该散落。

用往返测试锁住协议

这类代码最值得测试的不是“能不能 Marshal”，而是 Marshal 后再 Unmarshal，时刻和时长是否保持同一语义，空时间是否仍是空。测试里用 Time.Equal 比较时刻，不要直接用 ==，因为后者还会比较 Location 与单调时钟等内部信息。

func TestTaskDTORoundTrip(t *testing.T) {
	want := TaskDTO{
		ID:        7,
		CreatedAt: time.Date(2026, 10, 8, 3, 0, 0, 0, time.UTC),
		Timeout:   JSONDuration(1500 * time.Millisecond),
		DoneAt:    nil,
	}

	// 先编码再解码，验证协议而不是只验证某一个方法。
	data, err := json.Marshal(want)
	if err != nil {
		t.Fatal(err)
	}
	var got TaskDTO
	if err := json.Unmarshal(data, &got); err != nil {
		t.Fatal(err)
	}

	// Equal 比较同一时刻；Duration 直接比较纳秒语义。
	if !got.CreatedAt.Equal(want.CreatedAt) || got.Timeout != want.Timeout || got.DoneAt != nil {
		t.Fatalf("round trip mismatch: %#v", got)
	}
}

接入现有项目时的检查顺序

1. 先列出所有时间字段，给每个字段标记“时刻、日期、时长、可空时刻”中的一种。
2. 冻结对外协议：时刻统一 UTC，时长统一字符串或带单位后缀的整数。
3. 让 SQL 只处理数据库类型，让 Mapper 负责 sql.NullTime、毫秒列和领域对象的转换。
4. 为非整秒时长、非 UTC 输入、NULL 时间和闰日各留一个测试样例。

官方参考：https://pkg.go.dev/time、https://pkg.go.dev/encoding/json、https://pkg.go.dev/database/sql。这套设计没有发明新的时间格式，而是把标准库已有能力放回正确边界。代码量不大，但以后看到 created_at、timeout 和 done_at 时，调用方不再需要猜。