消息队列 / 系统课时

消息属性与载荷

消息属性与载荷

一条可维护的 RabbitMQ 消息不仅要有业务数据,还要带上内容类型、字符编码、消息标识、时间戳和业务头。本课将建立统一的消息契约,并通过 Java 示例完成发布、读取和验证,避免消费者依赖猜测解析消息。

学习目标

  • 区分消息属性、业务头和消息载荷的职责。
  • 为 JSON 消息设置内容类型、编码、标识与时间戳。
  • 设计可演进、可追踪的统一载荷格式。

消息由三部分组成

RabbitMQ 传递的核心对象可以理解为“属性、头、载荷”三层。属性描述消息如何被识别和解析,业务头保存少量路由或处理提示,载荷承载真正的业务事实。

部分 典型内容 主要用途
基础属性 contentType、contentEncoding、messageId、timestamp 告诉消费者如何解析、追踪和审计消息
业务头 x-business、x-schema-version、x-tenant-id 传递少量跨业务处理信息
载荷 JSON、文本或二进制数据 保存订单、支付、库存等业务内容

属性和头不应复制完整业务对象。订单金额、商品明细等应放入载荷,否则会造成协议重复、字段不一致,并增加消息中间件层面的耦合。

属性设置规则

JSON 消息建议将 contentType 固定为 application/json,将 contentEncoding 固定为 UTF-8。消费者应先检查这两个属性,再决定使用哪种反序列化方式,不能默认所有字节都是 JSON。

messageId 应在生产端生成并保持全链路不变,可用于日志关联、消费幂等和问题追踪。timestamp 表示消息创建时间,不等同于业务事件发生时间;业务事件时间仍应显式放入载荷。

业务头只保存短小、稳定且需要被基础设施读取的信息。例如租户标识、契约版本或来源系统。敏感信息、大对象和高频变化字段不适合放入头部。

规范 JSON 载荷

推荐使用事件信封包裹业务数据,使不同事件拥有一致的外层结构。最小结构可包含 eventId、eventType、occurredAt、schemaVersion 和 data。

其中,eventId 与消息属性中的 messageId 保持一致;eventType 使用稳定的过去式业务名称;schemaVersion 用于兼容字段演进;data 只保存当前事件需要的业务快照。

金额建议使用最小货币单位的整数,例如 12800 表示 128.00 元,避免浮点数精度问题。

完整发布与读取示例

下面示例使用 RabbitMQ Java Client 连接本机服务,创建临时队列,发布一条带完整属性的 JSON 消息,再立即读取并打印。运行前需保证 RabbitMQ 已启动,且项目已经引入 com.rabbitmq:amqp-client。

java
import com.rabbitmq.client.AMQP;
import com.rabbitmq.client.Channel;
import com.rabbitmq.client.Connection;
import com.rabbitmq.client.ConnectionFactory;
import com.rabbitmq.client.GetResponse;

import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Date;
import java.util.Map;
import java.util.UUID;

public class MessagePropertiesDemo {

    public static void main(String[] args) throws Exception {
        ConnectionFactory factory = new ConnectionFactory();
        factory.setHost("localhost");

        try (Connection connection = factory.newConnection();
             Channel channel = connection.createChannel()) {

            // 使用服务端生成的临时队列,避免读取到历史消息
            String queue = channel.queueDeclare("", false, true, true, null).getQueue();

            String eventId = UUID.randomUUID().toString();
            Instant occurredAt = Instant.now();
            String bodyJson = """
                    {"eventId":"%s","eventType":"order.created","occurredAt":"%s","schemaVersion":"1.0","data":{"orderId":"O202608030001","amount":12800,"currency":"CNY"}}
                    """.formatted(eventId, occurredAt).trim();

            Map<String, Object> headers = Map.of(
                    "x-business", "order",
                    "x-schema-version", "1.0"
            );

            AMQP.BasicProperties properties = new AMQP.BasicProperties.Builder()
                    .contentType("application/json")
                    .contentEncoding(StandardCharsets.UTF_8.name())
                    .messageId(eventId)
                    .timestamp(Date.from(occurredAt))
                    .type("order.created")
                    .appId("order-service")
                    .headers(headers)
                    .build();

            channel.basicPublish(
                    "",
                    queue,
                    properties,
                    bodyJson.getBytes(StandardCharsets.UTF_8)
            );

            GetResponse response = channel.basicGet(queue, true);
            AMQP.BasicProperties received = response.getProps();

            System.out.println("contentType=" + received.getContentType());
            System.out.println("contentEncoding=" + received.getContentEncoding());
            System.out.println("messageId=" + received.getMessageId());
            System.out.println("timestamp=" + received.getTimestamp().toInstant());
            System.out.println("schemaVersion=" + received.getHeaders().get("x-schema-version"));
            System.out.println("body=" + new String(response.getBody(), StandardCharsets.UTF_8));
        }
    }
}

预期输出如下,<ID> 和 <TIME> 是动态值,实际运行结果会不同。

text
contentType=application/json
contentEncoding=UTF-8
messageId=<ID>
timestamp=<TIME>
schemaVersion=1.0
body={"eventId":"<ID>","eventType":"order.created","occurredAt":"<TIME>","schemaVersion":"1.0","data":{"orderId":"O202608030001","amount":12800,"currency":"CNY"}}

验证时应重点确认消息属性与载荷一致:messageId 与 eventId 相同,字符编码明确,契约版本可读取,消费者能够按 UTF-8 正确还原 JSON。

常见错误

不要把 Java 对象直接使用默认序列化后发送,因为消费者会被语言、类名和版本绑定。也不要只设置 JSON 字符串而遗漏 contentType,否则其他语言的消费者无法可靠判断载荷格式。

时间字段应统一使用带时区的 ISO 8601 格式,例如 2026-08-03T08:00:00Z。新增字段时保持向后兼容;删除或改变字段语义时,应提升 schemaVersion,并让消费者在过渡期同时支持新旧版本。

本课总结

  • 消息属性负责解析与追踪,业务头负责少量处理提示,载荷负责业务数据。
  • JSON 消息应明确设置内容类型、UTF-8 编码、消息标识和时间戳。
  • 统一事件信封能提升跨语言消费、版本演进和问题定位能力。

下一课预告

下一课将进入交换机与绑定,理解路由键如何经过交换机规则,把同一生产者发送的消息投递到不同队列。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

消息属性与载荷

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通