Go go-imap 的 FetchCommand 为什么需要消费完或关闭

Go go-imap v2 的 FetchCommand 是流式响应的消费入口。只取一部分邮件便离开时，必须调用 Close，让库继续排空剩余响应并取得命令最终错误；否则解码器可能被尚未消费的数据挡住，同一连接后续响应也可能无法继续处理。Close 是收尾，不等于取消服务器上的 FETCH。

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

本文针对导入路径 github.com/emersion/go-imap/v2/imapclient，不混用 v1 的 channel 接口。

用可观测指标描述等待

“循环退出了”只代表业务不再读取，并不代表 IMAP 响应已经结束。将业务处理耗时、FetchCommand.Close 耗时和后续 Noop().Wait() 耗时分开记录，才能区分业务慢、排空慢与连接上的响应阻塞。还应记录申请邮件数量、实际收到数量、所取字段以及是否包含正文。

这些是比较维度，不是已完成的性能实验。不要把业务少处理几封邮件直接当成网络传输同步减少。

理解命令与消息的消费关系

Client 中的解码器负责解析服务器响应，FetchCommand 提供邮件级 Next，FetchMessageData 提供字段级 Next。正文数据可能通过 LiteralReader 暴露，不能把它当成与连接脱离的字节切片。业务不读取时，流式数据及内部缓冲形成反压，解码器便可能等待消费端。

推进命令级 Next 会丢弃上一条消息尚未消费的数据；推进消息字段也会处理前一字段中需要丢弃的数据。因此不能保留一个未读完的 LiteralReader，再推进到下一条消息后继续把它当作独立数据源。需要保留的内容应在当前消费范围内读出或保存。

这里的“丢弃”是从协议流读取并忽略，并非删除邮箱里的邮件。不同响应大小会让现象不同：小批量恰好没有卡住，也不能证明提前退出而不关闭是正确写法。API 明确要求完整消费 FetchCommand，并通过 Close 读取最终错误。参见官方 FetchCommand 文档。

在函数出口集中关闭并保留错误

下面的函数借用已经登录、已经 Select 邮箱的 Client，只读取 UID、Envelope 和 RFC822Size。UIDSet 由调用方提供，visit 可以完成邮件摘要处理；若 visit 失败，延迟收尾仍会执行。FetchMessageBuffer 是 Collect 得到的内存对象，不是流式正文读取器。

package mailfetch

import (
    "errors"
    "fmt"

    "github.com/emersion/go-imap/v2"
    "github.com/emersion/go-imap/v2/imapclient"
)

// InspectUIDs 借用已登录且已选择邮箱的连接，不负责关闭整个客户端。
func InspectUIDs(c *imapclient.Client, uids imap.UIDSet,
    visit func(*imapclient.FetchMessageBuffer) error) (retErr error) {
    if visit == nil {
        return fmt.Errorf("邮件处理函数不能为空")
    }
    cmd := c.Fetch(uids, &imap.FetchOptions{
        UID: true, Envelope: true, RFC822Size: true,
    })
    // 无论正常结束还是业务错误，都排空剩余响应并保留最终命令错误。
    defer func() {
        retErr = errors.Join(retErr, cmd.Close())
    }()
    for {
        msg := cmd.Next()
        if msg == nil {
            return nil // 命令是否成功由延迟调用的 Close 返回值决定。
        }
        buf, err := msg.Collect()
        if err != nil {
            return fmt.Errorf("读取邮件数据: %w", err)
        }
        if err := visit(buf); err != nil {
            return fmt.Errorf("处理邮件: %w", err)
        }
    }
}

示例使用 Go 标准库 errors.Join，因此需要支持该 API 的 Go 工具链。命名返回值 retErr 让延迟函数能合并业务错误与命令关闭错误。正常读到 nil 时，最终返回值仍可能因 Close 失败而非 nil；不要只看 Next 是否结束便宣布成功。

整个 Client 的生命周期由调用方负责。函数中的 Close 属于 FetchCommand；Client.Close 则涉及连接本身，两者不能互相替换。也不要在 visit 内同步等待同一连接上依赖解码器继续工作的命令，尤其当前邮件还带未读正文时；先完成当前 FETCH 的消费和收尾，再安排后续操作更容易控制。

对照三种读取策略测量

固定同一组测试邮件、相同请求字段和服务器环境，分别记录逐条处理到结束、处理部分后 Close、一次性 Collect 三种方案。将业务耗时与整个函数返回耗时分开，重复多次记录中位数和尾部耗时，并注明采样次数。所有方案都保留收尾错误，测量后再在同一连接执行 Noop().Wait()，单独记录等待。

对大附件，应优先按所需字段、明确 UID 范围或分批方案减少请求数据；仅仅更换循环写法并不能消除已经请求的响应。Collect 方便是因为聚合到内存，并非因为它绕过了协议消费。以上比较是可复用的实验设计，不提供未经运行的加速比例。

确定关闭与取消的适用边界

Close 会消费剩余响应并等待命令结束，因此服务器迟迟不发送完整响应时，Close 也可能等待。真正需要放弃连接时，应由拥有连接生命周期的上层处理 Client.Close，并接受该连接上其他操作一起受影响；不要把每个业务提前退出都变成断开共享连接。

已经读到最后还要 Close 吗？需要用它取得最终命令错误。只读到 Next 返回 nil 无法区分正常结束和命令失败。

defer cmd.Close() 足够吗？它可用于保证收尾，但单独写这一句会忽略 Close 的错误。需要可靠返回结果时，使用上面的延迟函数合并错误。

Close 会删除邮件吗？不会。这里关闭的是 FETCH 命令消费入口，排空未读响应不等于向邮箱发送删除操作。

实现细节可参考项目 FETCH 实现。把收尾放在当前函数出口、把连接关闭放在连接所有者处，再分别测量业务与排空成本，才能解释提前退出后的真实等待。