Apache Pulsar Schema 详解-优快云博客

Apache Pulsar Schema 是 Pulsar 实现 数据类型安全、前后兼容性、生产者与消费者解耦 的核心机制。通过 Schema，Pulsar 能够确保生产者发送的消息格式与消费者期望的格式一致，避免“数据乱码”或“反序列化失败”等问题。

📘 Apache Pulsar Schema 详解

一、什么是 Schema？

Schema 是消息数据的“契约”（Contract），定义了消息 payload 的结构和类型。
它使得 Pulsar 从“字节管道”升级为“结构化数据流平台”。
支持多种数据格式：String、JSON、Avro、Protobuf、Thrift、Primitive Types（int、long 等）。

✅ 优势：

类型安全：编译时或运行时检查类型。
自动序列化/反序列化：生产者发 POJO，消费者收 POJO。
兼容性控制：防止破坏性变更。
多语言支持：Java、Python、Go 等共享同一 Schema。

二、Schema 的核心作用

作用	说明
✅ 类型安全	消费者不会收到格式错误的消息
✅ 自动编解码	无需手动 `JSON.parse()` 或 `avro.decode()`
✅ 跨语言兼容	Java 生产，Python 消费，格式一致
✅ Schema 版本管理	支持演进与兼容性策略
✅ Schema Registry	内置注册中心，无需外部系统（如 Confluent Schema Registry）

三、支持的 Schema 类型

Pulsar 内置多种 Schema 类型：

类型	说明	适用场景
`Schema.STRING`	UTF-8 字符串	日志、简单文本
`Schema.BYTES`	原始字节数组	自定义序列化、二进制数据
`Schema.INT8/INT16/INT32/INT64`	整数类型	计数、ID、状态码
`Schema.FLOAT/DOUBLE`	浮点数	价格、指标
`Schema.BOOL`	布尔值	开关、状态
`Schema.DATE/TIME/DATETIME`	时间类型	事件时间
`Schema.JSON<T>`	JSON 结构（Pojo）	通用对象，灵活
`Schema.AVRO<T>`	Avro 格式	高性能、强类型、兼容性好
`Schema.PROTOBUF<T>`	Protocol Buffers	Google 生态、高效
`Schema.KEY_VALUE<K,V>`	Key-Value 对	复合结构
`Schema.NONE`	无 Schema（原始字节）	默认，无类型检查

四、Schema 使用示例（Java）

1. 定义数据类（POJO）

public class User {
    public String name;
    public int age;
    public String email;

    // 必须有默认构造函数
    public User() {}
}

2. 生产者使用 Schema

PulsarClient client = PulsarClient.builder()
    .serviceUrl("pulsar://localhost:6650")
    .build();

// 使用 JSON Schema
Producer<User> producer = client.newProducer(Schema.JSON(User.class))
    .topic("persistent://mycompany/app/users")
    .create();

// 发送对象，自动序列化为 JSON
User user = new User();
user.name = "Alice";
user.age = 30;
user.email = "alice@example.com";

producer.send(user);  // 自动转为 {"name":"Alice","age":30,"email":"alice@example.com"}

3. 消费者使用 Schema

Consumer<User> consumer = client.newConsumer(Schema.JSON(User.class))
    .topic("users")
    .subscriptionName("user-processor")
    .subscribe();

Message<User> msg = consumer.receive();
User user = msg.getValue();  // 自动反序列化
System.out.println("Name: " + user.name);
consumer.acknowledge(msg);

✅ 无需手动 new ObjectMapper().readValue()

五、Schema 兼容性与演进

Pulsar 支持 Schema 演进，并可通过策略控制兼容性。

1. Schema 兼容性策略

策略	说明
`ALWAYS_COMPATIBLE`	任何变更都允许（不推荐）
`BACKWARD`	新 Schema 可读旧数据（推荐）
`FORWARD`	旧 Schema 可读新数据
`FULL`	新旧 Schema 双向兼容

# 设置命名空间的兼容性策略
pulsar-admin namespaces set-schema-compatibility-strategy my-tenant/my-namespace --strategy BACKWARD

2. 兼容性示例（JSON/Avro）

// V1
class UserV1 { String name; }

