Go Hamba Avro 怎样为可空字段选择联合分支

我第一次把一个“可以没有值”的 Go 字段接到 Avro schema 时，直觉是把它声明成普通的 string，再在业务层用空字符串表示缺省。真正编码后才发现，Avro 的可空字段不是“约定一个特殊字符串”，而是一个明确的联合：null 和具体类型各自占一个分支。Go Hamba Avro 对这个场景已经提供了直接映射，关键在于先区分 nullable union 和多分支 union，再决定用 *T 还是 UnionConverter。

官方地址：https://pkg.go.dev/github.com/hamba/avro/v2

只有 null 与一个具体类型组成的二选一联合，优先用 *T：字段为 nil 就表示 null 分支，有值就表示具体类型分支。联合里有多个业务类型时，再让一个带指针接收者的结构体实现 UnionConverter，把分支选择写成显式规则。

• 影响面：普通可选字段会在编码时进入错误的类型或缺省分支，消费者看到的不是预期的 Avro union。
• 触发条件：schema 使用了包含 null 的联合，但 Go 字段仍用零值类型；或者多分支联合没有定义唯一的活跃成员。
• 根因：把 Avro 的“分支选择”误当成 Go 的“零值判断”，没有让 schema、Go 类型和编码入口保持一一对应。

先把可空字段看成二选一联合

Hamba Avro 文档把 nullable union 定义为两个 schema 组成的联合，其中一个必须是 null，另一个可以是 string、int、记录或其他支持的类型，例如 ["null", "string"] 与 ["string", "null"]。顺序可以不同，但它们都表达“无值或一个字符串”。

这和 Go 的空字符串不是同一件事。空字符串仍然是一个真实的字符串值；nil 才能表达没有选择具体类型分支。也就是说，下面这个 schema 的缺省分支不是业务约定，而是编码格式的一部分：

{
  "type": "record",
  "name": "Profile",
  "fields": [
    {
      "name": "nickname",
      "type": ["null", "string"],
      "default": null
    }
  ]
}

排查这类问题时，我会先把影响面收窄到三处：schema 的联合成员、Go 字段的实际类型、最终调用的编码函数。三处只要有一处把“无值”改写成了普通零值，后面再调整标签或字段名都不会真正解决问题。

简单场景直接用 *T

Hamba Avro 对 nullable union 接受指针形式。对于 ["null", "string"]，Go 字段可以写成 *string；如果具体类型是 int，则写成对应的整数指针。切片是一个特殊情况，文档允许在可空联合中直接使用切片，因此不要为了“统一风格”盲目给切片再套一层指针。

package main

import (
    "fmt"

    "github.com/hamba/avro/v2"
)

const profileSchema = `{
  "type": "record",
  "name": "Profile",
  "fields": [{
    "name": "nickname",
    "type": ["null", "string"],
    "default": null
  }]
}`

type Profile struct {
    // 指针的 nil 与非 nil 分别对应 null 和 string 分支。
    Nickname *string `avro:"nickname"`
}

func stringPtr(value string) *string {
    // 单独的辅助函数让“有值分支”不会误写成空指针。
    return &value
}

func encodeProfile() ([]byte, error) {
    profile := Profile{
        // 改成 nil 就是选择 null 分支，而不是编码空字符串。
        Nickname: stringPtr("蓝河"),
    }

    // Marshal 根据 schema 和字段类型选择 union 的具体分支。
    data, err := avro.Marshal(profileSchema, profile)
    if err != nil {
        // 将编码错误交给调用方，避免把失败伪装成空 payload。
        return nil, fmt.Errorf("编码 Profile 失败: %w", err)
    }
    return data, nil
}

这段代码的重点不是辅助函数，而是字段的语义：Nickname: nil 表示 null，Nickname: stringPtr("") 表示一个存在但内容为空的字符串。两者在消费端可能触发完全不同的默认值、展示和更新策略。

第一次不适应：把默认值当成了 Go 零值

我遇到的第一个症状是“字段明明没填写，接收端却拿到了一个字符串”。原因通常不是 Hamba Avro 随机选错，而是发送端在组装结构体时已经把空字符串写进了 string 字段。到了编码阶段，库只能看到一个合法的字符串值，自然不会替你改成 null。

这里有三个容易混淆的层次：

如果字段还要参与“未修改”和“主动清空”的区分，单独的 *T 只能表达两种状态，业务上可能还需要额外的更新标记。不要把 Avro union 误当成完整的补丁语义；它只负责序列化时的类型分支。

联合超过两个分支时，换成 UnionConverter

当 schema 变成 ["null", "int", "Event"] 或其他多个业务分支时，单个 *T 已经无法表达全部选择。这个时候可以定义一个联合结构体，让它实现 Hamba Avro 的 UnionConverter 接口：

type Event struct {
    // 记录分支的字段名必须和 Avro record 对应。
    Name string `avro:"name"`
}

type Choice struct {
    // 约定同一时刻最多只有一个成员非 nil。
    Count *int
    Event *Event
}

