Go go-imap 怎样按正文分段读取邮件内容

用 Go 通过 IMAP 读取邮件时，真正容易混淆的是“正文”不一定是一段连续文本：一封邮件可能包含纯文本、HTML 和附件等多个 MIME 部件。使用 github.com/emersion/go-imap/v2/imapclient 时，可以先用 FetchItemBodySection 描述要取的部件，再从 FetchItemDataBodySection.Literal 读取返回流；如果需要解析整封邮件，就把这个流交给 go-message/mail。

官方地址：https://pkg.go.dev/github.com/emersion/go-imap/v2/imapclient

本文的核心结论是：小邮件可以用 Collect 直接收集，正文或附件较大时，应保留 FetchCommand 的逐条消费方式，并通过 Part、HeaderFields 或 Partial 缩小读取范围。

先把“分段读取”拆成两个边界

第一层边界是 MIME 部件。零值的 FetchItemBodySection{} 表示取整封邮件正文；给 Part 赋值，例如 []int{1, 2}，表示取指定的 MIME 部件；把 Specifier 设为 PartSpecifierHeader，则只读取头部。

第二层边界是字节范围。Partial 使用 Offset 和 Size 描述正文载荷的字节区间，适合先取邮件正文的前一小段做预览。它不是按字符或按行切分，中文正文也不能把这个范围当作安全的 UTF-8 字符边界。

用 FetchCommand 逐条取出正文数据

Fetch 返回的是命令对象。它有消息层和数据项层：先调用 Next 得到一封消息，再继续调用消息对象的 Next 找到 FetchItemDataBodySection。官方文档特别强调，调用方必须完整消费 FetchCommand；最稳妥的写法是在创建后立即 defer fetchCmd.Close()，并在函数末尾检查 Close 返回的错误。

package main