// V2（新增字段，兼容 V1）
class UserV2 { 
    String name; 
    int age;  // 新增，有默认值或可为 null
}

BACKWARD 允许：V2 消费者可读 V1 消息（age 为 null 或默认值）。
FORWARD 允许：V1 消费者可读 V2 消息（忽略 age 字段）。

⚠️ 不兼容变更：删除字段、改变类型（String → int）、重命名字段（无别名）。

六、Schema 存储与注册中心

Pulsar 内置 Schema Registry，无需外部系统。

1. Schema 存储位置

Schema 元数据存储在 BookKeeper 中，与消息分离。
每个 Topic 可关联一个 Schema。
Schema 有版本号（schema-version），自动管理。

2. Schema 生命周期

# 查看 Topic 的 Schema
pulsar-admin schemas get my-topic

# 删除 Schema（恢复为 BYTES）
pulsar-admin schemas delete my-topic

# 强制上传 Schema（用于非自动注册场景）
pulsar-admin schemas upload my-topic --filename user-schema.json

3. Schema 自动上传

默认开启：生产者首次发送时，Schema 自动注册。
可关闭：autoUpdateSchema(false)，强制预注册。

producer = client.newProducer(Schema.JSON(User.class))
    .topic("my-topic")
    .autoUpdateSchema(false)  // 禁用自动上传
    .create();

七、Protobuf 与 Avro 示例

1. Avro Schema（推荐用于高性能场景）

Schema<User> schema = Schema.AVRO(User.class);
Producer<User> producer = client.newProducer(schema)
    .topic("avro-users")
    .create();

Avro 优势：紧凑、高效、支持 schema evolution。

2. Protobuf Schema

需引入 pulsar-schema-protobuf 依赖：

<dependency>
    <groupId>org.apache.pulsar</groupId>
    <artifactId>pulsar-schema-protobuf</artifactId>
    <version>3.3.0</version>
</dependency>

Schema<MyProtobuf.User> schema = Schema.PROTOBUF(MyProtobuf.User.class);
Producer<MyProtobuf.User> producer = client.newProducer(schema)
    .topic("protobuf-users")
    .create();

八、Schema 高级特性

1. Key-Value Schema

Schema<KeyValue<String, User>> kvSchema = Schema.KeyValue(
    Schema.STRING,
    Schema.JSON(User.class)
);

Producer<KeyValue<String, User>> producer = client.newProducer(kvSchema)
    .topic("user-events")
    .create();

producer.send(new KeyValue<>("user-123", user));

适用于 Kafka 风格的 Key-Value 消息。

2. Schema 验证

Broker 会验证消息是否符合 Schema。
不符合则拒绝（SchemaCompatibilityCheck）。

3. Schema 与分区路由

// 按 Key 路由（Key 也使用 Schema）
producer.newMessage()
    .key("user-123")           // Key 可为 String
    .value(user)
    .send();

九、最佳实践建议

实践	建议
✅ 强制使用 Schema	避免 `Schema.BYTES` 或 `Schema.NONE`
✅ 选择合适类型	高性能用 `Avro`，灵活用 `JSON`
✅ 设置兼容性策略	推荐 `BACKWARD`
✅ 预注册 Schema	生产环境禁用 `autoUpdateSchema`
✅ 版本化 Schema	结合 CI/CD 管理 Schema 变更
✅ 监控 Schema 冲突	关注 `SchemaCompatibilityException`
✅ 使用 Protobuf for gRPC	微服务间通信

十、Schema 错误处理

错误	原因	解决方案
`IncompatibleSchemaException`	Schema 不兼容	检查兼容性策略
`SchemaNotFoundException`	Topic 无 Schema	上传或启用自动注册
`InvalidSchemaException`	Schema 格式错误	检查 POJO 定义
`ClassCastException`	消费者 Schema 与生产者不匹配	统一 Schema 类型

✅ 总结

特性	说明
✅ 内置 Schema Registry	无需外部系统
✅ 多格式支持	JSON、Avro、Protobuf、Primitive 等
✅ 自动编解码	生产者发对象，消费者收对象
✅ 兼容性控制	支持 Schema 演进
✅ 跨语言一致	Java、Python、Go 等共享 Schema
✅ 安全可靠	防止数据格式错误