Go go-message 写入邮件后为什么要先关闭附件再关闭总写入器

在 go-message 里写一封带附件的邮件，附件返回的 io.WriteCloser 和外层 mail.Writer 不是同一个层级。附件写完要先关闭附件部件，让它结束自己的传输编码；所有部件都收尾后，再关闭总写入器，让 multipart/mixed 写出最终边界。只关闭外层 Writer，或者把两个 Close 都拖到函数末尾，都会让“附件已经写完”和“整封 MIME 邮件已经完整”混成两件事。

官方项目地址：https://github.com/emersion/go-message

下面用“报表正文 + CSV 附件”的原创场景排查这个顺序。示例只负责生成邮件字节，不连接 SMTP，也不代表邮件已经投递。

先看清问题现场：究竟是哪一层没有收尾

最容易误判的场景是：正文能看到，附件名也出现了，但附件末尾损坏；或者程序没有明显报错，却有的客户端提示 MIME 结构不完整。此时不要先把问题归到“邮箱不兼容”，先把输出拆成三层：

第一层收尾成功，不等于第二层已经完整；第二层收尾成功，也不等于第三层已经发送成功。这个分层是判断关闭顺序的起点。

为什么附件必须先于总写入器关闭

mail.CreateWriter 创建的是邮件级 Writer，mail 包把邮件组织成 multipart/mixed。调用 CreateAttachment 后拿到的是一个独立的附件部件写入器，它内部还可能包着默认的 base64 传输编码器。

因此，附件写入器的 Close 先完成“当前部件的编码尾部”；外层 Writer.Close 再完成“整个 multipart 容器的终止边界”。外层关闭只知道容器要结束，并不会替调用方补做一个仍然打开的附件部件的编码收尾。

可以把它类比成“先封好包裹里的小盒子，再封总箱子”：小盒子的内容没有结束，外层再封也不能保证里面的编码完整。

把关闭顺序写成一个可复用的函数

关键代码不在于调用多少 API，而在于每个写入器都在自己的作用域内及时关闭，并且把关闭错误保留下来。下面的函数只构建 EML 字节，收件人、主题和文件名均为演示值。

package maildemo

import (
    "bytes"
    "fmt"
    "io"
    "time"

    "github.com/emersion/go-message/mail"
)

// writePart 写入一个 MIME 部件，并在离开部件层前处理 Close 错误。
func writePart(w io.WriteCloser, data []byte) error {
    if _, err := io.Copy(w, bytes.NewReader(data)); err != nil {
        // 写入失败时立即关闭，尽量让编码器释放自己的状态。
        _ = w.Close()
        return fmt.Errorf("写入部件: %w", err)
    }
    if err := w.Close(); err != nil {
        // Close 可能负责写出传输编码尾部，不能把错误当成普通清理错误。
        return fmt.Errorf("关闭部件: %w", err)
    }
    return nil
}

// BuildMail 只生成邮件字节；成功返回前不会把半成品交给发送模块。
func BuildMail(bodyText string, attachmentData []byte) ([]byte, error) {
    var header mail.Header
    header.SetAddressList("From", []*mail.Address{{
        Name: "报表服务", Address: "reports@example.com",
    }})
    header.SetAddressList("To", []*mail.Address{{
        Name: "收件示例", Address: "reader@example.net",
    }})
    header.SetSubject("周报与明细")
    header.SetDate(time.Now())

    // 先在私有缓冲区完成所有 MIME 收尾，再决定是否交付。
    var buf bytes.Buffer
    mw, err := mail.CreateWriter(&buf, header)
    if err != nil {
        return nil, fmt.Errorf("创建邮件 Writer: %w", err)
    }

    var inlineHeader mail.InlineHeader
    inlineHeader.SetContentType("text/plain", map[string]string{"charset": "utf-8"})
    bodyWriter, err := mw.CreateSingleInline(inlineHeader)
    if err != nil {
        return nil, fmt.Errorf("创建正文部件: %w", err)
    }
    if err := writePart(bodyWriter, []byte(bodyText)); err != nil {
        return nil, err
    }

    var attachmentHeader mail.AttachmentHeader
    attachmentHeader.SetContentType("text/csv", map[string]string{"charset": "utf-8"})
    attachmentHeader.SetFilename("weekly-detail.csv")
    attachmentWriter, err := mw.CreateAttachment(attachmentHeader)
    if err != nil {
        return nil, fmt.Errorf("创建附件部件: %w", err)
    }
    if err := writePart(attachmentWriter, attachmentData); err != nil {
        return nil, err
    }

    // 所有子部件已关闭后，外层 Close 才负责 multipart 的最终边界。
    if err := mw.Close(); err != nil {
        return nil, fmt.Errorf("关闭外层邮件 Writer: %w", err)
    }
    return buf.Bytes(), nil
}

