必须用 gogen-avro 生成类型安全结构体，因手动编解码易致 runtime panic 和字段错位；generic 模式缺乏编译期 schema 校验，无法保障命名空间、union、zigzag 等规则正确执行。
Go 里用 Avro 做序列化，别直接手写编解码逻辑——必须用 gogen-avro 生成类型安全的结构体，否则 runtime panic 和字段错位是常态。
为什么不能手动实现 avro.Encoder / avro.Decoder
Avro 的二进制编码强依赖 schema 顺序、字段名匹配、union 分支判定和 ZigZag 编码规则。Go 官方没有内置 Avro 支持，第三方库如 github.com/hamba/avro 或 github.com/linkedin/goavro 仅提供 generic 模式（即运行时靠 map[string]interface{} 解析），无法保证字段类型安全，且对嵌套 record、enum、fixed 类型支持不完整。
常见错误现象：
- 反序列化后 struct 字段值为零值，但无报错（实际是字段名大小写或命名空间不匹配）
- union 类型字段读出来是
nil，但 schema 明确写了默认值 - int 字段反序列化成负数，实为 ZigZag 编码未被正确处理
根本原因：generic 模式跳过了 schema 校验阶段，把解析权交给开发者——而 Avro 的 schema 约束（如命名空间、aliases、default）必须在编译期绑定到 Go 类型上才可靠。
gogen-avro 生成代码前必须检查 schema 的 3 个硬约束
schema 文件（.avsc）哪怕语法合法，也可能导致 gogen-avro 生成失败或运行时崩溃。以下三点必须人工确认：
- 所有 record、enum、fixed 类型必须带
namespace，且引用时用完整路径（如"com.example.User"），不能省略或写成"User" - 同一文件内不能有同名但不同 namespace 的类型（
gogen-avro会覆盖生成，导致 struct 冲突） - union 类型中不能出现两个语义等效但声明路径不同的类型（例如
["com.v1.Address", "com.v2.Address"]），即使它们字段完全一致，Avro 解析器也无法自动归一
执行生成命令前，建议先用官方校验工具跑一遍：java -jar avro-tools.jar compile schema user.avsc /tmp/out，确认无 warning 才继续。
Colly 是一个用于 Go 语言的快速开源爬取和爬虫框架。它适用于从简单的页面提取到异步爬虫处理大量页面集合，支持请求回调和结构化解析。
序列化到文件时必须显式写入 avro.OcfWriter 的 schema
Avro 对象容器文件（OCF）要求 schema 必须嵌入文件头。Go 中若只用 io.WriteSeeker 写裸二进制，下游系统（如 Spark、Kafka Connect）将无法识别数据格式。
正确做法是使用 gogen-avro 生成的 WriteToOCF 方法，或手动构造 avro.OcfWriter：
fw, err := avro.NewOcfWriter(
file,
avro.WithSchema(schema),
avro.WithCodec(avro.CodecSnappy), // 可选压缩
)
if err != nil {
panic(err)
}
defer fw.Close()
for _, u := range users {
if err := fw.Write(u); err != nil {
panic(err)
}
}
注意：schema 必须是 *avro.Schema 类型，不能传字符串或 JSON 字节流；若用 gogen-avro，它已为你导出 UserSchema() 函数，直接调用即可。
反序列化时别忽略 avro.OcfReader 的 schema 兼容性检查
Avro 支持 schema 演进，但 Go 层需主动启用。如果 reader 使用的 schema（即你代码里硬编码的 struct）比文件中的旧 schema 多字段，必须设置默认值，否则 OcfReader.Read() 会返回 avro.ErrMissingDefault。
解决方案分两步：
- 在 .avsc 中为新增字段声明
"default": null或具体值（如"default": 0） - 生成代码后，用
gogen-avro提供的ReadWithSchema方法，传入运行时获取的文件 schema（通过reader.Schema()）而非本地 struct schema
最容易被忽略的一点：Kafka 场景下，consumer 从 Schema Registry 拉取的 schema 版本可能与本地生成代码的版本不一致，此时必须用动态 schema 构造 avro.NewGenericDatumReader，再手动映射到 struct——这正是 gogen-avro 的 UnmarshalGeneric 方法存在的意义。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
