在Spring Boot项目中实现浏览器与服务器的双向实时通信，STOMP over WebSocket是一种成熟且易用的方案。通过@EnableSTOMP相关注解，开发者能够以消息代理的模式组织实时通信逻辑，而不必关心底层WebSocket帧的处理细节。
一、整合前的环境准备
开始整合之前，需要确认项目基于Spring Boot 2.x或以上版本，并使用Maven或Gradle管理依赖。STOMP本身是一个简单的文本导向消息协议，它工作在WebSocket之上，因此我们必须先让项目具备WebSocket支持能力。
在Maven的pom.xml中，应添加spring-boot-starter-websocket依赖。这个起步依赖已经包含了Spring WebSocket模块以及STOMP相关的消息处理类。不需要额外引入原始的javax.websocket包，因为Spring的抽象层会统一处理。
依赖配置示例
下面是一段典型的Maven依赖声明，它足以支撑后续的EnableSTOMP整合工作：
- spring-boot-starter-web：提供基础Web容器
- spring-boot-starter-websocket：提供WebSocket与STOMP支持
- spring-boot-starter-thymeleaf（可选）：用于编写简单演示页面
二、使用@EnableWebSocketMessageBroker开启STOMP
Spring Boot中并没有一个单独叫做@EnableSTOMP的注解，通常所说的EnableSTOMP是指使用@EnableWebSocketMessageBroker来启用STOMP消息代理功能。这个注解放在配置类上，告诉Spring启用基于WebSocket的消息代理机制。
被注解的配置类需要实现WebSocketMessageBrokerConfigurer接口，从而重写关键方法，例如registerStompEndpoints与configureMessageBroker。前者用来暴露STOMP连接的WebSocket端点，后者用来定义应用前缀与代理前缀。
基础配置类写法
一个最小可用的配置类通常如下组织：使用@Configuration标注类，加上@EnableWebSocketMessageBroker，然后重写方法。在registerStompEndpoints里通过registry.addEndpoint("/ws").withSockJS()暴露端点并允许SockJS回退；在configureMessageBroker里设置enableSimpleBroker("/topic")以及setApplicationDestinationPrefixes("/app")。
这样设置之后，前端连接/ws端点，发送以/app开头的消息会进入服务端Controller，而服务器向/topic开头的地址发送消息时，客户端可以订阅并接收。这种前缀划分让消息路由非常清晰。
三、编写消息控制器与广播逻辑
服务端收发STOMP消息主要依靠@Controller与@MessageMapping注解。@MessageMapping类似于@RequestMapping，用来映射客户端发来的目的地址。配合@SendTo注解，可以把返回值直接转发到某个代理主题。
例如客户端向/app/chat发送消息，控制器方法用@MessageMapping("chat")接收，处理完后用@SendTo("/topic/messages")把结果广播给所有订阅者。如果是主动推送，比如后台定时任务，则可以注入SimpMessagingTemplate，调用convertAndSend方法向指定主题发消息。
常用注解对照
| 注解或类 | 作用说明 |
|---|---|
| @EnableWebSocketMessageBroker | 启用STOMP消息代理配置 |
| @MessageMapping | 接收客户端发往应用前缀的消息 |
| @SendTo | 将控制器返回值发往指定代理主题 |
| SimpMessagingTemplate | 服务端主动推送消息到主题的模板工具 |
四、前端如何连接并订阅
前端一般使用SockJS与STOMP.js库。先通过SockJS连接/ws端点，再用Stomp.over(socket)创建STOMP客户端，调用connect方法完成握手。连接成功后，使用subscribe("/topic/messages", callback)订阅主题，并在回调里更新页面。
发送消息时，调用stompClient.send("/app/chat", {}, JSON.stringify({content: 'hello'}))。注意目的地必须以配置中的应用前缀开头，否则服务端Controller无法收到。若连接失败，先检查是否忘了withSockJS，或浏览器不支持WebSocket但又未开启回退。
五、常见问题与排查思路
实际整合中，最常见的问题是404或连接立即断开。多数情况是因为端点未暴露、前缀写错，或没有引入webstarter导致DispatcherServlet未正确加载。可以在浏览器开发者工具里查看WebSocket帧，确认连接地址与发送目的地。
另一个容易忽略的点是跨域。如果前端页面与后端不在同一域，要在注册端点时调用setAllowedOriginPatterns允许来源，否则浏览器会拦截握手。此外，Spring Security若启用，还需放行STOMP端点与SockJS相关资源。
整合Spring Boot与STOMP的核心在于理解应用前缀、代理前缀与端点的关系，配置正确后，实时消息推送并不复杂。
六、小结
通过@EnableWebSocketMessageBroker开启STOMP，配合明确的前缀规则与简单的控制器写法，Spring Boot项目能够快速拥有实时推送能力。掌握配置类、消息路由与前端连接方式，就可以在通知、聊天、监控等场景中稳定使用。
后续若消息量增大，可将内置简单代理替换为RabbitMQ或ActiveMQ等外部代理，只需在configureMessageBroker中调用enableStompBrokerRelay并填写中继地址即可，应用代码基本不用改动。
Spring_BootEnableSTOMPWebSocket修改时间：2026-08-11 10:27:29