Spring STOMP中messagingTemplate.convertAndSendToUser私聊消息无法接收问题

针对你遇到的"发送日志正常但无法接收私聊消息"问题，以下是逐步排查和解决的具体方案：

1. 核心问题定位方向 #

这类问题通常出在用户身份绑定、目的地路由配置或客户端订阅与服务端发送路径不匹配这几个环节，逐一排查即可定位。

2. 具体排查与修复步骤 #

（1）确保用户Principal正确绑定 #

Spring STOMP的/user前缀路由完全依赖于WebSocket连接的Principal对象，必须保证其getName()方法返回的是用户唯一标识（如用户名）。

检查你的CustomHandshakeHandler实现，确保正确设置用户身份：

public class CustomHandshakeHandler extends DefaultHandshakeHandler {
    @Override
    protected Principal determineUser(ServerHttpRequest request, WebSocketHandler wsHandler, Map<String, Object> attributes) {
        // 从登录Session中获取用户名（需与LoginController的登录逻辑对应）
        HttpServletRequest servletRequest = ((ServletServerHttpRequest) request).getServletRequest();
        String username = (String) servletRequest.getSession().getAttribute("loggedInUsername");
        
        if (username == null) {
            throw new AccessDeniedException("未登录用户无法建立WebSocket连接");
        }
        // 返回自定义Principal，确保getName()返回用户名
        return () -> username;
    }
}

（2）修正WebSocketConfig配置 #

必须启用/user作为消息代理的目的地前缀，否则用户专属路由会失效：

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        // 启用简单消息代理，必须包含/user前缀
        registry.enableSimpleBroker("/topic", "/user");
        // 设置客户端发送消息的前缀（对应@MessageMapping的路径）
        registry.setApplicationDestinationPrefixes("/app");
        // 显式指定用户目的地前缀（默认就是/user，可省略，但建议明确）
        registry.setUserDestinationPrefix("/user");
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/ws")
                .setHandshakeHandler(new CustomHandshakeHandler())
                .setAllowedOriginPatterns("*") // 根据实际跨域需求调整
                .withSockJS();
    }
}

（3）匹配客户端订阅与服务端发送路径 #

这是最容易出错的环节，必须保证两者的路径对应：

• 客户端订阅路径：无需指定具体用户名，直接订阅/user/queue/private，Spring会自动根据当前连接的Principal替换为/user/{当前用户名}/queue/private
• 服务端发送路径：使用convertAndSendToUser方法，第二个参数是相对于/user/{目标用户名}的后缀路径

客户端订阅代码（JavaScript）：

const socket = new SockJS('/ws');
const stompClient = Stomp.over(socket);

stompClient.connect({}, function(frame) {
    console.log("WebSocket连接成功");
    // 订阅私聊消息队列
    stompClient.subscribe('/user/queue/private', function(message) {
        const chatMsg = JSON.parse(message.body);
        console.log("收到私聊消息：", chatMsg);
        // 后续渲染到页面逻辑
    });
});

服务端ChatController代码：

@Controller
public class ChatController {
    @Autowired
    private SimpMessagingTemplate simpMessagingTemplate;

    @MessageMapping("/chat/private")
    public void sendPrivateMessage(@Payload ChatMessage chatMessage) {
        // 打印日志确认消息接收正常
        System.out.printf("发送私聊：%s -> %s：%s%n", 
                          chatMessage.getFromUsername(), 
                          chatMessage.getToUsername(), 
                          chatMessage.getContent());
        // 发送到目标用户的专属队列
        simpMessagingTemplate.convertAndSendToUser(
            chatMessage.getToUsername(), 
            "/queue/private", 
            chatMessage
        );
    }
}

消息实体类ChatMessage：

public class ChatMessage {
    private String fromUsername;
    private String toUsername;
    private String content;

    // 必须添加getter/setter，否则JSON序列化/反序列化会失败
    public String getFromUsername() { return fromUsername; }
    public void setFromUsername(String fromUsername) { this.fromUsername = fromUsername; }
    public String getToUsername() { return toUsername; }
    public void setToUsername(String toUsername) { this.toUsername = toUsername; }
    public String getContent() { return content; }
    public void setContent(String content) { this.content = content; }
}

（4）其他补充排查点 #

• 用户在线状态：SimpleBroker不支持离线消息持久化，接收方必须保持WebSocket连接在线才能收到消息
• 跨域配置：确保setAllowedOriginPatterns设置正确，避免因跨域限制导致消息被浏览器拦截
• 日志追踪：开启org.springframework.messaging和org.springframework.web.socket包的DEBUG日志，查看消息路由过程，确认是否有路由失败的情况

内容的提问来源于stack exchange，提问作者川大计院蒻篝