Go go-message 的内联部分与附件部分怎样区分

我在处理 MIME 邮件时，最容易把两类内容混在一起：一封邮件可以同时有纯文本和 HTML 两种正文，也可以带一张图片或一个文件附件。go-message/mail 已经把这两种语义分开了：读取时看 Part.Header 的具体类型，写入时分别使用 CreateInline 和 CreateAttachment。

官方地址：https://pkg.go.dev/github.com/emersion/go-message/mail

先把内联部分和附件部分放回邮件结构

这个包把邮件看成一个或多个文本部分，以及零个或多个附件部分。纯文本和 HTML 通常是同一封邮件正文的不同表现形式；它们不应该被当作两个独立下载文件。附件则是读者需要单独保存、下载或交给文件处理器的内容。

因此，判断重点不是“这部分有没有二进制字节”，而是它在 MIME 结构里的角色：正文使用 InlineHeader，附件使用 AttachmentHeader。只看 Content-Type 容易把 HTML 正文、内嵌图片和普通附件混为一谈，具体 header 类型更适合写分支。

读取时用 Part.Header 的具体类型区分

Reader.NextPart 每次返回一个 Part。它的 Header 是接口，实际值通常是 *mail.InlineHeader 或 *mail.AttachmentHeader，可以用 Go 的类型 switch 做清晰的分派：

package main

