gogen-avro生成强类型结构体并配合confluent-kafka-go/v2的avrov2.Serializer是最稳路径，因其自动处理magic byte、schema ID前缀、registry缓存与兼容性校验，避免手拼二进制或使用json.Marshal导致的解码失败、SchemaRegistryError及静默数据丢失等问题。
直接用 gogen-avro 生成强类型结构体 + confluent-kafka-go/v2 的 avrov2.Serializer，是最稳、最省心的路径。 其他方式（比如手写 elodina/go-avro 序列化逻辑）容易漏掉 schema ID 前缀、版本兼容校验或 registry 重试机制，线上出错难定位。
为什么不能直接用 json.Marshal 后塞进 Kafka？
Avro 消息不是纯 JSON。Kafka 中的 Avro 记录必须以 00 开头的 magic byte + 4 字节 big-endian schema ID 打头，否则消费者（尤其是 Confluent 客户端）会报 SchemaRegistryError: invalid magic byte 或直接跳过解析。手拼二进制极易出错，且无法享受 schema 演化检查。
常见错误现象：
- 消费者收到消息但解码为空 struct，无报错 —— 很可能是没加 magic byte 和 schema ID 前缀
- 报错
SchemaRegistryError: Schema not found—— schema ID 存在但 registry 里没注册对应版本，或凭证/URL 配置错 - 字段值全为零值 —— writer schema 和 reader schema 不匹配，且未启用兼容性检查
gogen-avro 生成代码时的关键参数和陷阱
生成的 Go struct 是整个链路类型安全的基础。不配对参数，后续序列化/反序列化会静默失败。
-
--package必须显式指定，否则默认包名是main，无法被其他模块 import - 如果 Avro schema 含
union类型（如["null", "string"]），默认生成带interface{}的字段；加--short-unions才生成具体 Go 类型（如*string），避免运行时 panic - 务必保留
.avsc文件在 Git 中，并与生成的 Go 文件一起提交 —— schema 是契约，不是临时产物 - 不要用
go:generate自动覆盖已有文件，先 diff 再确认；schema 小改可能引发字段顺序变化，导致 OCF 解析错位
序列化时如何正确注入 schema ID 并发往 Kafka
Confluent 的 avrov2.Serializer 会自动查 registry、缓存 codec、加前缀、处理 null 字段，你只管传 struct 指针。
关键点：
- 初始化
schemaregistry.NewClient时，url必须带协议（http://或https://），且不能末尾带/ -
avrov2.NewSerializerConfig()默认启用AutoRegisterSchemas，生产环境建议关掉，改用 CI 流程预注册 schema，避免上线时因权限问题卡住 - 调用
ser.Serialize(topic, &myStruct)时，topic参数仅用于查找 subject 名（通常是topic-value），不参与序列化计算 —— 确保你的 registry 里已存在该 subject - 如果要复用同一 schema 给多个 topic，别硬编码 topic 名；用
avrov2.WithSubjectNameStrategy显式控制 subject 名生成逻辑
真正容易被忽略的是：registry 的兼容性级别（BACKWARD/FORWARD）是在 subject 级别配置的，不是客户端能 override 的。哪怕你生成了完全兼容的新 schema，如果 registry 里该 subject 设的是 BACKWARD，而你试图用旧 consumer 读新数据，照样失败 —— 这个得靠运维配合，不是写代码能绕开的。
