在 Spring Boot 项目中引入 WebSocket 能力，最标准的方式就是使用 EnableWebSocket 注解来开启配置支持，并配合 WebSocketConfigurer 接口完成端点的注册与拦截器设置。这种方式比手动管理底层 Socket 简单很多，开发者只需关注消息处理逻辑。
一、引入必要依赖
要在 Spring Boot 中使用 EnableWebSocket，首先需要在构建文件中加入 WebSocket 相关的 starter。以 Maven 为例，spring-boot-starter-websocket 已经把底层容器所需的 API 都打包好了，不需要再单独引入 javax.websocket 或 tomcat 的 websocket 包。
如果项目本身是基于 Spring MVC 的，那么这个 starter 会无缝衔接已有的 DispatcherServlet 体系；若是响应式项目，则应考虑使用对应的 reactive websocket 支持，而不是本文提到的注解驱动模型。依赖添加完成后，记得执行一次编译，确认没有版本冲突。
二、使用 EnableWebSocket 开启配置
EnableWebSocket 是一个元注解，它的作用是向 Spring 容器注册 WebSocket 的配置处理器。我们通常在一个被 Configuration 标记的类上同时使用 EnableWebSocket，并让这个类实现 WebSocketConfigurer 接口。这样 Spring 在启动时就会读取 registerWebSocketHandlers 方法里的设置。
很多新手会疑惑为什么一定要实现接口，其实接口里定义的三个方法分别负责端点注册、拦截器添加以及允许的跨域来源。即使你暂时用不到拦截器，也必须提供空实现，否则编译无法通过。下面给出一个最基础的配置类结构说明。
| 配置项 | 对应方法 | 主要作用 |
|---|---|---|
| 端点路径 | addHandler | 绑定 URL 与 WebSocketHandler 实例 |
| 握手拦截 | addInterceptors | 在连接建立前做鉴权或日志记录 |
| 跨域许可 | setAllowedOrigins | 配置哪些域名可以建立连接 |
基础配置代码示例说明
在配置类中，我们先通过 new 一个 TextWebSocketHandler 的子类来作为消息处理器，然后在 registerWebSocketHandlers 里用 registry.addHandler 把它挂到比如 /ws 的路径下。若前端和后端不同源，必须调用 setAllowedOrigins 放开对应域名，否则浏览器会拦截握手。
需要注意的是，EnableWebSocket 只是触发自动配置，真正生效的是 WebSocketConfigurer 的实现逻辑。如果项目中存在多个配置类，建议把 WebSocket 的配置单独拆出，避免和其他 MVC 配置混在一起难以维护。
三、编写消息处理器
消息处理器一般继承 TextWebSocketHandler，重写 afterConnectionEstablished、handleTextMessage 和 afterConnectionClosed 等方法。afterConnectionEstablished 在连接成功时触发，适合用来把当前会话保存到内存 map 中，方便后续群发。
handleTextMessage 负责接收客户端发来的文本。你可以根据消息内容做路由，比如区分登录指令和业务指令。处理完之后，通过 session.sendMessage 把结果写回。如果消息体较大或频率高，建议引入线程池来异步处理，防止阻塞容器 IO 线程。
会话管理与推送
实际业务里，往往需要在后台定时任务或接口中主动向某个用户推消息。这时就可以从之前保存的 session 集合里按用户标识取出对应的 WebSocketSession，再调用 sendMessage 方法。注意发送前要判断 session 是否处于打开状态，避免写入已断开的连接导致异常。
另外，由于 WebSocket 连接可能很多，单机内存保存所有会话在大规模场景下并不合适。生产环境一般会结合 Redis 发布订阅或者消息队列，把推送事件广播到多个节点，再由各节点找自己机器上的会话进行下发。
四、前端如何对接
浏览器原生支持 WebSocket 对象，前端只需写 new WebSocket（后端地址）即可建立连接。连接打开后用 onmessage 监听服务端推送，用 send 方法向上发数据。若后端配置了允许跨域，前端部署在别的域名下也能正常握手。
调试阶段可以先用浏览器控制台临时创建连接，发几条测试报文看后台是否打印收到日志。确认链路通了之后再补重连机制和心跳包，心跳可以用前端定时 send 一个 ping 文本，后台收到后回 pong，以此保活 NAT 环境下的映射。
五、常见错误与排查
最常见的问题是 403 跨域。很多人忘了在配置里放开 origin，或者把 setAllowedOrigins 写成具体的 IP 却用了域名访问。其次是 handler 没有加 Component 注解导致注入为空，配置类里引用的其实是未初始化的对象。
还有一个隐蔽坑是容器问题：若项目打成 war 包放在外部 Tomcat，需要确保 Tomcat 版本支持 WebSocket 规范；而用内嵌 Tomcat 的 jar 包方式通常没这问题。遇到连接立即断开时，优先看后台有没有抛握手异常，再根据堆栈定位是拦截器还是处理器的问题。
总结来说，Spring Boot 整合 EnableWebSocket 的核心就是：加依赖、写带注解的配置类、实现处理器、前端建连。理清这条主线后，剩下的都是业务层面的收发与状态管理。
Spring_BootEnableWebSocket实时通信修改时间：2026-08-10 08:54:33