Go time.Time 怎样保留错误信息

在 Go 里，time.Time 不负责“保存解析错误”。它只表示一个时间值；错误信息由 time.Parse、time.ParseInLocation 或序列化方法单独返回。要保留错误信息，接口应返回 (time.Time, error)，向上层补充业务上下文时使用 %w，这样既能读到完整文本，也能继续用 errors.As 判断 *time.ParseError。

官方文档：https://pkg.go.dev/time#Parse

最容易出错的写法，是解析失败后只返回 time.Time{}，让调用方通过零值猜测原因。零值只能说明时间对象没有有效时间，不能说明是空字符串、layout 不匹配，还是时区输入不合法。

先分清 time.Time 和 error 的职责

time.Parse 的结果是两个值：成功时得到一个 time.Time 和 nil；失败时得到一个通常不可用的时间值和一个错误。错误不在 time.Time 内部，也不会因为把时间值传给另一个函数就自动跟随。

package main

import (
	"fmt"
	"time"
)

func main() {
	// layout 决定输入字符串中日期、时间和时区的排列方式。
	value, err := time.Parse(time.RFC3339, "2026-11-06T09:30:00+08:00")
	if err != nil {
		// 解析失败时不要用 value 猜测原因，直接处理 err。
		fmt.Println("解析时间失败:", err)
		return
	}

	// 成功分支中的 value 才是可以继续参与业务计算的时间。
	fmt.Println(value.Format("2006-01-02 15:04:05"))
}

因此，“保留错误信息”的第一步不是给 time.Time 增加字段，而是不要丢弃第二个返回值。对于必须记录失败原文的导入任务，可以在当前层直接返回 err，由更上层决定日志、提示或拒绝策略。

封装解析函数，失败时返回零值和原始错误

建议把输入解析集中在一个小函数中，明确约定：成功返回有效时间和 nil，失败返回零值和非空错误。这样调用方不需要同时猜测时间值和错误状态。

package schedule

import "time"

// ParseStartTime 只负责把外部 RFC3339 文本转换成 time.Time。
func ParseStartTime(raw string) (time.Time, error) {
	// 直接返回 Parse 的错误，保留原始解析位置和原因。
	parsed, err := time.Parse(time.RFC3339, raw)
	if err != nil {
		// 失败分支返回明确的零值，避免调用方误用半成品时间。
		return time.Time{}, err
	}
	return parsed, nil
}

如果业务允许没有时区的本地时间，就把规则写进函数名或参数，而不是悄悄改变含义。time.ParseInLocation 会在输入没有时区信息时使用指定位置；这和“解析失败后保留错误”是两个不同问题，不能用默认时区掩盖非法输入。

package schedule

import (
	"fmt"
	"time"
)

// ParseLocalStartTime 只对不带时区的输入使用明确的业务位置。
func ParseLocalStartTime(raw string, loc *time.Location) (time.Time, error) {
	if loc == nil {
		// 没有位置时返回可定位的参数错误，而不是默默使用本地时区。
		return time.Time{}, fmt.Errorf("解析开始时间失败: location 为空")
	}
	// layout 与 raw 必须匹配，错误仍然原样向调用方传递。
	return time.ParseInLocation("2006-01-02 15:04:05", raw, loc)
}

上面的示例需要补充 fmt 导入；实际项目中可把参数错误和解析错误统一包在同一套业务错误接口下。关键点是：返回值的错误状态始终可见，调用方不通过 IsZero 代替错误判断。

用 %w 添加上下文，还能识别 ParseError

跨越业务层时，直接返回 err 往往缺少字段名或记录编号。使用 fmt.Errorf("...: %w", err) 添加上下文，错误链仍然指向原始错误；如果底层是 *time.ParseError，上层可以用 errors.As 取出它。

package schedule

import (
	"errors"
	"fmt"
	"time"
)

// ReadStartTime 为业务错误增加记录编号，同时保留底层 ParseError。
func ReadStartTime(recordID, raw string) (time.Time, error) {
	parsed, err := time.Parse(time.RFC3339, raw)
	if err != nil {
		// %w 建立错误链，调用方仍可用 errors.As 识别底层类型。
		return time.Time{}, fmt.Errorf("记录 %s 的开始时间无效: %w", recordID, err)
	}
	return parsed, nil
}

func handleStartTime(recordID, raw string) {
	parsed, err := ReadStartTime(recordID, raw)
	if err == nil {
		// 只有无错误时才使用 parsed，避免零值继续流入业务。
		fmt.Println("开始时间:", parsed)
		return
	}

	var parseErr *time.ParseError
	if errors.As(err, &parseErr) {
		// 类型判断用于区分输入格式问题与其他系统错误。
		fmt.Println("请检查时间格式:", parseErr.Layout, parseErr.Value)
		return
	}
	fmt.Println("开始时间处理失败:", err)
}

不要把错误改成只有一段新字符串再返回，例如 fmt.Errorf("时间无效: %v", err)。这种写法虽然保留了人类可读文本，但会切断错误链，调用方无法再使用 errors.Is 或 errors.As 做类型判断。

零值、时区和序列化是三个不同边界

下面几个状态应分开处理：

time.Time.IsZero() 适合判断一个时间值是否为零值，但它不能替代解析错误。另一个常见边界是直接比较两个 time.Time：== 还会比较 Location 和可能存在的单调时钟读数；如果业务只关心时间点，通常应明确使用 Equal，不要把比较结果当成错误信息。

package schedule

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

func encodeStartTime(t time.Time) ([]byte, error) {
	// MarshalJSON 也会单独返回 error，不能只保存字节切片。
	data, err := json.Marshal(t)
	if err != nil {
		// 继续使用 %w，让调用方保留序列化失败的根因。
		return nil, fmt.Errorf("序列化开始时间失败: %w", err)
	}
	return data, nil
}

让调用方按错误类型决定处理方式

最终接口可以把“可读上下文”和“可判断类型”同时交给调用方。调用方先检查 err，再按 errors.As 区分格式错误；成功后只使用有效的 time.Time。

func importRow(id, raw string) error {
	// 解析函数已经保留了原始错误和记录编号上下文。
	parsed, err := ReadStartTime(id, raw)
	if err != nil {
		var parseErr *time.ParseError
		if errors.As(err, &parseErr) {
			// 格式错误可记录并跳过当前行，是否重试由业务决定。
			return fmt.Errorf("跳过记录 %s: 时间格式错误: %w", id, err)
		}
		// 其他错误不能被当成普通输入错误吞掉。
		return err
	}

	// parsed 是成功结果，后续才进入排序、比较或持久化。
	_ = parsed
	return nil
}

这里的核心约定可以压缩成一句话：time.Time 保存成功的时间值，error 保存失败的原因；需要补充上下文就用 %w，而不是覆盖原错误。

常见问题

time.Time 能不能直接保存 error？

不能。把时间和错误作为两个返回值或一个业务结构体的两个字段保存；不要把错误文本塞进时间字符串。

解析失败后为什么还要返回 time.Time{}？

这是为了让返回值保持明确的失败约定，提醒调用方不要使用半成品时间。真正的失败原因仍然在第二个返回值中。

什么时候用 errors.As？

当上层需要把格式错误、业务校验错误和系统错误分开处理时使用；前提是中间包装错误采用 %w 保留错误链。