import (
	"fmt"
	"io"
	"log"

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

// readBodyPreview 读取指定邮件的正文前缀，避免把整封大邮件一次性放进内存。
func readBodyPreview(c *imapclient.Client, seqNum uint32, size int64) ([]byte, error) {
	seqSet := imap.SeqSetNum(seqNum)
	bodySection := &imap.FetchItemBodySection{
		// 只请求整个正文载荷的前 size 个字节；它按字节工作，不按字符工作。
		Partial: &imap.SectionPartial{Offset: 0, Size: size},
	}
	fetchCmd := c.Fetch(seqSet, &imap.FetchOptions{
		BodySection: []*imap.FetchItemBodySection{bodySection},
	})
	defer fetchCmd.Close()

	msg := fetchCmd.Next()
	if msg == nil {
		return nil, fmt.Errorf("没有收到序号 %d 的邮件响应", seqNum)
	}
	for {
		item := msg.Next()
		if item == nil {
			break
		}
		body, ok := item.(imapclient.FetchItemDataBodySection)
		if !ok {
			continue
		}
		data, err := io.ReadAll(body.Literal)
		if err != nil {
			return nil, fmt.Errorf("读取正文片段失败: %w", err)
		}
		return data, nil
	}
	return nil, fmt.Errorf("响应中没有正文片段")
}

func main() {
	// 示例只展示读取边界；连接、登录和选中邮箱由调用方负责。
	var c *imapclient.Client
	preview, err := readBodyPreview(c, 1, 4096)
	if err != nil {
		log.Printf("读取预览失败: %v", err)
		return
	}
	log.Printf("预览字节数: %d", len(preview))
}

这里的关键不是把 io.ReadAll 绝对禁止，而是把读取范围先限制在 Partial。如果返回内容仍可能很大，可以改为从 body.Literal 直接复制到文件或下游解析器，避免额外构造完整的 []byte。

正文是文本还是附件，交给 mail 解析器判断

如果目标是提取正文和附件，而不是只拿一段原始字节，可以请求整封邮件的正文流。拿到 FetchItemDataBodySection 后，用 mail.CreateReader 创建 MIME 读取器，再通过 NextPart 遍历每一部分。InlineHeader 表示正文内嵌内容，AttachmentHeader 表示附件，二者的处理策略不应混在一起。

package main

import (
	"fmt"
	"io"
	"log"

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

// extractParts 从一封邮件的 Literal 流中分别读取正文和附件元数据。
func extractParts(c *imapclient.Client, seqNum uint32) error {
	seqSet := imap.SeqSetNum(seqNum)
	section := &imap.FetchItemBodySection{}
	fetchCmd := c.Fetch(seqSet, &imap.FetchOptions{
		BodySection: []*imap.FetchItemBodySection{section},
	})
	defer fetchCmd.Close()

	msg := fetchCmd.Next()
	if msg == nil {
		return fmt.Errorf("没有收到邮件数据")
	}
	var literal imap.LiteralReader
	for {
		item := msg.Next()
		if item == nil {
			break
		}
		body, ok := item.(imapclient.FetchItemDataBodySection)
		if ok {
			literal = body.Literal
			break
		}
	}
	if literal == nil {
		return fmt.Errorf("没有找到正文 Literal")
	}

	reader, err := mail.CreateReader(literal)
	if err != nil {
		return fmt.Errorf("创建 MIME 读取器失败: %w", err)
	}
	for {
		part, err := reader.NextPart()
		if err == io.EOF {
			break
		}
		if err != nil {
			return fmt.Errorf("读取 MIME 部件失败: %w", err)
		}
		switch header := part.Header.(type) {
		case *mail.InlineHeader:
			// 内嵌正文可能是纯文本或 HTML，按业务需要读取或转码。
			text, err := io.ReadAll(part.Body)
			if err != nil {
				return fmt.Errorf("读取内嵌正文失败: %w", err)
			}
			log.Printf("正文长度: %d", len(text))
		case *mail.AttachmentHeader:
			// 附件先取文件名，再决定是否保存；不要默认把附件全部读入内存。
			name, err := header.Filename()
			if err != nil {
				return fmt.Errorf("读取附件文件名失败: %w", err)
			}
			log.Printf("发现附件: %s", name)
		}
	}
	return nil
}

这条路径的优点是解析器会沿着 MIME 结构拆分部件，调用方不必猜测附件位于第几个 part。若只想拿一个已知部件，则直接使用 Part 更简单；若要理解一封复杂邮件的整体结构，使用 mail.CreateReader 更合适。

三种读取方式怎么选

可以按目标大小做一个简单决策：

• 只需要标题、发件人或少量元数据：请求 Header 或只取需要的头字段。
• 只需要预览：给正文部件设置 Partial，并把字节片段交给后续解码逻辑。
• 需要完整正文或附件：请求完整 Literal，使用 mail.CreateReader 逐个部件读取。
• 邮件体积确定且合理：可以调用 FetchCommand.Collect，但它会把消息内容收集进内存，不适合大型附件。

UID 选项只改变响应中是否带回 UID，不会把正文自动变成流式读取；真正决定读取粒度的是 BodySection 的描述和你如何消费 Literal。

几个容易漏掉的边界

第一，FetchCommand.Close 的错误不能完全忽略。即使前面已经拿到正文，服务器在命令收尾阶段返回的协议错误仍然可能需要交给上层。

第二，Partial 是载荷字节区间。对 UTF-8 文本只取前几千字节时，末尾可能落在一个多字节字符中间；预览程序需要能容忍解码不完整，或者在本地做安全截断。

第三，使用 Collect 后，不要再假设自己仍处在流式路径。官方说明它会读取并存储消息内容；如果邮件含大型附件，应回到 Next 加 Literal 的方式。

第四，调用 Fetch 后要持续消费消息层和数据项层，不能只读第一项就把连接交给别的命令。把命令对象的关闭放进 defer，再在需要时显式检查关闭错误，是更稳妥的资源边界。

结语

Go go-imap 的分段读取可以归结为三件事：用 FetchItemBodySection 描述“取哪里”，用 FetchCommand.Next 和 FetchItemDataBodySection 找到“取到什么”，再决定把 Literal 交给字节处理还是 MIME 解析器。范围明确时优先缩小请求，内容复杂时保留流式边界，就能在预览、正文提取和附件处理之间做出清晰取舍。

相关问题

• 为什么读取了正文片段却出现乱码？通常要区分字节截断、Content-Transfer-Encoding 和字符集解码三个边界。
• 什么时候应该使用 Part 而不是 Partial？前者定位 MIME 部件，后者限制载荷字节范围，二者可以组合使用。
• Collect 和逐条 Next 有什么区别？前者便于小消息快速取值，后者更适合大正文和附件的受控读取。