架构注册表概览

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

本文档概述了 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"}
  ]
}

以下是采用 Protocol Buffer 格式的同一示例。

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 架构存储在架构注册表中，并随消息一起传递架构的标识符。只要消息的消费者知道使用了哪个注册表，就可以检索相同的架构并解码消息。

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

架构注册表的向后兼容性是指，配置了新架构版本的消费者应用可以读取使用之前架构生成的数据。

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

下面是示例架构注册表 schema_registry_test 的自上而下视图，其中按上下文、主题和架构版本进行了整理：

customer_support 上下文
- order 主题
- V1 版本（包括 orderId、customerName、productName、quantity、price）
- V2 版本（向 V1 添加了 orderDate）

什么是架构

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

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

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

Apache Avro
协议缓冲区 (Protobuf)

架构注册表 API 不支持 JSON。

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

架构注册表组织

架构注册表使用分层结构来整理架构。

图：架构的层次结构。

架构：消息的结构和数据类型。每个架构都由一个架构 ID 标识。应用使用此 ID 来检索架构。
主题：架构不同版本的逻辑容器。主题使用兼容性规则管理架构随时间的演变情况。每个主题通常对应于一个 Kafka 主题或记录对象。
版本：当业务逻辑需要更改消息结构时，请在相关主题下创建并注册新的架构版本。

每个版本都引用一个特定的架构。如果底层架构恰好相同，不同主题的版本可以引用同一架构。
Context：主题的高级分组或命名空间。借助上下文，不同的团队或应用可以在同一架构注册表中无冲突地使用相同的主题名称。

一个架构注册表可以有多个上下文。它始终包含一个标识为 . 的默认上下文，如果没有指定其他上下文标识符，架构和主题将位于该上下文中。

一个上下文可以包含多个主题。
注册表：整个架构生态系统的顶层容器。它存储并管理所有架构、主题、版本和上下文。

架构注册表工作流

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

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

使用指定为 Avro 生成的类的特定架构初始化生产者应用，并将其配置为使用特定的架构注册表和序列化程序库。
配置使用方客户端以使用相应的反序列化程序库和相同的架构注册表。
在运行时，客户端将消息对象传递给 producer.send 方法，Kafka 客户端库使用配置的序列化程序将此记录转换为 Avro 编码的字节。
序列化程序会根据客户端库中配置的主题名称策略来确定架构的主题名称。然后，它会在向架构注册表发出的请求中使用此主题名称来检索架构的 ID。如需了解详情，请参阅主题命名策略。
如果注册表中不存在具有该主题名称的架构，则可将客户端配置为注册该架构，在这种情况下，客户端会收到新分配的 ID。

请避免在生产环境中使用此配置。
生产者将包含架构 ID 的序列化消息发送到 Kafka 代理的相应主题。
Kafka 代理将消息的字节数组表示形式存储在主题中。
消费者应用接收消息。
反序列化程序会从架构注册表中检索具有此 ID 的架构。
反序列化程序会解析面向消费类应用的消息。

限制

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

架构格式：
- 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 参数。

后续步骤

Apache Kafka® 是 Apache Software Foundation 或其关联公司在美国和/或其他国家/地区的注册商标。