Go go-vcard 的版本转换为什么不能只替换 VERSION 文本

如果你把 vCard 的版本迁移理解成把文本里的 VERSION:3.0 改成 VERSION:4.0，很容易得到一张“看起来是 4.0、参数语义却还是旧写法”的卡片。go-vcard 的正确思路是先把文本解析成 Card，再让 ToV4 处理库明确覆盖的兼容语义，最后交给 Encoder 输出。

VERSION 只描述卡片版本，不会自动改写所有字段参数。对 go-vcard 来说，版本转换至少还要关注字段参数、重复字段和编码器要求；当前实现会把旧式 TYPE=pref 转成 PREF=1，但不会替你完成所有可能的业务迁移。

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

先看清 go-vcard 的 Card 模型

go-vcard 把一张联系人卡片表示成 Card，本质上是 map[string][]*Field。键是属性名，例如 VERSION、FN、TEL；值是字段切片，因此同一个属性可以出现多次。每个 Field 不只保存 Value，还保存 Params 和可选的 Group。

这也是手工替换字符串容易出问题的地方：你改到了版本行，却没有触碰 TEL 或 EMAIL 上的参数，也没有处理同一属性的多个字段。迁移对象不是一行文本，而是 Card 里的字段集合。

为什么只改 VERSION 不等于完成迁移

在 go-vcard 的源码中，ToV4 首先读取 card.Value(FieldVersion)。如果版本已经以 4. 开头，函数直接返回；否则它用 SetValue(FieldVersion, "4.0") 写入版本，再遍历 Card 中的其它字段。

遍历时，当前实现专门识别参数集合里的旧式 pref 类型：它先删除这个类型，再设置标准化的 PREF=1。所以两段文本虽然都写着 4.0，下面这一段的优先级语义并不等价：

VERSION:4.0
TEL;TYPE=cell,pref:13800000000

VERSION:4.0
TEL;TYPE=cell;PREF=1:13800000000

这不是说所有 vCard 差异都由 ToV4 解决。它的职责是一个明确、有限的兼容处理函数；未知参数、业务自定义字段、联系人系统对字段的额外约定，仍然需要你在业务层决定。

ToV4 实际补了哪一个兼容语义

把转换逻辑拆开看，会发现它至少有两个可以单独检查的结果：卡片级的 VERSION 被统一设为 4.0，字段级的旧式 TYPE=pref 被改成参数键 PREF、值为 1。它不会把每一个字段的值重新组织，也不会把重复属性合并成一个字段。

因此，迁移时可以把“库会处理什么”和“业务必须确认什么”分成两列：

按解析、转换、编码组织 Go 代码

推荐把转换放在结构化对象层，而不是对输入字符串做替换。下面的函数只处理一张卡片，示例中的中文注释说明了输入错误、转换位置和输出错误；它没有假设联系人内容已经通过本地运行验证。

package main

import (
	"fmt"
	"io"

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

// convertToV4 负责把一张 vCard 从文本层交给 Card 模型，再编码回文本。
func convertToV4(input io.Reader, output io.Writer) error {
	// Decoder 负责处理字段、重复属性和参数，不要先手工替换 VERSION。
	card, err := vcard.NewDecoder(input).Decode()
	if err != nil {
		return fmt.Errorf("decode vcard: %w", err)
	}

	// ToV4 会设置 4.0，并处理库明确支持的旧式 pref 参数。
	vcard.ToV4(card)

	// Encoder 要求 Card 存在 VERSION 字段，并负责输出规范的字段行。
	if err := vcard.NewEncoder(output).Encode(card); err != nil {
		return fmt.Errorf("encode vcard: %w", err)
	}
	return nil
}

这里的顺序有一个实际好处：读取失败、版本处理和写出失败各自有清晰边界。Encoder.Encode 还要求 Card 中存在 VERSION 字段；如果你自己构造 Card 而忘记添加它，直接编码会返回 vcard: VERSION field missing。

已经是 4.x 时，为什么还要留意早退

当前 ToV4 使用 strings.HasPrefix(version, "4.") 判断是否早退。这意味着版本值已经是 4.0、4.1 等 4.x 形式时，函数不会继续遍历字段参数。

所以不能把“调用了 ToV4”理解成“无条件扫描并清理所有旧参数”。如果你的输入可能出现“VERSION 已经是 4.0，但某些字段仍带 TYPE=pref”的混合数据，需要在业务层先决定是否要单独规范化参数，或者在进入转换前把这类数据标记出来。不要未经确认就全量重写未知参数，因为它们可能是下游系统的扩展约定。

func versionOf(card vcard.Card) string {
	// Value 读取同名属性的第一个字段，适合做迁移前的快速分流。
	return card.Value(vcard.FieldVersion)
}

func needsParameterReview(card vcard.Card) bool {
	// 只把存在旧式 pref 类型的字段交给业务策略判断。
	for key, fields := range card {
		if key == vcard.FieldVersion {
			continue
		}
		for _, field := range fields {
			if field.Params.HasType("pref") {
				return true
			}
		}
	}
	return false
}

这个检查函数不负责改数据，它只把“需要人工或业务策略确认”的卡片挑出来。这样可以把自动转换与例外处理分开，避免把一个看似简单的版本迁移变成不可追踪的全字段重写。

迁移前后的检查清单

1. 确认输入确实能被 NewDecoder 解析，而不是把未解析的字符串当作已知结构。
2. 检查 VERSION、FN、TEL、EMAIL、ADR 等业务必需字段是否允许重复。
3. 特别关注字段参数：旧式 TYPE=pref 与 PREF=1 不能只靠文本相似来判断等价。
4. 调用 ToV4 后再用 Encoder 输出，并保留错误上下文。
5. 对已经是 4.x 的输入单独检查，因为当前实现会提前返回。
6. 把扩展字段、隐私字段和下游应用的兼容性放进业务回归范围，不要把库函数的有限转换当成完整规范迁移器。

几个容易混淆的问题

手工 SetValue 能不能替代 ToV4？

只能替代“设置版本字段”这一小部分。SetValue 会把指定属性替换成一个字段，但不会遍历其它字段，也不会把 TYPE=pref 转成 PREF=1。如果只需构造一张已知为 4.0 的新卡片，可以直接设置；如果是旧卡片迁移，优先使用 ToV4 并检查边界。

ToV4 会删除所有旧版本字段吗？

不会。根据当前实现，它主要设置 VERSION=4.0，并规范化带旧式 pref 类型的参数；其它字段和大多数参数保持在 Card 中。更大范围的字段映射要由业务规则或专门的 vCard 兼容层完成。

为什么一定要经过 Encoder？

因为 Card 是内存结构，直接改 map 并不会自动得到正确的 vCard 文本。Encoder 会检查 VERSION 是否存在，按属性名组织字段，并处理字段值中的转义。输出阶段也应当保留写入错误，避免迁移成功但文件不完整。

总结一下：go-vcard 的版本迁移应该看 Card 结构，不要只看 VERSION 字符串。用 Decoder → ToV4 → Encoder 处理库明确支持的转换，再对 4.x 早退、重复字段、未知参数和下游兼容性做业务决策，这样才能知道哪些变化是自动完成的，哪些变化仍然需要你负责。