Java WebSocket异常处理需分连接、通信、关闭三阶段：连接失败捕获DeploymentException/IOException并检查配置；通信中用try-catch处理DecodeException等并在@OnError/@OnClose中规范清理资源；日志需结构化记录Session ID、远程地址等上下文。
Java WebSocket异常处理核心是区分连接阶段、通信阶段和关闭阶段的错误类型，针对性地捕获、记录和恢复。
连接建立失败的常见原因和处理
客户端无法连接到服务端，通常抛出 DeploymentException（服务端部署失败）或 IOException（网络不通、端口被占、SSL配置错误等）。
- 检查服务端是否已启动，WebSocket端点路径（如
@ServerEndpoint("/ws")）是否与客户端请求一致 - 确认服务器防火墙、反向代理（Nginx/Tomcat）是否支持WebSocket协议升级（需透传
Upgrade和Connection: upgrade头） - 客户端用
new WebSocket(url)时，URL必须是ws://或wss://，不能是http:// - 服务端使用 Spring Boot +
@EnableWebSocket时，确保添加了WebSocketHandlerRegistry配置，且未被 MVC 的拦截器误拦
运行中通信异常的捕获与响应
连接建立后，消息收发过程可能触发 DecodeException（解码失败）、EncodeException（编码失败）、RuntimeException（业务逻辑异常）或底层 IOException（连接中断）。
- 在
@OnMessage方法中用 try-catch 包裹业务逻辑，避免未捕获异常导致会话意外关闭 - 实现
javax.websocket.MessageHandler.Whole<string></string>时，若自定义Decoder.Text抛异常，会进入@OnError，此时可调用session.close()并记录原始报文用于排查 - 对关键操作（如广播、持久化）加超时控制，防止线程阻塞导致心跳超时断连
@OnError 和 @OnClose 必须正确实现
这两个生命周期方法不是“可选补充”，而是异常兜底和资源清理的关键入口。
立即学习“Java免费学习笔记（深入）”；
-
@OnError方法参数必须是Session和Throwable，不要忽略 Throwable —— 它包含真实异常堆栈，比如java.io.EOFException表示对方已静默断开 - 在
@OnError中避免再调用session.getBasicRemote().sendText()，此时 session 往往已不可用，会引发IllegalStateException -
@OnClose中应清理该 Session 关联的缓存、定时任务、数据库连接等，推荐用ConcurrentHashMap管理在线会话，并配合session.getId()做唯一标识
日志和监控建议
单纯打印异常堆栈不够，要结构化记录关键上下文。
- 记录 Session ID、远程地址（
session.getRemoteAddress()）、异常时间、错误码（如 CloseReason.getCloseCode()） - 对高频断连场景，增加连接耗时、ping-pong 延迟、消息吞吐量等指标埋点
- 使用 Logback 的
AsyncAppender避免日志阻塞 I/O 线程；敏感字段（如 token）需脱敏 - Spring Boot 项目可集成 Actuator + Prometheus，暴露
/actuator/metrics/websocket.sessions.active类指标
基本上就这些。WebSocket 异常不复杂但容易忽略阶段差异，抓住“谁在什么时候抛了什么错”，再配合适当的日志和清理机制，排查效率能明显提升。
