Go Hamba Avro 怎样使用读者 Schema 读取演进后的记录

Avro 的二进制记录通常由生产者按 writer Schema 写出，消费者却可能已经换成了包含新字段的 reader Schema。两份 Schema 不能只靠字段名“猜”着读：应先让 Hamba Avro 做兼容性解析，再把解析后的复合 Schema 交给解码器。这样新增字段可以使用默认值，旧字段可以被忽略，允许的类型提升也会在进入业务结构体前完成。

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

核心做法是 SchemaCompatibility.Resolve(reader, writer)，参数顺序不要写反；它返回的不是一条普通 reader Schema，而是一份知道 writer 编码布局、同时按 reader 语义读取的复合 Schema。

• writer Schema：描述已经写入的字节布局。
• reader Schema：描述当前消费者希望得到的字段和类型。
• 复合 Schema：连接两者，负责忽略旧字段、补默认值和处理允许的类型提升。

先把 writer Schema 和 reader Schema 放进同一个解析边界

下面的旧版本有 id、amount 和将被淘汰的 legacy_note。新版本把 amount 从 Avro int 提升到 long，增加带默认值的 trace_id，并不再接收 legacy_note。这四个变化正好覆盖最常见的记录演进边界。

package main

import (
    "bytes"
    "fmt"
    "log"

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

const writerSchemaJSON = `{
  "type": "record", "name": "Payment", "namespace": "demo",
  "fields": [
    {"name": "id", "type": "long"},
    {"name": "amount", "type": "int"},
    {"name": "legacy_note", "type": "string"}
  ]
}`

const readerSchemaJSON = `{
  "type": "record", "name": "Payment", "namespace": "demo",
  "fields": [
    {"name": "id", "type": "long"},
    {"name": "amount", "type": "long"},
    {"name": "trace_id", "type": "string", "default": ""}
  ]
}`

type WriterPayment struct {
    ID         int64  `avro:"id"`
    Amount     int32  `avro:"amount"`
    LegacyNote string `avro:"legacy_note"`
}

type ReaderPayment struct {
    ID      int64  `avro:"id"`
    Amount  int64  `avro:"amount"`
    TraceID string `avro:"trace_id"`
}

func main() {
    writer, err := avro.Parse(writerSchemaJSON)
    if err != nil {
        log.Fatal(err) // Schema 不可信时直接停止，不把半解析结果交给业务层。
    }
    reader, err := avro.Parse(readerSchemaJSON)
    if err != nil {
        log.Fatal(err) // reader Schema 也必须是完整、可解析的契约。
    }

    oldRecord := WriterPayment{ID: 1001, Amount: 25, LegacyNote: "old"}
    data, err := avro.Marshal(writer, oldRecord)
    if err != nil {
        log.Fatal(err) // 这里只产生示例字节，生产者通常从消息或文件得到它。
    }

    resolver := avro.NewSchemaCompatibility()
    resolved, err := resolver.Resolve(reader, writer)
    if err != nil {
        log.Fatalf("schema rejected: %v", err) // 不兼容记录在边界处拒绝。
    }

    decoder := avro.NewDecoderForSchema(resolved, bytes.NewReader(data))
    var current ReaderPayment
    if err := decoder.Decode(¤t); err != nil {
        log.Fatal(err) // 解码失败不应被当成业务默认值吞掉。
    }
    fmt.Printf("id=%d amount=%d trace_id=%q\n", current.ID, current.Amount, current.TraceID)
}

这里 Resolve 的顺序是 reader, writer。amount 的写入类型是 int，读取类型是 long，属于允许的提升；trace_id 在旧数据里不存在，因此必须在 reader Schema 里声明默认值。若 reader 新增了没有默认值的必需字段，解析会直接失败。

把复合 Schema 交给 Decoder，而不是只传 reader Schema

一个容易误用的写法是直接把 reader 传给 NewDecoderForSchema。这样解码器只知道当前字段定义，并不知道旧二进制中还存在 legacy_note，也不会自动建立 writer 到 reader 的字段动作表。复合 Schema 才保存了“读取哪个、跳过哪个、补哪个默认值”的边界。

Hamba Avro 的 NewDecoderForSchema 接收已经解析好的 Schema 和 io.Reader。需要从字符串解析时可以用 NewDecoder，但跨版本记录要先完成 Resolve，否则无法表达两份 Schema 的差异。

把默认值、忽略字段和输入上限当成控制点

Schema 演进解决的是数据契约，不等于输入已经安全。消息、文件或 HTTP 上传内容都可能来自不可信来源。要保护解码边界，至少记录三类动作：哪些旧字段被忽略，哪些字段由默认值补齐，以及字符串和 bytes 的最大允许长度。

cfg := avro.Config{
    MaxByteSliceSize: 1 

MaxByteSliceSize 的默认值是 1 MiB；自定义配置时仍应结合消息大小、队列限制和业务字段上限重新设定。不要为了“兼容”而把限制关闭，也不要把解码错误转换成空结构体后继续扣款、入账或写库。

上线前只检查四个兼容性信号

1. 两份 Schema 的 record 名称或别名是否能匹配。
2. reader 新增字段是否都有合理默认值。
3. 类型变化是否属于 Avro 允许的提升，而不是把字符串直接当数字读取。
4. 解码失败是否能被记录、隔离和重放，而不会落入业务成功路径。

实际接入时可以把 writer Schema 的指纹与 reader Schema 的版本写入消息元数据或审计日志。记录这些标识有助于定位哪一次发布引入了不兼容变化，但不要把完整载荷写入日志。对于同一 writer Schema 的大量消息，也可以缓存已解析的复合 Schema，减少重复构建，同时保留版本切换时的显式失效策略。

常见问题

reader Schema 能自动从 Avro 字节中恢复吗？

不能把它当成默认能力。裸 Avro 二进制通常需要解码端持有 writer Schema；拿到 writer Schema 后，才可以和当前 reader Schema 调用 Resolve。

删除字段后还需要在 Go 结构体里保留它吗？

不需要。reader Schema 不声明该字段时，复合 Schema 会为旧字段建立忽略动作；Go 结构体只保留当前业务需要的字段。

新增字段没有默认值怎么办？

不要在解码后用零值掩盖问题。为字段设计兼容默认值，或先发布能识别旧记录的 reader Schema，再让生产者开始写新字段。

参考资料：Hamba Avro v2 官方包文档与项目中的 SchemaCompatibility、Decoder API 说明。本文示例为原创说明，配图为静态结构图，不是实际运行截图。