消息队列 / 系统课时
消息属性与载荷
消息属性与载荷
一条可维护的 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。
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> 是动态值,实际运行结果会不同。
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 编码、消息标识和时间戳。
- 统一事件信封能提升跨语言消费、版本演进和问题定位能力。
下一课预告
下一课将进入交换机与绑定,理解路由键如何经过交换机规则,把同一生产者发送的消息投递到不同队列。