Go mail.Header.Date 缺少日期与格式错误怎样区分

在 Go 里解析邮件时间时，mail.Header.Date() 返回错误并不只有一种含义：Date 头根本不存在时，返回的是可识别的 mail.ErrHeaderNotPresent；Date 头存在但文本无法按邮件日期规则解析时，返回的是普通解析错误；只有第三种情况才会得到可用的 time.Time。

判断顺序应是“先用 errors.Is 识别缺失，再把剩余错误视为格式或内容问题”。不要把所有错误都当成缺失，也不要因为拿不到日期就直接把当前时间写进业务字段。

三种返回结果先分开看

Header.Date 的实现很短：它先通过大小写不敏感的 Header.Get("Date") 取第一个值；取到空字符串时返回 ErrHeaderNotPresent，否则把原始文本交给 ParseDate。所以错误类型已经把“没有这个头”和“有这个头但解析失败”分成了两层。

第一种是 Header{} 或者 Date 对应的第一个值为空。第二种是例如月份写错、时区偏移不完整、日期结构缺字段等，文本非空但不符合解析规则。第三种是返回日期和 nil 错误，日期的时区信息也会保留在结果里。

用 errors.Is 把缺失单独拎出来

生产代码不要比较错误字符串。标准库暴露了 mail.ErrHeaderNotPresent，应使用 errors.Is 判断它。这样即使上层以后对错误做了包装，缺失语义仍然能被识别。

package main

import (
    "errors"
    "fmt"
    "net/mail"
)

func classifyDate(header mail.Header) string {
    date, err := header.Date()
    if err == nil {
        // 成功时保留解析出的时区和时间，不要再按本地时区重解析。
        return fmt.Sprintf("valid: %s", date.Format("2006-01-02 15:04:05 Z07:00"))
    }
    if errors.Is(err, mail.ErrHeaderNotPresent) {
        // 缺失是输入不完整，和已有 Date 但格式错误不是同一类问题。
        return "missing: Date header is absent"
    }
    // 非空值解析失败，记录错误本身，便于定位上游生成格式。
    return "malformed: " + err.Error()
}

func main() {
    cases := []mail.Header{
        {},
        {"Date": []string{"not-a-mail-date"}},
        {"Date": []string{"Tue, 15 Nov 2022 08:30:00 +0800"}},
    }
    for _, header := range cases {
        fmt.Println(classifyDate(header))
    }
}

这里的关键不是输出文案，而是分支顺序：先判断 err == nil，再识别哨兵错误，最后处理其它错误。只有成功分支可以安全使用返回的时间值。

为什么不能只看 Header.Get

Header.Get("Date") 返回空字符串只能说明“取到的第一个值为空”。它适合做展示或粗略检查，却不能替代 Header.Date() 的错误语义：空字符串会让你无法区分字段不存在与字段存在但内容为空，也无法获得格式解析失败的原因。

另外，Header 的底层类型是 map[string][]string，Get 只取第一个值。邮件头出现重复 Date 时，文章范围内建议先按标准库的正常调用路径处理，并在确实需要审计重复头时直接读取 map 记录；不要把重复头静默拼成一个日期字符串再交给 ParseDate。

格式错误具体落在哪些边界

ParseDate 面向 RFC 5322 日期格式，标准库实现还兼容一些常见的旧式写法。例如带星期、带秒或不带秒、数字时区偏移，以及部分旧式时区写法都可能被接受；但这不表示任意人类日期文本都能解析。

package main

import (
    "fmt"
    "net/mail"
)

func main() {
    samples := []string{
        "Fri, 21 Nov 1997 09:55:06 -0600",
        "21 Nov 97 09:55:06 GMT",
        "Fri, 21 Nov 1997 09:55:06 -060",
    }
    for _, raw := range samples {
        parsed, err := mail.ParseDate(raw)
        if err != nil {
            // 失败时保留 raw；只保存错误文本往往丢掉排查上游所需的证据。
            fmt.Printf("raw=%q parse_error=%v\n", raw, err)
            continue
        }
        // 用 RFC3339 统一展示结果，但不改变原邮件头的存档内容。
        fmt.Printf("raw=%q parsed=%s\n", raw, parsed.Format("2006-01-02T15:04:05Z07:00"))
    }
}

第三个示例的偏移量只有三位，文本看起来像日期，但不能据此当成合法输入。对于解析失败，应该把原始 Date 头和错误一起记录到可控范围的诊断字段中，并注意脱敏与日志长度限制。

把分类结果接入邮件归档

归档系统通常需要一个业务时间，但“没有 Date”与“Date 损坏”应采用不同策略：

• 缺失：可以把邮件接收时间作为临时排序字段，但要把时间来源标记为 received_at，不能伪装成发件时间。
• 格式错误：优先保留原始头，必要时进入人工或异步修复队列；不要静默替换成当前时间。
• 解析成功：使用返回的 time.Time，后续展示时再统一格式化，不要丢失原始时区。

一个轻量的返回结构可以让调用方不再依赖错误字符串：

type DateResult struct {
    Value      time.Time
    Source     string // mail_date、received_at 或 unknown
    Raw        string
    Missing    bool
    ParseError error
}

如果只需要判断，不必为了包装错误引入复杂层次；如果需要跨队列传输，建议把 Missing、Source 和可控长度的 Raw 明确存为字段。

一张表记住判断顺序

常见追问

可以用 strings.TrimSpace 后再判断缺失吗？

一般不需要。直接交给 Header.Date()，让标准库统一处理空值和解析；只有在你明确拥有自定义输入协议时，才考虑在边界层做额外清洗。

解析失败时能不能直接用 time.Now？

不建议。当前时间表达的是系统收到或处理邮件的时间，不是邮件声明的时间。若业务必须继续处理，请把降级时间和来源字段分开保存。

为什么要保留原始 Date 文本？

因为错误只告诉你解析失败，不一定能说明上游究竟发送了什么。保留经过长度限制和必要脱敏的原文，才能定位时区、字段缺失或格式生成问题。

最终可以把规则压缩成一句话：errors.Is(err, mail.ErrHeaderNotPresent) 只负责识别缺失；其它非 nil 错误按格式或内容问题处理；只有 nil 错误返回的 time.Time 才是可靠的邮件日期。