📚 课程目录第3章 Avro Schema 详解

3. Avro Schema 详解：Record、Enum、Array、Map、Union 类型定义

好，咱们进入 Avro Schema 的核心地带。前面聊了基础类型和 Schema 的 JSON 骨架，现在要啃硬骨头了——复杂类型。说白了，这些才是真正支撑起业务数据结构的基石。

我个人习惯把 Avro 的复杂类型分成两类：容器型（Record、Array、Map）和标记型（Enum、Union、Fixed）。今天咱们重点把前五个讲透，Fixed 留到后面讲序列化细节时再提。

核心观点：Avro 的复杂类型不是凭空设计的，它直接映射了大多数编程语言中的数据结构。你写 Java 的 POJO、写 Go 的 struct、写 Python 的 dict，都能在 Avro 里找到对应。

3.1 Record：数据结构的骨架

Record 是 Avro 里最常用的复杂类型，没有之一。它对应着关系数据库里的「表」、Java 里的「类」、JSON 里的「对象」。我做过统计，在我经手的项目中，90% 以上的 Schema 顶层都是 Record。

先看一个最朴素的 Record 定义：

{
  "type": "record",
  "name": "User",
  "namespace": "com.example.model",
  "doc": "用户基本信息",
  "fields": [
    {"name": "id", "type": "long", "doc": "用户ID"},
    {"name": "name", "type": "string"},
    {"name": "age", "type": "int", "default": 0}
  ]
}

这里有几个关键点，我当年踩过坑：

name 和 namespace：name 是必填的，namespace 可选但强烈建议填。为什么？因为 Avro 的 Schema 解析器会用 namespace + name 生成全限定名（FQN），如果你有两个不同 namespace 下同名的 Record，不加 namespace 就会冲突。我曾经在一个微服务项目里，两个团队各自定义了 Order Record，结果序列化时互相覆盖，排查了一整天。
fields 数组：字段是有序的！Avro 序列化时按字段顺序写入，反序列化时也按顺序读取。这意味着你不能随意调整字段顺序，否则会破坏兼容性。
default 值：这是 Avro 实现 Schema 演进的杀手锏。给字段设置默认值，新加的字段就不会破坏旧数据的反序列化。我建议：所有非必填字段都加上 default。

小技巧：Record 可以嵌套。比如 User 里可以有一个 Address 类型的字段，Address 本身也是一个 Record。这种嵌套在复杂业务场景下非常常见。

3.2 Enum：有限选项的优雅表达

Enum 在 Avro 里是个被低估的类型。很多人习惯用 string 来表示状态、类型等枚举值，但 Enum 提供了更强的类型安全和 Schema 演进能力。

{
  "type": "enum",
  "name": "UserStatus",
  "namespace": "com.example.enums",
  "symbols": ["ACTIVE", "INACTIVE", "BANNED"]
}

Enum 的 symbols 是有序列表，Avro 序列化时存的是索引（整数），不是字符串。这意味着：

序列化效率高，一个 int 搞定
但 symbols 的顺序不能随意改，否则索引对不上

嗯，这里要注意：Enum 的演进只能追加新值到末尾，不能删除或重排已有值。我曾经在一个支付系统里，因为删除了一个废弃的订单状态，导致历史数据反序列化全部报错。那次教训让我记住了：Enum 的 symbols 是「只增不减」的。

3.3 Array：有序集合

Array 在 Avro 里很简单，就是一个「类型 + 数组」的组合。它对应 Java 的 List、Python 的 list。

{
  "type": "array",
  "items": "string"
}

或者嵌套复杂类型：

{
  "type": "array",
  "items": {
    "type": "record",
    "name": "OrderItem",
    "fields": [
      {"name": "productId", "type": "long"},
      {"name": "quantity", "type": "int"}
    ]
  }
}

Array 的 items 可以是任何 Avro 类型，包括 Record、Map、Union，甚至另一个 Array。但说实话，我很少见到超过两层嵌套的 Array，太深了可读性会急剧下降。

避坑指南：Avro 的 Array 是变长数组，序列化时会先写长度再写元素。如果你有大量空数组，序列化开销其实不小。我曾经优化过一个日志系统，把空数组改成了 null（配合 Union），序列化体积直接降了 30%。

