Spring Boot集成GCP PubSub时ordering key不生效问题排查

• 用对官方指定的消息头键
  别自己随便定义头名称，必须用Spring Cloud GCP提供的GcpPubSubHeaders.ORDERING_KEY常量作为消息头的键。要是用普通字符串比如"orderingKey"，框架不会自动把它映射到PubSub的orderingKey字段里。示例代码：

  @MessagingGateway(defaultRequestChannel = "pubsubOutputChannel")
  public interface PubSubGateway {
      void sendMessage(@Payload String message, @Header(GcpPubSubHeaders.ORDERING_KEY) String orderingKey);
  }
  

• 开启消息排序支持开关
  不管是用配置类还是配置文件，必须明确开启消息排序功能，不然就算设了orderingKey也不会生效。
  配置类写法：

  @Bean
  public PubSubTemplate pubSubTemplate(PubSubPublisherTemplate publisherTemplate, PubSubSubscriberTemplate subscriberTemplate) {
      PubSubTemplate template = new PubSubTemplate(publisherTemplate, subscriberTemplate);
      publisherTemplate.setEnableMessageOrdering(true); // 这行是关键配置
      return template;
  }
  

  配置文件（application.properties）写法：

  spring.cloud.gcp.pubsub.publisher.enable-message-ordering=true
  

• 确认订阅的排序配置匹配
  虽然你说Python测试正常，但要核对Spring Boot连接的订阅确实开启了消息排序——订阅的enable_message_ordering必须设为true，不然就算主题支持，订阅没开也无法按序接收（不过这个不影响orderingKey在控制台的显示，只是确保功能完整）。

• 自定义转换器别过滤关键头
  要是你自己实现了消息转换器，得确保没把GcpPubSubHeaders.ORDERING_KEY这个头过滤掉。默认转换器会处理这些特殊头，但自定义时要手动配置：

  @Bean
  public PubSubMessageConverter pubSubMessageConverter() {
      DefaultPubSubMessageConverter converter = new DefaultPubSubMessageConverter();
      converter.setHeaderPatterns("*"); // 确保不排除ORDERING_KEY头
      return converter;
  }
  

内容的提问来源于stack exchange，提问作者Tiny Rick