import (
    "fmt"
    "io"

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

func readParts(mr *mail.Reader) error {
    for {
        part, err := mr.NextPart()
        if err == io.EOF {
            // 没有更多 MIME 部分时，正常结束遍历。
            return nil
        }
        if err != nil {
            // 解析失败不能当成普通附件继续处理。
            return fmt.Errorf("读取邮件部分失败: %w", err)
        }

        switch header := part.Header.(type) {
        case *mail.InlineHeader:
            // 正文可能有 text/plain、text/html 等不同表示。
            data, err := io.ReadAll(part.Body)
            if err != nil {
                return fmt.Errorf("读取正文失败: %w", err)
            }
            fmt.Printf("正文类型=%s，字节数=%d\n", header.Get("Content-Type"), len(data))
        case *mail.AttachmentHeader:
            // 附件单独处理文件名和落盘策略。
            filename, err := header.Filename()
            if err != nil {
                return fmt.Errorf("解析附件文件名失败: %w", err)
            }
            data, err := io.ReadAll(part.Body)
            if err != nil {
                return fmt.Errorf("读取附件 %q 失败: %w", filename, err)
            }
            fmt.Printf("附件=%s，字节数=%d\n", filename, len(data))
        default:
            // 未知 header 不应被静默归类为附件。
            return fmt.Errorf("不支持的邮件部分类型 %T", part.Header)
        }
    }
}

这里的关键是“先拿类型，再决定读取策略”。正文分支可以交给渲染器，附件分支可以交给文件存储；不要因为两者都实现了 io.Reader 就共用同一套业务处理。

NextPart 和 Body 有一个容易忽略的生命周期

官方说明要求：调用下一次 NextPart 之前，要把当前 Part.Body 完整读完，否则当前部分的剩余内容会被丢弃。这个约束决定了业务代码不能只读取正文开头几百字，然后马上切到下一个 part。

如果只想判断类型，也应该先明确处理策略：要么完整消费并丢弃 body，要么把 body 复制到自己的存储后再继续。对于大附件，不建议无边界地 io.ReadAll，可以直接流式写入文件，同时处理写入错误。

func saveAttachment(dst io.Writer, part *mail.Part) error {
    // 当前函数负责把一个附件完整消费掉，之后才能读取下一个 Part。
    if _, err := io.Copy(dst, part.Body); err != nil {
        return fmt.Errorf("保存附件内容失败: %w", err)
    }
    return nil
}

这也是内联与附件的一个实际差异：正文往往适合在内存里解析为文本，附件则更适合边读边写。类型识别解决的是语义分支，流式消费解决的是资源边界，两者不要混成一个判断。

写入时选择 CreateInline 或 CreateAttachment

写邮件时，mail.CreateWriter 会建立一个可容纳正文和附件的邮件 writer。正文如果有纯文本和 HTML 两种版本，先调用 CreateInline，再用 CreatePart 分别写入两个 InlineHeader；附件则直接调用 CreateAttachment。

package main

import (
    "bytes"
    "fmt"
    "io"

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

func buildMail(attachment io.Reader) ([]byte, error) {
    var out bytes.Buffer
    var header mail.Header
    header.Set("Subject", "项目周报")

    writer, err := mail.CreateWriter(&out, header)
    if err != nil {
        return nil, fmt.Errorf("创建邮件 writer 失败: %w", err)
    }

    // InlineWriter 对应同一正文的多种文本表示，不能在其中加入附件。
    inline, err := writer.CreateInline()
    if err != nil {
        return nil, fmt.Errorf("创建正文 writer 失败: %w", err)
    }

    var plainHeader mail.InlineHeader
    plainHeader.Set("Content-Type", "text/plain; charset=utf-8")
    plain, err := inline.CreatePart(plainHeader)
    if err != nil {
        return nil, fmt.Errorf("创建纯文本正文失败: %w", err)
    }
    if _, err := io.WriteString(plain, "本周完成接口联调。\n"); err != nil {
        return nil, fmt.Errorf("写入纯文本正文失败: %w", err)
    }
    if err := plain.Close(); err != nil {
        return nil, fmt.Errorf("关闭纯文本正文失败: %w", err)
    }

    var htmlHeader mail.InlineHeader
    htmlHeader.Set("Content-Type", "text/html; charset=utf-8")
    htmlPart, err := inline.CreatePart(htmlHeader)
    if err != nil {
        return nil, fmt.Errorf("创建 HTML 正文失败: %w", err)
    }
    if _, err := io.WriteString(htmlPart, "
本周完成接口联调。
"); err != nil {
        return nil, fmt.Errorf("写入 HTML 正文失败: %w", err)
    }
    if err := htmlPart.Close(); err != nil {
        return nil, fmt.Errorf("关闭 HTML 正文失败: %w", err)
    }
    if err := inline.Close(); err != nil {
        return nil, fmt.Errorf("关闭正文 writer 失败: %w", err)
    }

    // AttachmentHeader 代表独立附件，文件名属于附件元数据。
    var attachmentHeader mail.AttachmentHeader
    attachmentHeader.Set("Content-Type", "application/pdf")
    attachmentHeader.SetFilename("周报.pdf")
    filePart, err := writer.CreateAttachment(attachmentHeader)
    if err != nil {
        return nil, fmt.Errorf("创建附件失败: %w", err)
    }
    if _, err := io.Copy(filePart, attachment); err != nil {
        return nil, fmt.Errorf("写入附件失败: %w", err)
    }
    if err := filePart.Close(); err != nil {
        return nil, fmt.Errorf("关闭附件失败: %w", err)
    }
    if err := writer.Close(); err != nil {
        return nil, fmt.Errorf("关闭邮件 writer 失败: %w", err)
    }
    return out.Bytes(), nil
}

这里的判断可以记成一句话：同一正文的不同表现形式进 InlineWriter，读者要独立保存的内容进 AttachmentHeader。如果邮件只有一个正文部分，可以考虑 CreateSingleInlineWriter；它明确不支持附件，适合更简单的写入场景。

用一张表判断当前部分该走哪条分支

我最后会保留的几个边界

• 不要只用 Content-Type 判断正文还是附件；类型 switch 能直接表达包的抽象。
• 不要把附件塞进 InlineWriter；官方 API 的设计就是让它只表示同一正文的多种格式。
• 不要在 Part.Body 未消费完时调用下一次 NextPart。
• 不要把未知的 header 类型默默当成附件，升级依赖或处理非标准邮件时应保留错误信息。

常见问题

内联图片一定是 InlineHeader 吗？

不能只凭“图片”这个词下结论。读取时应以 Part.Header 的具体类型和邮件结构为准；图片也可能作为独立附件出现，业务还要结合相关 header 做自己的关联策略。

为什么不能先跳过正文再读附件？

因为 NextPart 要求当前 Body 先完整读取，否则当前部分的剩余内容会被丢弃。需要跳过时也应把它消费完。

CreateInlineWriter 能不能同时写附件？

不能。它建立的是单独的正文多格式结构，官方文档明确说明不能包含附件；需要正文加附件时使用 CreateWriter。