这里有两个独立的收尾点：writePart 结束正文或附件自己的 Writer，mw.Close() 结束整个 MIME 容器。任何一处失败都返回 nil 数据，避免把可能缺少编码尾部或最终边界的缓冲区继续保存、排队或发送。

不要让 defer 把附件关闭推迟到外层之后

defer 很适合做资源清理，但在这个嵌套结构里，直接把正文、附件和外层 Writer 的关闭都 defer 到同一个函数，会利用后进先出的规则，把外层 Writer 先关闭。那样的代码看起来整洁，却把 MIME 的层级顺序反过来了。

// 反例：多个 defer 的执行顺序与 MIME 层级相反。
bodyWriter, err := mw.CreateSingleInline(inlineHeader)
if err != nil {
    return nil, err
}
defer bodyWriter.Close() // 可能晚于外层关闭

attachmentWriter, err := mw.CreateAttachment(attachmentHeader)
if err != nil {
    return nil, err
}
defer attachmentWriter.Close() // 最后注册，却会最先关闭
defer mw.Close()                // 外层先于 bodyWriter 关闭

更稳妥的做法是：部件写完就显式 Close，外层 Writer 只在所有部件函数成功后显式 Close。若确实需要 defer 兜底，也要让它只负责失败路径清理，不能替代明确的成功收尾顺序。

两个 Close 分别收束什么

当问题现场同时出现“附件内容不全”和“邮件边界异常”时，可以按下图看对象关系。正文部件和附件部件都归属于部件层；部件 Close 产生可完整解码的传输编码尾部；外层 Writer.Close 则把 MIME 终止边界补到私有缓冲区中。最后得到的只是可交付邮件字节，仍需由发送模块承担 SMTP 或队列职责。

复查时只交付完整邮件，不交付半成品

代码层面可以建立一个很小的交付约定：正文部件写入成功、正文部件 Close 成功、附件部件写入成功、附件部件 Close 成功、外层 Writer Close 成功，才返回邮件字节。任何阶段失败，都记录阶段名和错误类型，不把正文、附件原文或收件人地址写进普通日志。

另外，mail.CreateAttachment 的文件名只写入 MIME 头，不会自动读取本地文件；附件内容仍要由调用方写入。对于较大的附件，还要在业务层限制输入大小和内存占用，不能因为 MIME Writer 的 Close 顺序正确，就把它误认为发送、投递或容量检查。

为什么不能只调用 mw.Close()？因为外层 Close 负责 multipart 容器的收尾，不等于替每个子 Writer 结束传输编码。每个部件都要先完成自己的 Close。

正文也需要先关闭吗？需要。正文通常也有自己的传输编码器；正文和附件都是独立 MIME 部件，应该在创建下一个部件前结束。

关闭外层 Writer 后还可以继续添加附件吗？不应继续。外层 Close 表示容器已经收尾，后续写入会破坏“完整邮件已经准备好”的交付约定。

拿到返回的字节就代表邮件发送成功了吗？不是。返回值只表示本地构建阶段成功，实际保存、入队、SMTP 连接和远端接收要由后续模块单独处理。