Spring Boot STOMP WebSocket与Android Kotlin客户端通信异常排查

服务端配置核对 #

先确认Spring Boot服务端核心配置是否正确，这是问题根源：

• 确保@EnableWebSocketMessageBroker已添加，消息代理和应用前缀匹配客户端发送/订阅路径：

  @Configuration
  @EnableWebSocketMessageBroker
  public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
      @Override
      public void configureMessageBroker(MessageBrokerRegistry config) {
          config.enableSimpleBroker("/topic", "/queue"); // 客户端订阅主题必须在此范围内
          config.setApplicationDestinationPrefixes("/app"); // 客户端发消息需带/app前缀
      }
  
      @Override
      public void registerStompEndpoints(StompEndpointRegistry registry) {
          registry.addEndpoint("/ws").setAllowedOrigins("*").withSockJS(); // 跨域和端点路径要与客户端一致
      }
  }
  

• 检查控制器的@MessageMapping和@SendTo路径对应关系：

  @Controller
  public class StompController {
      @MessageMapping("/send-message") // 客户端发消息完整路径为/app/send-message
      @SendTo("/topic/messages") // 客户端需订阅/topic/messages接收反馈
      public MessageResponse handleMessage(MessageRequest request) {
          return new MessageResponse("Received: " + request.getContent());
      }
  }
  

• 开启服务端DEBUG日志，查看是否收到客户端SEND帧、是否成功广播MESSAGE帧。

OkHttp客户端修复要点 #

若使用基于OkHttp的STOMP库（如stomp-android），重点检查：

• 订阅路径必须与服务端@SendTo路径完全一致，不能少斜杠或拼写错误。
• 发送消息的目的地要带/app前缀，比如/app/send-message，而非直接/send-message。
• 配置心跳避免连接假死，间隔需与服务端匹配（默认10秒）：

  val okHttpClient = OkHttpClient.Builder().build()
  val stompClient = Stomp.over(
      OkHttpWebSocketTransport.create(okHttpClient),
      "ws://your-server:port/ws"
  )
  stompClient.setHeartbeat(10000, 10000)
  stompClient.connect()
  

• 订阅回调添加日志和异常捕获，避免异常吞掉后续回调，更新Compose状态需切主线程：

  stompClient.subscribe("/topic/messages") { stompMessage ->
      try {
          Log.d("STOMP", "Received payload: ${stompMessage.payload}")
          withContext(Dispatchers.Main) {
              // 更新Compose状态
          }
      } catch (e: Exception) {
          Log.e("STOMP_ERROR", "Failed to handle message", e)
      }
  }
  

• 确保订阅操作在发送消息前执行，避免错过服务端即时反馈。

Ktor客户端修复要点 #

使用Ktor的STOMP插件时，注意这些细节：

• 配置正确的STOMP版本（服务端默认1.2）和心跳，开启日志查看帧交互：

  val client = HttpClient(OkHttp) {
      install(Stomp) {
          version = StompProtocolVersion.V1_2
          heartbeatInterval = 10.seconds
      }
      install(Logging) {
          logger = Logger.DEFAULT
          level = LogLevel.ALL
      }
  }
  

• 订阅需在连接成功后执行，路径完全匹配服务端广播路径：

  val session = client.webSocketSession(Url("ws://your-server:port/ws"))
  val stompSession = session.stomp()
  // 先订阅再发送，避免错过消息
  stompSession.subscribe("/topic/messages") { frame ->
      Log.d("KTOR_STOMP", "Received: ${frame.body}")
  }
  stompSession.send(StompSendFrame(destination = "/app/send-message", body = "Test message"))
  

• 确认服务端跨域配置setAllowedOrigins("*")生效，允许Ktor客户端请求。

通用排查技巧 #

• 用Postman的WebSocket功能测试服务端：连接ws://your-server:port/ws，发送STOMP帧SEND到/app/send-message，订阅/topic/messages，验证服务端是否正常反馈，排除服务端问题。
• 抓包查看WebSocket帧：确认客户端SEND帧是否到达服务端，服务端是否返回MESSAGE帧给客户端。
• 检查客户端回调中的未处理异常，异常会导致后续回调失效。

内容的提问来源于stack exchange，提问作者Rafael Souza