消息队列 / 系统课时
消息序列化
消息序列化
对象消息真正要解决的不是“把 Java 类塞进队列”,而是把业务事件转换成稳定、可跨进程读取的 JSON 契约。本课用 Spring AMQP 4.x 的 JSON 转换器完成对象收发,并把事件版本、类型和业务数据分开设计,避免一次字段调整拖垮所有消费者。
学习目标
- 配置
JacksonJsonMessageConverter,让RabbitTemplate与@RabbitListener使用同一套 JSON 转换规则 - 设计包含事件标识、事件类型、版本和业务载荷的事件结构
- 判断哪些字段变化可以兼容演进,哪些变化应升级事件版本
把对象转换为 JSON 消息
Spring AMQP 4.x 使用基于 Jackson 3 的 JacksonJsonMessageConverter。发送端调用 convertAndSend 时,转换器把对象写成 JSON;消费端拿到消息后,再根据监听方法的目标类型还原对象。这样消息体不依赖 Java 原生序列化格式,也更容易被其他语言消费。
下面配置一个最小拓扑,并让发送模板和监听容器显式使用同一个转换器:
package com.example.rabbitmq;
import org.springframework.amqp.core.Binding;
import org.springframework.amqp.core.BindingBuilder;
import org.springframework.amqp.core.DirectExchange;
import org.springframework.amqp.core.Queue;
import org.springframework.amqp.rabbit.config.SimpleRabbitListenerContainerFactory;
import org.springframework.amqp.rabbit.connection.ConnectionFactory;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.amqp.support.converter.JacksonJsonMessageConverter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class RabbitJsonConfig {
@Bean
JacksonJsonMessageConverter jsonMessageConverter() {
return new JacksonJsonMessageConverter();
}
@Bean
RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory,
JacksonJsonMessageConverter converter) {
RabbitTemplate template = new RabbitTemplate(connectionFactory);
template.setMessageConverter(converter);
return template;
}
@Bean
SimpleRabbitListenerContainerFactory rabbitListenerContainerFactory(
ConnectionFactory connectionFactory,
JacksonJsonMessageConverter converter) {
SimpleRabbitListenerContainerFactory factory = new SimpleRabbitListenerContainerFactory();
factory.setConnectionFactory(connectionFactory);
factory.setMessageConverter(converter);
return factory;
}
@Bean
DirectExchange orderEventsExchange() {
return new DirectExchange("order.events");
}
@Bean
Queue orderCreatedQueue() {
return new Queue("order.created.q");
}
@Bean
Binding orderCreatedBinding(Queue orderCreatedQueue,
DirectExchange orderEventsExchange) {
return BindingBuilder.bind(orderCreatedQueue)
.to(orderEventsExchange)
.with("order.created");
}
}配置生效后,RabbitTemplate 发布对象时会生成 JSON 消息,监听容器也会用 JSON 转换器反序列化。可以在 RabbitMQ 管理界面查看消息属性;消息体应为 JSON,内容类型应与 JSON 转换相匹配。
把事件当作契约设计
不要直接把数据库实体或内部 DTO 当作长期消息协议。更稳妥的做法是定义事件信封,把跨服务需要稳定识别的元数据放在外层,把业务字段放进 data。例如:
package com.example.rabbitmq;
import java.math.BigDecimal;
public record OrderCreatedEvent(
String eventId,
String eventType,
int schemaVersion,
String occurredAt,
OrderCreatedData data) {
public record OrderCreatedData(
long orderId,
BigDecimal amount,
String currency) {
}
}对应的线上消息可以保持为清晰的 JSON 契约:
{
"eventId": "<ID>",
"eventType": "order.created",
"schemaVersion": 1,
"occurredAt": "2026-09-03T06:00:00Z",
"data": {
"orderId": 1001,
"amount": 299.00,
"currency": "CNY"
}
}eventId 用于追踪和幂等,eventType 表示业务语义,schemaVersion 表示契约版本。实际事件 ID 会不同,因此示例使用 <ID> 占位。业务消费者应依赖这些业务字段,而不是依赖某个 Java 类的全限定名来判断事件含义。

验证发送与接收
下面是依赖前述配置与拓扑的片段示例。发布者创建一个事件对象,消费者直接接收 OrderCreatedEvent,从而验证对象到 JSON 再回到对象的完整链路。
package com.example.rabbitmq;
import java.math.BigDecimal;
import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.stereotype.Service;
@Service
public class OrderEventService {
private final RabbitTemplate rabbitTemplate;
public OrderEventService(RabbitTemplate rabbitTemplate) {
this.rabbitTemplate = rabbitTemplate;
}
public void publish() {
var data = new OrderCreatedEvent.OrderCreatedData(
1001L, new BigDecimal("299.00"), "CNY");
var event = new OrderCreatedEvent(
"evt-1001", "order.created", 1,
"2026-09-03T06:00:00Z", data);
rabbitTemplate.convertAndSend(
"order.events", "order.created", event);
}
@RabbitListener(queues = "order.created.q")
public void consume(OrderCreatedEvent event) {
System.out.printf(
"received type=%s version=%d orderId=%d%n",
event.eventType(),
event.schemaVersion(),
event.data().orderId());
}
}调用 publish() 后,预期输出为:
received type=order.created version=1 orderId=1001让事件可以长期演进
兼容演进的关键不是不断增加版本号,而是尽量保持旧消费者还能读新消息。新增可选字段通常风险最低;删除字段、修改字段含义、把字符串改成对象这类变化则可能直接破坏旧消费者。
当变化无法兼容时,可以提升 schemaVersion,并让消费者在迁移期同时支持旧版和新版。这样序列化层只负责可靠地传输 JSON,真正的兼容策略由清晰、稳定、可演进的事件契约承担。