消息队列 / 系统课时

消息序列化

消息序列化

对象消息真正要解决的不是“把 Java 类塞进队列”,而是把业务事件转换成稳定、可跨进程读取的 JSON 契约。本课用 Spring AMQP 4.x 的 JSON 转换器完成对象收发,并把事件版本、类型和业务数据分开设计,避免一次字段调整拖垮所有消费者。

学习目标

  • 配置 JacksonJsonMessageConverter,让 RabbitTemplate 与 @RabbitListener 使用同一套 JSON 转换规则
  • 设计包含事件标识、事件类型、版本和业务载荷的事件结构
  • 判断哪些字段变化可以兼容演进,哪些变化应升级事件版本

把对象转换为 JSON 消息

Spring AMQP 4.x 使用基于 Jackson 3 的 JacksonJsonMessageConverter。发送端调用 convertAndSend 时,转换器把对象写成 JSON;消费端拿到消息后,再根据监听方法的目标类型还原对象。这样消息体不依赖 Java 原生序列化格式,也更容易被其他语言消费。

下面配置一个最小拓扑,并让发送模板和监听容器显式使用同一个转换器:

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。例如:

java
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 契约:

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 类的全限定名来判断事件含义。

事件 JSON 契约从 v1 演进到 v2 的兼容关系

验证发送与接收

下面是依赖前述配置与拓扑的片段示例。发布者创建一个事件对象,消费者直接接收 OrderCreatedEvent,从而验证对象到 JSON 再回到对象的完整链路。

java
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() 后,预期输出为:

text
received type=order.created version=1 orderId=1001

让事件可以长期演进

兼容演进的关键不是不断增加版本号,而是尽量保持旧消费者还能读新消息。新增可选字段通常风险最低;删除字段、修改字段含义、把字符串改成对象这类变化则可能直接破坏旧消费者。

当变化无法兼容时,可以提升 schemaVersion,并让消费者在迁移期同时支持旧版和新版。这样序列化层只负责可靠地传输 JSON,真正的兼容策略由清晰、稳定、可演进的事件契约承担。

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

目录与阅读设置

阅读设置

17

记录一个想法

消息序列化

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

登录哪都通