Go go-smtp 的 Data 写入器为什么必须关闭

Go go-smtp 的 Data 写入器必须在正常提交时显式关闭，因为 Write 成功只说明内容写入没有报告错误，尚未完成 SMTP 数据结束与最终响应读取。DataCommand.Close 会结束邮件数据，并等待服务器的提交结果；遗漏关闭或忽略它的错误，都可能把未完成、被拒绝的提交记成成功。

官方地址：https://github.com/emersion/go-smtp

明确邮件提交的生产目标

假设通知服务已接受发件人和收件人，io.Copy 也没有报错，但业务记录了“发送成功”之后，邮件并未进入预期状态。首先要区分三个层次：内容传输完成、服务器接受提交、最终收件人收到邮件。写完内容不等于后两个目标；SMTP 接受也不证明最终投递到收件箱。

对应用而言，合理的本次事务成功条件是：完整内容写入成功，DataCommand.Close 返回 nil，再将任务登记为已被 SMTP 服务器接受。邮件的最终投递情况需要另行处理退信、投递反馈和服务端记录。

理解 DataCommand 与提交响应的关系

Client.Data 之前必须完成 Mail，并至少成功调用一次 Rcpt。Data 返回的 DataCommand 同时实现写入与关闭接口。其内部 DotWriter 负责 SMTP 点转义和数据结束标记，应用应提交邮件头、空行与正文，不要自行追加结束邮件的点行。

正文行以点开头时，协议需要转义；数据结束标记则属于传输封装，不能混成业务正文。DataCommand.Close 完成这一封装的收尾，再检查 SMTP 最终响应。服务器在这个位置仍可能拒绝邮件，所以仅检查 io.Copy 的错误不够。Data 活跃期间应避免调用同一 Client 的其他协议方法，直至数据提交结束。参见官方 Data 接口文档。

用明确的成功和失败路径结束写入

普通文件的 Close 常用于资源释放，DataCommand.Close 还具有提交语义。不要机械地在进入函数后立即 defer w.Close()：如果内容源中途报错，延迟关闭可能把已经写入的残缺内容作为一封完整消息提交。正常内容写入结束后显式 Close；内容读取或写入失败则弃用专用连接，是较清楚的责任划分。

package mailjob

import (
    "fmt"
    "io"

    smtp "github.com/emersion/go-smtp"
)

// SubmitPrepared 借用专用 SMTP 连接，调用前已完成 Mail 和至少一次 Rcpt。
// 消息应已在本地构建完整；调用方负责连接最终清理。
func SubmitPrepared(c *smtp.Client, message io.Reader) error {
    w, err := c.Data()
    if err != nil {
        return fmt.Errorf("进入 DATA: %w", err)
    }

    // 读取源或写入网络失败时，放弃连接，避免关闭写入器提交残缺内容。
    if _, err := io.Copy(w, message); err != nil {
        _ = c.Close()
        return fmt.Errorf("传输邮件内容，连接已弃用: %w", err)
    }

    // 正常路径显式结束 DATA，并读取服务器最终接受或拒绝响应。
    if err := w.Close(); err != nil {
        _ = c.Close()
        return fmt.Errorf("结束 DATA，提交结果需分类处理: %w", err)
    }
    return nil
}

这个辅助函数只演示 DATA 阶段，不执行真实发送。message 应是已准备完整的 RFC 822 风格消息，包含邮件头、头体分隔空行及正文，使用 CRLF 行结束。生产代码最好先完成模板渲染、附件读取与编码，确认本地数据完整后才进入 DATA，以免提交过程中暴露源数据错误。

调用者需要事先完成所需 TLS、认证、Mail 和 Rcpt 配置，并为该事务分配独占连接。示例错误路径调用 Client.Close 后，该连接必须从可复用资源中移除；不要放回连接池。正常路径只关闭 DataCommand，不关闭 Client，连接生命周期仍由调用者管理。

也不要同时 defer w.Close() 和在正文末尾调用 w.Close()。当前项目实现会记录重复关闭错误。一个负责 DATA 的函数只安排一个明确的提交出口，更容易知道最终响应由谁检查。

记录阶段与处理结果未知

日志建议记录任务编号、尝试编号、阶段、持续时间和错误类型，分别标识 data-open、data-write 与 data-close。不要记录认证口令、完整邮件正文或全部收件人隐私。邮件任务编号可以联系业务记录，不能天然成为 SMTP 服务端的去重键。

网络错误不等同于服务器明确拒绝：服务器可能已接收邮件，只是最终响应没有被客户端读到。自动重试可能产生重复消息，需要结合业务幂等记录、服务端追踪和重试策略处理。RFC 5321 对提交结束与服务器责任的规定是理解这一差异的基础，见SMTP DATA 规范。

上线前确认调用边界及常见问题

阅读调用点时，确认“发送成功”的业务更新位于 Close 返回 nil 之后；确认内容源错误会弃用连接；确认提交响应错误没有被 defer 丢弃；确认同一 Client 在 DATA 期间没有被其他协程复用。TLS 与认证在进入邮件事务前完成，不能因为正文能够写入就假定连接已受保护。

Client.Close 能替代写入器 Close 吗？不能。前者关闭连接，后者正常结束数据提交并读取结果。异常路径可以弃用连接，但不能将它记作成功提交。

能在 DATA 尚未结束时调用 Quit 或 Reset 吗？不要这样恢复正常事务。此时连接仍处于内容传输阶段，应先正常结束 DATA，或在失败路径直接放弃连接。

使用 SendMail 还要自行拿 Data 写入器吗？不需要为同一封邮件重复走两套接口。高层 SendMail 的正常实现会完成内容复制及写入器关闭；手动控制 DATA 时，关闭责任才落在自己的调用代码中。

LMTP 是否完全一样？LMTP 支持逐收件人提交响应，不能用单一 SMTP 响应模型覆盖全部结果。本文示例与成功记录讨论普通 SMTP；需要每个收件人的结果时应采用相应 LMTP 响应接口。

可对照项目客户端实现理解关闭职责。将内容完成、提交接受和最终投递分别记录，才能解释“已经写完”之后仍然需要处理的服务器响应。