// ToAny 把 Go 联合结构体转换为 schema 允许的具体分支。
func (c *Choice) ToAny() (any, error) {
    if c.Count != nil && c.Event != nil {
        return nil, fmt.Errorf("联合分支同时有值")
    }
    if c.Count != nil {
        return c.Count, nil
    }
    if c.Event != nil {
        return c.Event, nil
    }
    return nil, fmt.Errorf("联合分支没有值")
}

// FromAny 把解码结果收敛回 Go 结构体，并拒绝未知类型。
func (c *Choice) FromAny(payload any) error {
    c.Count = nil
    c.Event = nil

    switch value := payload.(type) {
    case int:
        // 解码器给出 int 时，激活 Count 分支。
        c.Count = &value
    case Event:
        // 命名 record 按实际解码类型匹配 Event 分支。
        c.Event = &value
    default:
        return fmt.Errorf("未知的联合类型 %T", payload)
    }
    return nil
}

这个接口的两个方向要分开想：ToAny 负责“我准备发送哪个分支”，FromAny 负责“收到的值应该落在哪个成员”。Hamba Avro 文档特别提醒，接口方法使用指针接收者时，参与联合映射的类型也必须以指针形式满足接口；如果把方法改成值接收者或把字段写成不匹配的形状，自动识别就会失效。

修复动作：让每个联合只保留一个明确活跃分支

在多分支场景中，我会把“分支选择”当成一个小型不变量，而不是让调用方自由填充结构体。编码前检查“零个、一个、多个”三种状态：零个通常是错误或专门的 null 分支；一个才允许交给 ToAny；多个必须立即报错。这样可以把错误挡在消息离开进程之前。

另外，不要只凭字段名猜测命名类型。Hamba Avro 对 any 联合会按类型或名称解析；原始类型有预注册行为，而命名类型、map 和 slice 需要按文档要求注册。若应用选择通用 any，就要把类型注册和解析失败策略一起纳入配置，而不是等到线上遇到“解析成 map”才补救。

func validateChoice(choice *Choice) error {
    if choice == nil {
        // nil 联合容器是否允许，要由外层 schema 的 null 分支决定。
        return fmt.Errorf("联合容器不能为 nil")
    }
    if choice.Count != nil && choice.Event != nil {
        // 两个成员同时有值会让编码选择失去确定性。
        return fmt.Errorf("Count 与 Event 不能同时有值")
    }
    if choice.Count == nil && choice.Event == nil {
        // 没有显式 null 分支时，空联合也必须作为输入错误处理。
        return fmt.Errorf("至少选择一个联合分支")
    }
    return nil
}

如果 schema 本身包含 null，空值规则要和外层字段的指针关系统一：外层指针为 nil 可以表示整个联合为 null；外层非 nil 时，内部 Choice 再负责 int 与 Event 的二选一。这样分层后，代码能清楚回答“是字段缺失，还是字段存在但分支无效”。

复查配置：什么时候使用 any，什么时候保持类型安全

Hamba Avro 同时支持 map[string]any、指针和 any 形式的联合。我的选择顺序是：nullable 二选一用 *T；业务分支固定且需要编译期可读性时用 UnionConverter；只有 schema 很动态、确实需要按名称分派时才用 any。

使用 any 时要特别留意配置中的联合解析策略。文档列出了 UnionResolutionError 与 PartialUnionTypeResolution：前者决定无法解析类型时是否报错，后者决定只注册部分类型时是否仍尝试解析已知分支。生产代码更适合显式选择失败策略，并记录未知类型，而不是默认把所有不能解析的值都降级成通用 map。

防复发清单

1. 先读 schema，确认它是 nullable 二选一还是多分支联合。
2. nullable 字段优先使用 *T，并区分 nil 与空字符串、零整数。
3. 多分支联合固定一个类型安全容器，ToAny 与 FromAny 只接受明确成员。
4. 检查接口是否由指针类型实现，检查命名 record 的解码类型是否和 type switch 一致。
5. 使用 any 时提前决定注册、未知类型和部分解析的失败策略。

回头看，这次问题并不是“Avro 联合太复杂”，而是我一开始没有把 schema 分支当成数据模型的一部分。只要把 null、具体值和多分支类型分别映射到 *T、单活跃成员和 UnionConverter，Hamba Avro 的选择规则就会从隐含行为变成代码里看得见的边界。

常见问题

["string", "null"] 也能用 *string 吗？

可以。关键条件是联合只有两个 schema，且其中一个是 null；不要把联合数组下标当成 Go 字段的业务值。

为什么不用空字符串表示缺省？

空字符串仍属于 string 分支，接收端无法据此区分“没有值”和“有值但内容为空”。需要表达 null 时应保留指针的 nil 状态。

自定义联合结构体为什么一定要注意指针？

UnionConverter 的方法通常以指针接收者实现，库需要识别这个接口来调用编码和解码转换；值类型与指针类型不一致时，自动映射就可能无法命中。

any 联合解析失败怎么办？

先检查命名类型是否已经注册，再决定是否开启严格的解析错误策略。不要把未知类型静默降级成 map，除非这正是业务可以接受的兼容方案。