Go go-vcard 怎样设置优先使用的邮箱字段

在 go-vcard 中，优先邮箱不是靠 EMAIL 字段的变量名决定的，而是给某个 Field 设置 PREF 参数，再用 Card.PreferredValue(vcard.FieldEmail) 读取。多个邮箱应先用 Card.Add 保存；PREF 数值越小，库选择时的优先级越高。

官方项目地址：https://github.com/emersion/go-vcard

下面的示例把工作邮箱标成首选、把个人邮箱保留为备用，并同时展示如何拿到纯字符串和完整字段对象。示例只负责构造与编码 vCard，不连接通讯录服务，也不代表已经写入外部系统。

先保留多个 EMAIL 字段

一张 vcard.Card 本质上是字段名到字段列表的映射。同一个联系人有多个邮箱时，应对 FieldEmail 连续调用 Add。如果使用 Set，后一次会替换前一次，最终只剩一个字段。

给邮箱字段加上优先级

Field.Params 保存字段参数。go-vcard 提供了 ParamPreferred 常量，对应 vCard 的 PREF；ParamType 可以继续标记 work 或 home。这两个参数职责不同：前者用于选择，后者用于描述用途。

最小写法如下。Add 让两个邮箱同时存在，工作邮箱的 PREF=1 让它成为优先候选。

package main

import (
    "fmt"

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

func main() {
    card := make(vcard.Card)

    // Add 会追加字段，工作邮箱和个人邮箱都能保留。
    card.Add(vcard.FieldEmail, &vcard.Field{
        Value: "work@example.com",
        Params: vcard.Params{
            // PREF 数值越小，Preferred 选择时越靠前。
            vcard.ParamPreferred: []string{"1"},
            vcard.ParamType:      []string{vcard.TypeWork},
        },
    })
    card.Add(vcard.FieldEmail, &vcard.Field{
        Value: "home@example.com",
        Params: vcard.Params{
            // 没有 PREF 时，仍可用 TYPE 说明它是个人邮箱。
            vcard.ParamType: []string{vcard.TypeHome},
        },
    })

    // 只取业务要使用的邮箱字符串。
    fmt.Println(card.PreferredValue(vcard.FieldEmail))
}

输出值会是 work@example.com。这里的选择依据来自字段参数，而不是 TYPE=work 本身；如果只是给个人邮箱设置 TYPE=home，它不会自动成为首选。

读取时让库替你挑选

需要发送通知时，通常只调用 PreferredValue；需要继续读取参数、分组或原始字段时，调用 Preferred。前者返回字符串，后者返回 *vcard.Field，不存在对应字段时都会得到空结果。

// 读取首选值，并在需要时检查它的完整参数。
preferred := card.Preferred(vcard.FieldEmail)
if preferred == nil {
    fmt.Println("没有可用邮箱")
    return
}

// PreferredValue 适合交给通知或邮件模块。
value := card.PreferredValue(vcard.FieldEmail)
fmt.Println("首选邮箱:", value)

// Preferred 适合判断用途、分组或其他字段参数。
fmt.Println("邮箱类型:", preferred.Params.Get(vcard.ParamType))

实现层面的规则很直接：库遍历该属性的字段，默认优先级按较大的数处理；读到数字形式的 PREF 后，数值更小的字段会替换当前候选。没有参数时，列表顺序只在优先级相同或都缺少优先级时产生影响。

编码输出时补上 VERSION

如果还要把 Card 写成 vCard 文本，先设置 VERSION，再交给 NewEncoder。官方 API 明确要求待编码的 Card 有版本字段；否则优先级设置虽然存在于内存中，输出阶段仍不完整。

package carddemo

import (
    "bytes"
    "fmt"

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

func encodeCard(card vcard.Card) (string, error) {
    // Encoder 需要版本字段；3.0 适合保留数字 PREF 参数。
    card.SetValue(vcard.FieldVersion, "3.0")

    var buf bytes.Buffer
    enc := vcard.NewEncoder(&buf)
    if err := enc.Encode(card); err != nil {
        // 编码失败时不把不完整文本交给后续存储或发送模块。
        return "", fmt.Errorf("编码 vCard: %w", err)
    }
    return buf.String(), nil
}

如果业务需要转换为 vCard 4，可以在编码前调用 vcard.ToV4(card)。库会把带有 pref 类型标记的字段转换为数字形式的 PREF=1；已经使用数字 PREF 的字段则应按目标格式继续确认兼容性，不要把 TYPE 当成通用优先级开关。

四个容易踩到的边界

• 想保留多个邮箱却调用 Set：后一次写入会覆盖前一次，改用 Add。
• PREF 相同：选择逻辑只在发现更小数值时替换，因此相同优先级通常保留先出现的字段；业务上最好只设置一个明确的第一优先级。
• PREF 不是合法数字：不要依赖解析失败后的实现细节，生成数据时只写规范的数字文本。
• 把 TYPE 当 PREF：work、home 是用途标签；它们不能替代数字优先级。

最后可以按下面的速查表决定调用方式：

没有 PREF 时会返回什么？库仍会返回一个字段；没有明确优先参数时，调用方不应把字段列表顺序当成稳定的业务偏好。

能不能用 SetValue 设置 PREF？不能。SetValue 只设置字段值，不设置参数；要同时写值和参数，应构造 vcard.Field 后调用 Add 或 Set。

PreferredValue 会修改 Card 吗？不会。它只读取并返回优先字段的值，字段顺序和参数仍由原 Card 保留。

技术依据：https://pkg.go.dev/github.com/emersion/go-vcard、https://raw.githubusercontent.com/emersion/go-vcard/master/card.go、https://raw.githubusercontent.com/emersion/go-vcard/master/v4.go。本文的联系人场景、代码组织和结构图为原创示例。