Spring Boot集成WebSocket需四步：一、引入starter并配置ServerEndpointExporter；二、用@ServerEndpoint或STOMP替代原生Handler；三、前端带参数连接、校验状态、统一JSON解析；四、配置心跳、指数重连、会话清理。
在 Spring Boot 中集成 WebSocket 实现实时通信，核心是建立服务端与前端之间的持久双向连接，让服务端能主动推消息，而不是依赖前端轮询。关键不在于“能不能连上”，而在于“怎么管好连接、怎么发对人、怎么稳住长链”。下面分四块讲清楚实际落地要点。
一、基础依赖和配置要一步到位
只加一个 starter 不够，得配齐协议支持和开发便利性组件：
- 必须引入
spring-boot-starter-websocket，这是整个功能的底座； - 建议加上
commons-lang3和lombok，处理字符串、简化实体类代码，避免手写 getter/setter 分散注意力； - 配置类用
@Configuration + @Bean ServerEndpointExporter就行，不需要@EnableWebSocket（那是老写法），Spring Boot 2.0+ 自动识别@ServerEndpoint注解。
二、服务端逻辑别直接裸写 WebSocketHandler
原生 WebSocketHandler 虽然灵活，但连接管理、用户绑定、消息广播都得自己撸——容易出错还难维护。更推荐两种路径：
Java注释规范Skills
下载
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- 如果只是简单广播或点对点通知（比如系统公告、订单状态变更），用
@ServerEndpoint注解类 +@OnOpen/@OnMessage回调，配合ConcurrentHashMap存 session 和用户 ID 映射，够用且轻量； - 如果涉及群聊、@提醒、消息回执、订阅/发布模式，直接上 STOMP 协议：加
spring-boot-starter-websocket后，再配置SimpleBrokerMessageHandler或StompBrokerRelay，用@MessageMapping定义入口，@SendTo或@SendToUser控制投递目标，逻辑清晰、扩展性强。
三、前端连接和消息收发要带上下文
前端不能只写 new WebSocket('ws://...') 就完事，得考虑真实场景：
立即学习“Java免费学习笔记（深入）”；
- 连接 URL 建议带参数，如
ws://localhost:8080/ws?userId=123，后端在@OnOpen阶段从session.getRequestParameterMap()提取，完成用户身份绑定； - 发送消息前检查
readyState === 1，避免连接未就绪就发包； - 监听
onmessage时，建议统一解析 JSON 格式消息体（如{type: 'NOTICE', data: {...}}），方便前端按 type 分发处理逻辑，而不是一堆 if-else 判断原始字符串。
四、上线前必须处理的三个稳定性问题
本地跑通不等于线上可用，这三个点最容易被忽略：
-
心跳保活：Nginx 默认 60 秒断空闲连接，需在 Nginx 配置里加
proxy_read_timeout 300，后端也建议每 45 秒发一次 ping 帧（STOMP 下自动有心跳机制）； -
异常重连：前端
onclose触发后，用指数退避策略重试（如 1s、2s、4s…最大 30s），避免雪崩式重连压垮服务； -
会话清理：用户关闭页面或网络中断时，
@OnClose方法里务必从缓存中移除 session，并触发“用户离线”事件（比如更新数据库状态、发下线通知）。
