Spring Boot集成WebSocket有@ServerEndpoint和WebSocketMessageBrokerConfigurer两种方式：前者基于Java EE标准，需ServerEndpointExporter注册，适合轻量场景；后者基于Spring消息代理，支持STOMP、订阅发布与权限控制，适合企业级应用。
Spring Boot 集成 WebSocket 不是“配个注解就能用”，关键在于选对模式、管住生命周期、避开线程安全陷阱。直接上手容易在高并发下丢消息、内存泄漏或连接假死。
@ServerEndpoint 方式：适合轻量级、无 Spring 上下文依赖的场景
这是最直白的 Java EE 标准写法，不走 Spring 的消息代理机制，所有会话管理、广播逻辑都得自己写。
-
@ServerEndpoint必须配合ServerEndpointExporterBean 才能被 Tomcat 扫描到，否则 404；Jetty/Undertow 不支持该注解，必须换方案 - 类不能依赖
@Autowired注入 Spring Bean（默认不受 Spring 管理），需手动从ApplicationContext获取，或改用@Component+@Scope("prototype")并配合自定义ServerEndpointConfig.Configurator -
Session对象不是线程安全的，session.getAsyncRemote().sendText()是异步非阻塞调用，但并发调用可能触发IllegalStateException: Session is closed - 在线人数统计若用
static AtomicInteger，必须确保@OnOpen/@OnClose成对触发；客户端强制断网、浏览器崩溃等场景会导致@OnClose不执行，需加心跳检测和超时清理
WebSocketMessageBrokerConfigurer 方式：适合需要权限控制、消息路由、STOMP 协议的业务系统
这是 Spring 官方推荐的企业级方案，底层基于 SimpleBroker 或集成 RabbitMQ/Redis，天然支持订阅/发布、消息拦截、用户认证。
WebSocket 8.18.2
下载
WebSocket 8.18.2 是该协议规范的一个重要迭代版本，主要优化了连接稳定性与数据传输效率。它通过全双工通信机制，允许客户端与服务器在单一长连接上实时交换数据，大幅降低传统 HTTP 轮询的开销。该版本增强了心跳保活、自动重连及二进制帧传输能力，适用于即时通讯、在线游戏及金融行情推送等低延迟场景，为开发者提供更可靠的实时网络交互基础。
-
@EnableWebSocketMessageBroker和@Configuration缺一不可，否则@MessageMapping不生效 -
setApplicationDestinationPrefixes("/app")表示客户端发往/app/xxx的消息由@MessageMapping("/xxx")处理；enableSimpleBroker("/topic", "/queue")表示服务端可向这些前缀推送消息 - 若用
withSockJS()兼容老旧浏览器，注意 SockJS 会降级为 HTTP 长轮询，sendMessage延迟上升且不支持二进制帧 - 前端必须用 STOMP over WebSocket（如
stompjs库），不能直接用原生WebSocketAPI 连接/ws端点，否则握手失败或收不到消息
常见错误：Connection refused / 404 / No message received
这些错误基本不是代码写错，而是配置链路断在某个环节。
- 启动日志没出现
Started WebSocket endpoint at /api/websocket或Registered STOMP endpoint '/ws'→ 检查ServerEndpointExporter是否声明，或@EnableWebSocketMessageBroker是否遗漏 - 前端
new WebSocket("ws://localhost:8080/api/websocket/123")报Connection refused→ 确认服务端是否启用 WebSocket 支持（spring-boot-starter-websocket依赖存在且未被排除） - 能连上但收不到服务端
sendMessage的消息 → 检查是否调用了session.getBasicRemote().sendText()（同步阻塞）而非getAsyncRemote()后没处理Future异常；或广播时遍历了CopyOnWriteArraySet但部分Session已关闭 - 使用 Nginx 反代后 WebSocket 断连频繁 → Nginx 配置必须包含
proxy_http_version 1.1、proxy_set_header Upgrade $http_upgrade、proxy_set_header Connection "upgrade"
生产环境必须关注的三个细节
本地跑通不等于线上可用，这几个点最容易被跳过。
- 连接数限制：Tomcat 默认
maxConnections=8192，单机万级连接需调大，并监控tomcat.global.request.maxTime指标，避免慢连接拖垮线程池 - 消息粘包/分片：WebSocket 协议本身不保证消息边界，大消息（>64KB）可能被自动分片，
@OnMessage方法可能被多次调用；建议应用层加长度头或统一用 JSON 封装 - 会话状态丢失：重启服务时所有
Session彻底消失，若需消息可靠投递，必须引入外部存储（如 Redis 记录订阅关系 + 消息队列暂存离线消息）
