Go go-vcard 的 Add 与 Set 为什么会产生不同字段数量

在 github.com/emersion/go-vcard 里，Add 和 Set 产生不同字段数量是正常结果：Card 的值不是一个字段，而是 []*Field。Add 会把新字段追加到切片末尾，Set 会把这个键替换成只含一个字段的新切片。所以连续写入同一个属性时，前者保留多条，后者只保留最后一次设置的内容。

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

排查这类问题时，先看容器语义，再看读取接口取的是首字段、全部字段还是偏好字段。不要把“字段数量不同”误判成编码器丢数据。

先确认 Card 的字段容器

go-vcard 的 Card 定义为 map[string][]*Field。键是属性名，例如 TEL 或 EMAIL；值是字段指针切片，因此一个联系人可以同时保存多个电话号码或邮箱。

package main

import (
	"fmt"

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

func main() {
	card := make(vcard.Card)
	// Add 适合保留同一属性的多条记录，例如两个电话号码。
	card.AddValue(vcard.FieldTelephone, "+86-13800000001")
	card.AddValue(vcard.FieldTelephone, "+86-13800000002")
	fmt.Println(len(card[vcard.FieldTelephone])) // 2

	// SetValue 会替换 TEL 对应的整个字段切片，只留下一个值。
	card.SetValue(vcard.FieldTelephone, "+86-13800000003")
	fmt.Println(len(card[vcard.FieldTelephone])) // 1
	fmt.Println(card.Value(vcard.FieldTelephone))
}

这里的关键不是 AddValue 和 SetValue 是否“写入成功”，而是它们对同一个键的切片做了不同操作。源码中 Add 使用追加语义，Set 直接把键指向只包含一个 Field 的切片。

Add 的风险：把重复字段当成覆盖

当属性天然允许多值时，Add 是保留数据的写法。电话、邮箱、地址等字段可能同时存在家庭、工作或备用值，连续调用 Add 后，Values 能拿到完整列表。

func addContactChannels(card vcard.Card) {
	// 多个联系方式属于同一属性的不同 Field，不应该互相覆盖。
	card.AddValue(vcard.FieldEmail, "home@example.com")
	card.AddValue(vcard.FieldEmail, "work@example.com")
	card.AddValue(vcard.FieldTelephone, "+86-13800000001")
}

func showAll(card vcard.Card) {
	// Values 返回同一属性的全部值，适合检查 Add 是否完整保留数据。
	fmt.Println(card.Values(vcard.FieldEmail))
	fmt.Println(card.Values(vcard.FieldTelephone))
}

安全边界在于：追加不是“越多越好”。如果导入任务要求每个属性只留一个规范值，继续调用 Add 会产生重复联系人数据；这时应先定义去重或覆盖策略，不能把库的默认行为当成业务规则。

Set 的风险：把多值属性误写成单值

Set 适合表达“这个属性当前只认一个值”。例如服务端重新计算联系人的修订时间，或明确要用最新的主邮箱替换旧值。它的风险也很直白：对多值属性调用一次 Set，之前的字段会从当前 Card 中被移除。

func replacePrimaryEmail(card vcard.Card, email string) {
	// 只有业务确认该属性应当单值化时，才使用 SetValue 覆盖旧列表。
	card.SetValue(vcard.FieldEmail, email)
}

func keepOnePreferredPhone(card vcard.Card, phone string) {
	// 这里的 Set 会让 TEL 只剩一个 Field；调用方应记录这一取舍。
	card.Set(vcard.FieldTelephone, &vcard.Field{
		Value: phone,
		Params: vcard.Params{vcard.ParamPreferred: {"1"}},
	})
}

如果只是想把某条记录标记为首选，不一定要先清空所有记录。可以保留多个 Field，为目标字段设置 PREF 参数，再用 Preferred 或 PreferredValue 读取偏好项。这样“多值存储”和“主值选择”是两个独立问题。

读取接口会暴露什么

写入方式不同，读取结果也会从不同视角呈现：

Get 和 Value 不会因为属性存在多个字段就自动返回全部内容；需要完整列表时使用 Values。而 Preferred 会参考 PREF 参数，也兼容 TYPE=pref 的标记，因此“第一个字段”和“偏好字段”不一定是同一个字段。

把写入策略落到字段级清单

可以按下面的顺序给导入或更新逻辑划边界：

1. 先标记属性是多值还是单值，避免仅凭函数名决定策略。
2. 多值属性使用 Add 或 AddValue，并在写入后用 Values 检查数量。
3. 明确单值属性使用 Set 或 SetValue，在日志中记录被替换的旧值数量。
4. 如果需求只是选择主值，保留多个字段并设置偏好参数，再用 PreferredValue 读取。
5. 编码前确认卡片包含版本字段；这是 Encoder.Encode 的必要前提，不要把字段数量检查当成编码成功的替代品。

这套清单的价值在于把风险分成三类：数据被追加过多、旧数据被覆盖、读取接口观察错视角。每类问题都有对应的容器、写入或读取证据，排查时不需要猜测。

常见问题

连续两次调用 Set，为什么只剩第二个值？

因为第二次调用把同一个键重新指向只含一个 Field 的切片。需要保留两个字段时，改用 Add；需要保留多字段但选择一个主字段时，保留切片并设置 PREF。

Values 返回 nil 是不是 Add 失败？

不一定。Values 对不存在的键返回 nil，对已经写入的键返回字段值列表。先确认属性键完全一致，例如不要把 TEL 和自定义的大小写写成两个不同键。

Set 能不能只替换切片中的某一个字段？

不能直接做到。Set 的语义是替换该键对应的整个字段列表；如果只改一项，应先取得或构造完整列表，再按业务规则重建切片。

归根结底，Add 与 Set 的差别来自 Card 的切片模型：一个负责追加，一个负责替换。先决定字段是否允许多值，再选择写入方法，最后用正确的读取接口确认结果，字段数量就不会再成为“神秘变化”。