Go Hamba Avro 怎样把结构体编码成记录

用 Go 的 Hamba Avro 把结构体编码成 Avro record，关键不是手工拼字节，而是先让三件事对齐：schema 里的 record 字段、结构体上的 avro 标签，以及 Go 字段的实际类型。一次性编码可以调用 avro.Marshal；如果同一个 schema 要连续写入多个对象，则使用 NewEncoder 把结果交给 io.Writer。

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

先把 Avro record 字段和 Go 字段对齐

Hamba Avro 的映射关系可以先按一个最小 record 来理解：Avro 的 long 对应 Go 的 int64，string 对应 string，整个 record 对应一个 Go 结构体。schema 里的字段名是 Avro 文档的一部分，结构体标签则负责把 Go 字段接到这些名字上。

package main

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

const orderSchema = `{
  "type": "record",
  "name": "order",
  "namespace": "demo.orders",
  "fields": [
    {"name": "id", "type": "long"},
    {"name": "buyer", "type": "string"}
  ]
}`

type Order struct {
    // avro 标签把 Go 字段连接到 schema 的 id 字段。
    ID int64 `avro:"id"`
    // 标签名与 schema 一致时，编码器可以按 record 字段写入。
    Buyer string `avro:"buyer"`
}

func parseOrderSchema() (avro.Schema, error) {
    // 解析一次后可以复用 schema，不必为每条记录重复解析文本。
    return avro.Parse(orderSchema)
}

这里的 avro:"id" 不是 JSON 标签的替代写法，而是告诉 Avro 编码器这个字段对应哪个 schema 名称。如果标签、字段类型或 schema 结构对不上，问题应当在 schema 解析或编码返回的 error 中处理，而不是继续发送一段不确定的字节。

解析 schema 后调用 avro.Marshal

只需要把一条记录编码成字节时，avro.Marshal 是最直接的入口。它接收已经解析的 schema 和待编码值，返回 Avro 二进制数据；调用方负责判断 error，并决定把字节写入消息、文件或其他传输层。

func encodeOrder(order Order) ([]byte, error) {
    schema, err := avro.Parse(orderSchema)
    if err != nil {
        // schema 不合法时不要继续调用 Marshal。
        return nil, err
    }

    data, err := avro.Marshal(schema, order)
    if err != nil {
        // 字段类型或值与 schema 不兼容时返回编码错误。
        return nil, err
    }
    return data, nil
}

实际服务通常会在初始化阶段解析并缓存 schema，再把 schema 传给多个编码调用。这样做的重点不是让字节“看起来像 JSON”，而是始终由同一个 schema 解释字段顺序和类型。若还需要回读，可以把编码结果交给 avro.Unmarshal，但目标参数必须是结构体指针。

按 Avro 类型选择 Go 字段类型

编码前先检查类型表，比收到错误后猜原因更省时间。常用映射可以这样记：

官方类型转换说明还提醒了 int 的平台宽度和无符号整数的取值风险。跨机器、跨语言或长期存储的 record，建议优先写成 int32、int64 这类宽度明确的 Go 类型，并让 schema 的 int/long 与之对应。可空字段则要先确定 union 形态，再选择指针或库文档支持的 union 表达方式。

连续写入时改用 NewEncoder

当一个文件或消息流要连续写入多条同构记录，可以把 schema 和输出目标交给 NewEncoder。构造编码器时处理一次错误，之后每条业务对象调用 Encode，这样比每次都重新组织输出边界更清楚。

package main

import (
    "bytes"
    "fmt"

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

func encodeOrders(orders []Order) ([]byte, error) {
    out := &bytes.Buffer{}
    encoder, err := avro.NewEncoder(orderSchema, out)
    if err != nil {
        // schema 解析失败时，编码器不会进入可用状态。
        return nil, err
    }

    for _, order := range orders {
        // 每条结构体都按同一 record schema 编码。
        if err := encoder.Encode(order); err != nil {
            return nil, fmt.Errorf("encode order %d: %w", order.ID, err)
        }
    }
    return out.Bytes(), nil
}

NewEncoder 适合把输出直接接到文件、网络 writer 或缓冲区；如果只有一条记录，Marshal 的返回值更容易组合。两种 API 都不会替你决定业务层的重试、落盘或消息确认策略，编码成功只说明这一层产生了字节。

用 Unmarshal 做最小回读检查

写入流程需要一个简单的边界确认时，可以使用相同 schema 把字节回填到结构体指针。这个动作不是替代业务测试，而是帮助确认 schema、标签和基础类型没有在编码入口处错位。

func decodeOrder(data []byte) (Order, error) {
    schema, err := avro.Parse(orderSchema)
    if err != nil {
        return Order{}, err
    }

    var order Order
    // Unmarshal 的目标必须是可写入的结构体指针。
    if err := avro.Unmarshal(schema, data, &order); err != nil {
        return Order{}, err
    }
    return order, nil
}

最后可以用三项清单收口：schema 的 record 名称和字段类型是否固定；每个 Go 字段是否有正确的 avro 标签；连续写入时是否只复用同一个合法 schema 和 writer。满足这三点，结构体编码成 Avro record 就有了清晰的输入、转换和输出边界。

常见问题

Go 结构体字段名和 Avro 字段名不一样怎么办？

在字段上使用 avro:"schema_name" 标签，把 Go 字段连接到 Avro schema 中的名字，不要依赖字段名猜测。

一条记录该用 Marshal 还是 NewEncoder？

单条记录或需要直接获得 []byte 时用 Marshal；连续向同一个 writer 写入多条记录时用 NewEncoder。

为什么 Encode 前还要处理 NewEncoder 的错误？

NewEncoder 需要先根据 schema 创建编码器。schema 无法解析时编码器就不可用，应先返回构造错误。

Unmarshal 为什么要传结构体指针？

因为解码过程需要把字段写回目标对象；传值无法让调用方拿到被填充的结构体。