Go go-vcard 怎样为同一联系人保存多个电话号码

如果一个联系人同时有工作手机、私人手机和座机，Go 里的 go-vcard 不应该把三个号码拼进一个字符串，也不能连续调用 SetValue 期待它自动保留历史值。正确的模型是：一张 Card 代表同一联系人，多个电话号码作为同名 TEL 字段追加进去；需要区分用途时，再给字段附加 TYPE 和 PREF 参数。

官方资料地址：https://pkg.go.dev/github.com/emersion/go-vcard

先把联系人和电话号码的边界分开

我第一次处理 vCard 导出时，最容易犯的错误是把“联系人”理解成一组字符串。go-vcard 的 Card 实际上是 map[string][]*Field：键是属性名，值是这个属性的字段列表。也就是说，同一张卡片可以拥有多个 TEL，它们仍属于同一个联系人。

这个结构还有一个直接的安全边界：号码是结构化字段，不要把未经整理的多个号码拼接进一个 TEL 值，也不要在字段值里混入类型标签。类型应该由参数表达，避免导入方把“工作：”误当成号码内容。

无额外参数时，直接用 AddValue 追加

如果只关心“这个联系人有哪些电话号码”，最短写法是对同一个 Card 多次调用 AddValue。它会把每个值追加到字段列表，而不是替换之前的数据：

package main

import (
    "fmt"

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

func main() {
    // 一张 Card 表示同一个联系人，多个 TEL 值放在同一张卡片里。
    card := make(vcard.Card)
    card.SetValue(vcard.FieldFormattedName, "林晓岚")

    // AddValue 会追加同名字段，前一个号码不会被后一个覆盖。
    card.AddValue(vcard.FieldTelephone, "+86-10-55550001")
    card.AddValue(vcard.FieldTelephone, "+86-138-0000-0002")
    card.AddValue(vcard.FieldTelephone, "+86-21-55550003")

    // Values 返回该属性的全部值，适合做导出前的数量和内容检查。
    fmt.Println(card.Values(vcard.FieldTelephone))
}

这里的关键不是调用次数，而是方法语义：AddValue 追加，SetValue 设置单个值。如果把三次调用都写成 SetValue，最后一次写入会替换前面的号码；这在代码看起来“能运行”时尤其容易漏掉。

需要区分工作号和手机时，用 Field 参数保存类型

实际联系人通常不止需要号码列表，还需要知道号码用途。此时可以创建 Field，再通过 Params.Set 写入 TYPE；PREF 则可表达偏好顺序。TypeWork、TypeCell 等常量来自 go-vcard：

package main

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

func addPhone(card vcard.Card, number, phoneType, preference string) {
    // Field.Value 保存纯号码，类型和偏好放进参数，避免污染号码文本。
    field := &vcard.Field{Value: number}
    field.Params.Set(vcard.ParamType, phoneType)
    if preference != "" {
        // PREF 是可选参数；没有偏好时不写入空参数。
        field.Params.Set(vcard.ParamPreferred, preference)
    }
    // Add 追加 TEL 字段，保留同一联系人已有的号码。
    card.Add(vcard.FieldTelephone, field)
}

func buildCard() vcard.Card {
    // 先建立联系人，再为同一张卡片追加不同用途的号码。
    card := make(vcard.Card)
    card.SetValue(vcard.FieldFormattedName, "林晓岚")
    addPhone(card, "+86-10-55550001", vcard.TypeWork, "2")
    addPhone(card, "+86-138-0000-0002", vcard.TypeCell, "1")
    addPhone(card, "+86-21-55550003", vcard.TypeHome, "3")
    return card
}

这段写法把三种信息分开：Value 是号码本身，TYPE 是用途，PREF 是偏好。下游程序可以读取字段参数，而不必重新解析自定义字符串。

编码前读取全部号码，避免只检查首个值

go-vcard 提供 Value、PreferredValue 和 Values 三种不同粒度的读取方式。只想拿一个展示号码时可以用偏好值；要确认导出不会丢联系人电话，则应使用 Values(FieldTelephone)，因为 Value 只返回第一个字段值。

func writeCard(path string, card vcard.Card) error {
    // 编码前先读取全部 TEL，发现数量异常时阻止静默丢号。
    phones := card.Values(vcard.FieldTelephone)
    if len(phones) == 0 {
        return fmt.Errorf("联系人没有电话号码")
    }

    dest, err := os.Create(path)
    if err != nil {
        return err
    }
    defer dest.Close() // 文件句柄只在本次编码期间保持打开。

    enc := vcard.NewEncoder(dest)
    return enc.Encode(card)
}

示例中的错误分支是业务保护，不是库的强制要求：如果“至少一个电话”是你的业务规则，就在编码前明确检查；如果空号码卡片也合法，则可以删除这条判断。重点是把检查放在同一张 Card 进入 Encoder 之前。

常见问题

连续调用 SetValue 为什么只剩一个号码？

SetValue 的职责是把某个属性设置为单个值，后一次调用会替换同名属性的已有字段。多个号码应改用 AddValue 或 Add。

可以把 TYPE=cell 直接拼进号码字符串吗？

不建议。号码值和字段参数是两个不同层次，使用 Field.Params.Set(vcard.ParamType, vcard.TypeCell) 更容易被其他 vCard 实现正确读取。

Values 和 PreferredValue 应该怎么选？

要展示或校验全部号码，用 Values；只需要一个偏好号码时，用 PreferredValue。不要用只返回首个值的 Value 代替完整性检查。