3. 消息契约定义：什么是消息契约、契约的组成要素

在分布式系统中，消息契约是生产者和消费者之间关于消息格式、结构和语义的正式约定。它定义了双方如何理解、解析和处理消息，是系统间通信的“法律文件”。没有明确的契约，生产者和消费者各自独立演进，极易导致数据解析失败、字段缺失或业务逻辑错误。

3.1 什么是消息契约

消息契约（Message Contract）是对消息在传输过程中的结构、类型、语义和约束的完整描述。它确保：

• 生产者按照约定的格式发送消息
• 消费者按照相同的格式解析消息
• 双方对消息中每个字段的含义、类型、取值范围有共同理解
• 版本演进时，向后兼容性得到保障

3.2 契约的组成要素

一个完整的Kafka消息契约由以下四个核心要素构成：

3.3 要素详解

3.3.1 Topic名称

Topic名称是消息契约的第一标识。命名规范直接影响消息的可维护性和可发现性。推荐采用领域驱动命名：

# 推荐命名模式
{领域}.{实体}.{事件类型}.v{版本号}

# 示例
order.created.v1
payment.completed.v2
inventory.stock.changed.v1
user.profile.updated.v1

3.3.2 Key

Key在消息契约中承担两个关键职责：

• 分区路由：相同Key的消息进入同一分区，保证顺序消费
• 幂等去重：消费者可根据Key实现幂等处理

Key的类型通常为字符串或整数，但必须明确约定其格式：

// 契约中定义的Key格式
// 订单ID：ORD-{年份}-{序号}
// 用户ID：USR-{UUID前8位}

// 示例Key值
Key: "ORD-2024-001"   → 进入分区0
Key: "ORD-2024-002"   → 进入分区1
Key: "ORD-2024-003"   → 进入分区0

3.3.3 Value Schema

Value Schema是消息契约的核心，定义了消息体的完整结构。推荐使用Schema Registry管理：

一个典型的Avro Schema示例：

{
  "type": "record",
  "name": "OrderCreated",
  "namespace": "com.example.order",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "userId", "type": "string"},
    {"name": "amount", "type": "double"},
    {"name": "items", "type": {"type": "array", "items": "string"}},
    {"name": "timestamp", "type": "long", "logicalType": "timestamp-millis"}
  ]
}

3.3.4 Header

Header是消息的元数据容器，不参与业务逻辑但承载关键上下文：

• traceId：全链路追踪标识
• version：消息版本号，用于兼容性判断
• source：消息来源服务
• contentType：序列化格式（avro/json/protobuf）
• timestamp：消息产生时间

3.4 消息契约的完整结构

下图展示了消息契约在Kafka消息中的完整映射关系：

3.5 契约的版本管理

消息契约必须支持版本演进，常见的版本策略：

3.6 契约的验证流程

在开发验证阶段，消息契约的验证应覆盖以下维度：

1. 结构验证：消息体是否严格符合Schema定义
2. 类型验证：每个字段的类型是否正确（如double不能传string）
3. 边界验证：空值、最大值、最小值、特殊字符
4. 兼容性验证：新版本Schema是否兼容旧版本
5. Header验证：必填Header是否存在，值格式是否正确