Go net/mail.AddressParser.ParseList 怎样解析多个邮箱地址

在 Go 中，net/mail.AddressParser.ParseList 专门处理“多个邮箱地址放在一段字符串里”的场景。它把逗号分隔的地址解析成 []*mail.Address，每项都有 Name 和 Address 两个字段；解析失败时返回 error。如果输入来自邮件头，优先在拿到字段值后判断错误，再使用解析结果。

官方文档：https://pkg.go.dev/net/mail#AddressParser.ParseList

最稳妥的用法是：把整段地址交给 ParseList，不要先用 strings.Split 按逗号切开。因为显示名可能被引号包住并包含逗号，手工切分会破坏一个完整地址。

ParseList 的输入和输出是什么

官方定义中，ParseList 接收形如 Gogh Fir 或 foo@example.com 的逗号分隔地址列表，返回地址指针切片和错误。它解决的是“邮件地址语法解析”，不负责发信、DNS 查询或 SMTP 连接。

先用最小代码解析多个地址

调用时不需要自己拆分逗号。遍历返回切片，并分别读取显示名和邮箱地址即可。

package main

import (
    "fmt"
    "log"
    "net/mail"
)

func main() {
    list := "Alice , Bob "

    parser := &mail.AddressParser{}
    addresses, err := parser.ParseList(list)
    if err != nil {
        // 解析错误时不要继续使用可能不完整的结果。
        log.Fatalf("解析收件人列表失败: %v", err)
    }

    for index, address := range addresses {
        // Name 可能为空；Address 才是实际的邮箱地址字段。
        fmt.Printf("%d: name=%q address=%q\n", index, address.Name, address.Address)
    }
}

这里使用显式的 AddressParser，便于后续配置 WordDecoder。如果不需要自定义解码，也可以使用包级的 mail.ParseAddressList；但当前标题关注的是带解析器对象的 ParseList。

带引号的显示名为什么不能用 strings.Split

逗号通常表示下一个地址开始，但它也可能出现在被引号包住的显示名中。例如 "研发, 值班" 仍然是一个地址。先用 strings.Split(list, ",") 会把它拆成两段，后续再交给 Parse 时自然会遇到错误或错误的字段。

让标准库处理语法边界，调用方只需要关心结果：

package main

import (
    "fmt"
    "log"
    "net/mail"
)

func main() {
    list := `"研发, 值班" , ops@example.com`

    addresses, err := (&mail.AddressParser{}).ParseList(list)
    if err != nil {
        // 引号、尖括号或邮箱语法不完整时，统一返回解析错误。
        log.Fatalf("地址列表格式不正确: %v", err)
    }

    for _, address := range addresses {
        // 显示名中的逗号不会被当作另一个地址的分隔符。
        fmt.Printf("%s => %s\n", address.Name, address.Address)
    }
}

ParseList 返回 error 时该怎么处理

邮件头或用户配置不是完全可信的输入，调用 ParseList 后应先判断 error。不要把“切分后能得到几项”当作成功标准，也不要在错误发生后继续把地址交给后续发信逻辑。

// parseRecipients 只负责把文本转换成结构化收件人，不负责发送邮件。
func parseRecipients(raw string) ([]*mail.Address, error) {
    // 统一使用标准库语法解析，避免手工处理引号和逗号。
    addresses, err := (&mail.AddressParser{}).ParseList(raw)
    if err != nil {
        return nil, fmt.Errorf("收件人列表解析失败: %w", err)
    }
    // 空文本不一定是语法错误，由上层决定是否允许空收件人。
    if len(addresses) == 0 {
        return nil, fmt.Errorf("收件人列表为空")
    }
    return addresses, nil
}

是否把空字符串视为错误，属于业务规则而不是 ParseList 的替代功能。公共解析函数可以像上面一样拒绝空列表；如果某个邮件头允许为空，则应在调用方保留这个差异。

处理邮件头时，ParseList 和 Header.AddressList 怎么选

如果你已经有一段字符串，例如配置文件中的收件人字段，直接调用 ParseList。如果你已经通过 mail.ReadMessage 得到 mail.Header，则可以调用 Header.AddressList("To")，它表达了“从指定头字段解析地址列表”的意图。

package main

import (
    "fmt"
    "log"
    "net/mail"
    "strings"
)

func main() {
    message := "To: Alice , Bob \r\n\r\nbody"
    parsed, err := mail.ReadMessage(strings.NewReader(message))
    if err != nil {
        // 先保证邮件头成功解析，再读取 To 字段。
        log.Fatal(err)
    }

    addresses, err := parsed.Header.AddressList("To")
    if err != nil {
        // Header.AddressList 的错误也要按解析失败处理。
        log.Fatalf("To 头解析失败: %v", err)
    }
    fmt.Println("收件人数量:", len(addresses))
}

两条路径使用相同的地址语法规则，但输入层次不同：ParseList 适合裸字符串，Header.AddressList 适合已经解析出的邮件头。不要为了读取一个字符串先伪造完整邮件消息。

写一个保留显示名的复用函数

很多业务层只需要一个稳定的收件人对象。可以在解析层保留标准库的 mail.Address，在真正发送前再转换为字符串；这样既不会丢失显示名，也不会让发送逻辑重复解析文本。

type Recipient struct {
    Name    string
    Address string
}

// recipientsFromText 将地址文本转换为业务层结构，并保留显示名。
func recipientsFromText(raw string) ([]Recipient, error) {
    addresses, err := (&mail.AddressParser{}).ParseList(raw)
    if err != nil {
        // 用包装错误保留原始语法错误，便于记录输入来源。
        return nil, fmt.Errorf("parse recipients: %w", err)
    }

    result := make([]Recipient, 0, len(addresses))
    for _, address := range addresses {
        // 复制字段后，业务层不必依赖指针切片的生命周期。
        result = append(result, Recipient{
            Name:    address.Name,
            Address: address.Address,
        })
    }
    return result, nil
}

常见问题

ParseList 和 strings.Split 有什么区别？

strings.Split 只按字符切割，不理解邮件地址语法；ParseList 会按邮件地址规则识别显示名、尖括号和列表边界。只要输入可能包含显示名，就应优先使用标准库解析。

没有显示名时 Name 是什么？

对于 alice@example.com 这类地址，Name 可以为空，实际邮箱在 Address 字段中。业务代码不要用 Name 是否为空判断地址是否有效。

解析成功后能直接发送邮件吗？

不能。解析只得到结构化地址，不会建立 SMTP 连接，也不会替你验证邮箱是否存在。发送、连接和投递结果属于后续流程。

什么时候用 AddressParser 的 WordDecoder？

当邮件头中的显示名使用 RFC 2047 encoded-word 表示，并且你需要自定义字符集解码时，可以配置 AddressParser.WordDecoder。普通 ASCII 显示名不需要额外配置。

总结一下：多个邮箱地址交给 AddressParser.ParseList 整体解析，成功后遍历 []*mail.Address 读取 Name 和 Address，失败时停止后续处理；尤其不要先用 strings.Split 破坏带引号显示名的语法结构。