架构注册表概览

架构注册表提供由多个应用共享的架构的存储库。以前，如果没有架构注册表，团队可能需要依赖非正式协议（例如口头约定、未以程序化方式强制执行的共享文档或 Wiki 页面）来定义消息格式以及如何序列化和反序列化消息。架构注册表可确保消息编码和解码的一致性。

本文档概述了 Managed Service for Apache Kafka 的架构注册表功能、其组件和基本工作流。

了解架构

假设您要构建一个跟踪客户订单的应用。您可以使用名为 customer_orders 的 Kafka 主题来传输包含每个订单相关信息的消息。典型的订单消息可能包含以下信息字段：

• 订单 ID

• 客户名称

• 商品名称

• 数量

• 价格

为确保这些消息的结构一致，您可以定义架构。 以下是 Apache Avro 格式的示例：

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "customerName", "type": "string"},
    {"name": "productName", "type": "string"},
    {"name": "quantity", "type": "int"},
    {"name": "price", "type": "double"}
  ]
}

以下是协议缓冲区格式的同一示例。

syntax = "proto3";

package com.example;

option java_multiple_files = true; // Optional: Recommended for Java users
option java_package = "com.example"; // Optional: Explicit Java package

message Order {
  string orderId = 1;
  string customerName = 2;
  string productName = 3;
  int32 quantity = 4; // Avro int maps to Protobuf int32
  double price = 5;
}

此架构是消息的蓝图。它告诉您，order 消息包含五个字段：订单 ID、客户名称、商品名称、数量和价格。它还指定了每个字段的数据类型。

如果使用方客户端收到使用此架构编码的二进制消息，则必须确切知道如何解读该消息。为此，生成方会将 order 架构存储在架构注册表中，并随消息传递架构的标识符。只要消息的使用方知道使用了哪个注册表，就可以检索相同的架构并解码消息。

假设您想向 orderDate 消息添加 order 字段。您可以创建新版本的 order 架构，并在同一主题下注册该架构。这样，您就可以跟踪架构随时间的演变情况。 添加字段是向前兼容的更改。这意味着，使用旧版架构（不含 orderDate）的使用方仍然可以读取和处理使用新架构生成的消息。系统会忽略新字段。

架构注册表的向后兼容性意味着，使用新架构版本配置的使用方应用可以读取使用先前架构生成的数据。

在此示例中，初始 order 架构将为版本 1。当您添加 orderDate 字段时，您将创建 order 架构的版本 2。这两个版本都存储在同一主题下，让您可以管理架构更新，而不会破坏可能仍依赖于版本 1 的现有应用。

以下是名为 schema_registry_test 的示例架构注册表的鸟瞰视图，该注册表按上下文、主题和架构版本进行组织：

• customer_support 上下文

  • order 主题

  • V1 版本（包含 orderId、customerName、productName、quantity、price）

  • V2 版本（将 orderDate 添加到 V1）

什么是架构

Apache Kafka 消息由字节字符串组成。如果没有定义的结构，使用方应用必须直接与生成方应用协调，才能了解如何解读这些字节。

架构提供了消息中数据的正式说明。它定义了字段及其数据类型（例如字符串、整数或布尔值）以及任何嵌套结构。

Managed Service for Apache Kafka 支持以下格式的架构：

• Apache Avro

• 协议缓冲区 (Protobuf)

架构注册表 API 不支持 JSON。

Managed Service for Apache Kafka 中集成的架构注册表功能可让您使用 Kafka 客户端创建、管理和使用这些架构。架构注册表实现了 Confluent Schema Registry REST API，该 API 与现有的 Apache Kafka 应用和常用客户端库兼容。

架构注册表组织

架构注册表使用层次结构来组织架构。

• 架构： 消息的结构和数据类型。每个架构都由一个架构 ID 标识。应用使用此 ID 来检索架构。

• 主题： 不同版本架构的逻辑容器。 主题使用兼容性规则管理架构随时间的演变情况。每个主题通常对应于一个 Kafka 主题或记录对象。

• 版本： 当业务逻辑需要更改消息结构时，请在相关主题下创建并注册新的架构版本。

  每个版本都引用一个特定的架构。如果底层架构恰好相同，则不同主题的版本可以引用同一架构。

• 上下文： 主题的高级分组或命名空间。上下文允许不同的团队或应用在同一架构注册表中无冲突地使用相同的主题名称。

  一个架构注册表可以有多个上下文。它始终包含一个标识为 . 的默认上下文，当未指定其他上下文标识符时，架构和主题会进入该上下文。

  一个上下文可以包含多个主题。

• 注册表： 整个架构生态系统的顶级容器。它存储和管理所有架构、主题、版本和上下文。

架构注册表工作流

如需遵循本部分所述的工作流，您可以尝试使用架构注册表生成 Avro 消息中的快速入门。

Kafka 客户端中的序列化程序和反序列化程序与架构注册表交互，以确保消息符合定义的架构。以下是 Managed Service for Apache Kafka 中架构注册表的典型工作流：

1. 使用指定为 Avro 生成的类的特定架构初始化生成方应用，并将其配置为使用特定的架构注册表和序列化程序库。

2. 将使用方客户端配置为使用相应的反序列化程序库和相同的架构注册表。

3. 在运行时，客户端将消息对象传递到 producer.send 方法，Kafka 客户端库使用配置的序列化程序将此记录转换为 Avro 编码的字节。

4. 序列化程序根据客户端库中配置的主题名称策略确定架构的主题名称。然后，它在向架构注册表发出的请求中使用此主题名称来检索架构的 ID。如需了解详情， 请参阅 主题命名策略。

5. 如果该架构在注册数据库中不存在于该主题名称下，则可以将客户端配置为注册该架构，在这种情况下，客户端会收到新分配的 ID。

   请避免在生产环境中使用此配置。

6. 生成方将序列化的消息连同架构 ID 一起发送到 Kafka 代理的相应主题。

7. Kafka 代理将消息的字节数组表示形式存储在主题中。

8. 使用方应用会收到消息。

9. 反序列化程序会从架构注册表中检索具有此 ID 的架构。

10. 反序列化程序会为使用方应用解析消息。

限制

架构注册表不支持以下功能：

• 架构格式：

  • JSON 架构格式。

• 架构模式：

  • READONLY_OVERRIDE 架构模式。

• 架构配置值：

  • Normalize 和 Alias 配置值。

• API 方法：

  • ModifySchemaTags 方法 (/subjects/{subject}/versions/{version}/tags)。
  • GetLatestWithMetadata 方法 (/subjects/{subject}/metadata)。
  • ListSchemas 方法 (/schemas)。
  • DeleteSchemaMode 方法。
  • 对于 GetVersion 方法：format、deleted 和 findTags 参数。
  • 对于 CreateVersion 方法：metadata、ruleSet、schemaTagsToAdd 和 schemaTagsToRemove 参数。
  • 对于 UpdateSchemaMode 方法：force 参数。
  • 对于 GetSchemaMode 方法：defaultToGlobal 参数。
  • 对于 GetSchema 方法：WorkspaceMaxId 和 findTags 参数。
  • 对于 ListVersions 方法：deletedOnly 参数。
  • 对于 ListSubjects 方法：deletedOnly 参数。

后续步骤

• 架构生命周期管理

• 创建架构注册表

• 创建主题