Go time.DateOnly 怎样统一只保留日期的文本格式

先给结论：如果字段只需要日期，不要在每个调用点手写布局字符串，直接统一使用 time.DateOnly。它代表 2006-01-02，可以同时传给 Time.Format 和 time.Parse，让输出和输入都稳定为 YYYY-MM-DD。

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

这篇只处理日期文本的格式化、解析和输入错误，不把日期格式化等同于时区换算。解析没有时区的日期时，Go 会返回 UTC 位置的 time.Time；如果业务需要某个地区的日历语义，还要单独设计位置规则。

一、先确认 DateOnly 解决的是什么问题

Go 的时间布局使用参考时间表达格式，time.DateOnly 已经把常见的日期布局固定成 2006-01-02。使用它的价值不只是少写几个字符，更重要的是让同一个字段的读写规则保持一致。

下面的关系可以作为排查基准：

二、格式化：把 time.Time 稳定输出为日期

格式化时应先明确时间值代表哪个日期，再调用 Format。如果原值带有时区，Format 会按照当前 time.Time 所在位置对应的年月日输出，因此跨午夜时不要把它误判成单纯的字符串问题。

package main

import (
	"fmt"
	"time"
)

func main() {
	beijing := time.FixedZone("CST", 8*60*60)
	t := time.Date(2026, time.November, 7, 23, 30, 0, 0, beijing)

	// DateOnly 固定输出年月日，避免调用点各写一套布局字符串。
	dateText := t.Format(time.DateOnly)
	fmt.Println(dateText)

	// 需要按另一个时区确定“是哪一天”时，先显式转换，再格式化。
	fmt.Println(t.UTC().Format(time.DateOnly))
}

这里的两个结果可能不同：第一个按 CST 位置得到本地日期，第二个按 UTC 位置重新确定日期。DateOnly 只负责“怎样写日期”，不负责“日期应该取哪个时区”。

三、解析：用同一常量读取 YYYY-MM-DD

读取表单、CSV 或 JSON 中的日期字段时，把布局和输入一起传给 time.Parse。解析函数返回值和错误，不能只接收前一个结果，否则非法日期会被静默当成零值继续流转。

package main

import (
	"fmt"
	"time"
)

func parseDate(value string) (time.Time, error) {
	if value == "" {
		return time.Time{}, fmt.Errorf("date is required")
	}

	// Format 与 Parse 共用 DateOnly，保证读写规则不会悄悄分叉。
	t, err := time.Parse(time.DateOnly, value)
	if err != nil {
		return time.Time{}, fmt.Errorf("parse date %q: %w", value, err)
	}
	return t, nil
}

func main() {
	for _, input := range []string{"2026-11-07", "2026-02-30"} {
		t, err := parseDate(input)
		if err != nil {
			fmt.Println("invalid:", err)
			continue
		}
		fmt.Println("valid:", t.Format(time.DateOnly))
	}
}

没有时区字段时，time.Parse 会把结果放在 UTC。对“生日、账期日、自然日”这类业务字段，通常应把它当作日期数据使用，不要随意调用 In 后再把它解释成某个瞬时点。

四、输入异常时按顺序排查

遇到解析失败时，先把问题归类，不要一上来修改布局。常见原因是空字符串、输入包含时间部分、分隔符不同，或日期本身不存在。

func validateDateInput(value string) error {
	if value == "" {
		return fmt.Errorf("empty date")
	}

	// DateOnly 只接受日期部分；带时间或带时区的输入应使用对应布局。
	if _, err := time.Parse(time.DateOnly, value); err != nil {
		return fmt.Errorf("date must match YYYY-MM-DD: %w", err)
	}
	return nil
}

例如 2026/11/07 的分隔符不匹配，2026-11-07T09:00:00Z 额外带了时间和时区，2026-02-30 则不是有效的公历日期。它们应分别修正输入协议，而不是把 DateOnly 换成一个更宽松的布局。

五、封装日期字段的读写入口

当同一个字段在多个接口中出现时，可以封装成一个小类型。这样格式化、解析和错误边界都集中在一起，调用方不必重复记忆布局字符串。

type DateOnly struct {
	time.Time
}

func NewDateOnly(value string) (DateOnly, error) {
	// 入口统一校验日期文本，调用方只接收合法的日期值。
	t, err := time.Parse(time.DateOnly, value)
	if err != nil {
		return DateOnly{}, fmt.Errorf("invalid date %q: %w", value, err)
	}
	return DateOnly{Time: t}, nil
}

func (d DateOnly) String() string {
	// 零值也遵循同一输出规则，避免不同页面出现不同格式。
	return d.Time.Format(time.DateOnly)
}

如果需要接入 JSON，可在这个类型上实现 MarshalJSON 和 UnmarshalJSON，仍然复用 time.DateOnly。实现时要保留输入错误，不能为了“兼容更多格式”而无提示地接受多个日期协议。

六、常见误区与处理结果

七、常见追问

time.DateOnly 和自己写 "2006-01-02" 有什么区别？

输出效果相同，但常量更容易表达字段意图，也能让格式化和解析统一引用同一个布局。团队代码中不必到处搜索同一字符串。

Parse(time.DateOnly, value) 会校验日期是否真实存在吗？

会按布局解析年月日，并拒绝不合法的日期组合，例如二月不存在的日期。它不负责校验业务上的节假日、账期或时区策略。

日期字段应该保存成 time.Time 还是字符串？

取决于边界。进入业务层后通常使用 time.Time 或专门的日期类型；在接口和文件边界上使用 YYYY-MM-DD 文本，并通过 DateOnly 统一转换。

总结：把 time.DateOnly 当作日期字段的单一布局入口，输出使用 Format，输入使用 Parse，错误必须返回，时区则在更早的业务决策中明确。