3.4 Map：键值对容器

Map 对应 Java 的 HashMap、Python 的 dict。它的键必须是 string，值可以是任意类型。

{
  "type": "map",
  "values": "double"
}

Map 在什么场景下好用？我个人经验是：动态属性。比如用户的自定义字段、配置项、标签系统。这些字段的 key 是动态的，没法在 Schema 里预定义。

举个例子，一个商品可以有多个自定义属性：

{
  "type": "record",
  "name": "Product",
  "fields": [
    {"name": "id", "type": "long"},
    {"name": "name", "type": "string"},
    {"name": "attributes", "type": {"type": "map", "values": "string"}}
  ]
}

这样，attributes 里可以放 "color": "red"、"size": "XL" 等任意键值对，非常灵活。

3.5 Union：多类型联合

Union 是 Avro 里最强大也最容易用错的类型。它表示「这个字段可以是多种类型中的一种」。说白了，就是「或」的关系。

["null", "string"]

这个 Union 表示：字段可以是 null，也可以是 string。这是 Avro 里实现「可选字段」的标准方式。

Union 的语法是 JSON 数组，数组里的每个元素都是一个 Avro 类型。注意：

Union 的元素不能重复（比如不能有两个 string）
Union 的元素顺序很重要，Avro 序列化时会存一个索引，表示实际用的是哪个类型
null 通常放在第一位，这是约定俗成的习惯

来看一个更复杂的 Union：

{
  "name": "contact",
  "type": ["null", "string", {
    "type": "record",
    "name": "PhoneNumber",
    "fields": [
      {"name": "countryCode", "type": "string"},
      {"name": "number", "type": "string"}
    ]
  }]
}

这个 contact 字段可以是 null、纯字符串（邮箱）、或者一个 PhoneNumber Record。我在一个 CRM 系统里就用过这种设计，客户的联系方式多种多样，Union 完美解决了这个问题。

重要提醒：Union 里的 Record 类型必须要有 name，因为 Avro 需要为每个分支生成全限定名。匿名 Record 在 Union 里是不允许的。

3.6 类型组合实战：一个完整的 Schema

光讲理论不够，咱们来一个实战例子。假设我们要设计一个电商订单的 Schema：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example.order",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "userId", "type": "long"},
    {"name": "status", "type": {
      "type": "enum",
      "name": "OrderStatus",
      "symbols": ["PENDING", "PAID", "SHIPPED", "DELIVERED", "CANCELLED"]
    }},
    {"name": "items", "type": {
      "type": "array",
      "items": {
        "type": "record",
        "name": "OrderItem",
        "fields": [
          {"name": "productId", "type": "long"},
          {"name": "quantity", "type": "int"},
          {"name": "price", "type": "double"}
        ]
      }
    }},
    {"name": "shippingAddress", "type": ["null", {
      "type": "record",
      "name": "Address",
      "fields": [
        {"name": "street", "type": "string"},
        {"name": "city", "type": "string"},
        {"name": "zipCode", "type": "string"}
      ]
    }], "default": null},
    {"name": "tags", "type": {"type": "map", "values": "string"}, "default": {}}
  ]
}

这个 Schema 用到了我们今天讲的所有复杂类型：

Record：Order、OrderItem、Address
Enum：OrderStatus
Array：items
Map：tags
Union：shippingAddress（null 或 Address）

你想想看，如果用 JSON Schema 或者 Protobuf 来定义同样的结构，代码量会多不少。Avro 的简洁性在这里体现得很明显。

3.7 知识体系总览

下面这张图总结了 Avro 复杂类型的核心关系，我建议你保存下来，写 Schema 时对照着看：

3.8 避坑总结

最后，我把这些年用 Avro 复杂类型踩过的坑整理成一张表，你写 Schema 时对照着检查：

类型	常见坑	建议
Record	字段顺序随意调整	新字段只能追加到末尾
Enum	删除或重排 symbols	只追加，不删除，不重排
Array	大量空数组浪费空间	考虑用 Union(null, array) 替代
Map	values 类型定义过宽	尽量用具体类型，少用 string
Union	元素顺序随意	null 放第一位，其他按使用频率排序