WebSocket 是 HTML5 提出的新型通信协议,实现了浏览器与服务器之间的全双工通信。相较于传统 HTTP 请求-响应模式,WebSocket 建立连接后可保持长期连接,支持服务器主动推送消息,极大降低了通信延迟和带宽消耗。在实时聊天、在线游戏、金融行情推送、协同编辑等场景中,Java WebSocket 技术已成为企业级应用的标准选择。
本教程系统讲解 Java 生态下 WebSocket 的完整开发体系,涵盖协议原理、服务端实现(原生 API、Tomcat、Spring Boot)、客户端集成、性能调优、安全加固、故障排查及真实项目案例。无论您是初学者还是资深开发者,都能从中获取可落地的工程实践方案。
WebSocket 通过一次握手建立持久连接,后续通信仅需 2~10 字节帧头部,消息传输效率提升 10~20 倍,完美解决上述问题。
| 特性 | HTTP/1.1 | WebSocket |
|---|---|---|
| 连接模式 | 短连接(每次请求后关闭) | 长连接(一次握手,持续通信) |
| 数据格式 | 文本(需序列化) | 二进制/文本(支持 Frame 分片) |
| 通信方向 | 客户端→服务器 | 全双工(双向实时) |
| 握手协议 | TCP 直接通信 | HTTP Upgrade 机制(Upgrade: websocket) |
| 典型应用 | 网页加载、API 调用 | 聊天室、实时监控、在线协作 |
WebSocket 协议由 IETF 定义为 RFC 6455,其握手过程基于 HTTP,但升级后完全脱离 HTTP 协议栈,使用独立帧格式。理解这一区别是避免开发误区的关键。
WebSocket 握手由客户端发起 Upgrade 请求,服务器响应 101 状态码完成协议切换:
客户端请求: GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13 服务器响应: HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
此过程确保握手请求的真实性,避免恶意服务端响应。一旦握手成功,后续通信完全使用 WebSocket 帧格式。
WebSocket 数据以帧(Frame)为单位传输,每个帧包含:
示例:发送文本 "Hello" 的帧结构(简化):
| 字节 | 内容 | 说明 |
|---|---|---|
| 0 | 10000001 | FIN=1, Opcode=1(文本帧) |
| 1 | 10000101 | Mask=1, Payload Length=5(<126) |
| 2-5 | 掩码密钥(4字节) | 客户端生成随机数 |
| 6-10 | 加密后数据 | "Hello" ⊕ 掩码 |
心跳机制是维持长连接稳定的核心策略,防止中间设备(如 NAT、防火墙)因超时关闭连接。
Java EE 7 引入 JSR 356,提供标准 WebSocket API。核心注解:
@ServerEndpoint("/ws/chat")
public class ChatWebSocket {
private Session session;
@OnOpen
public void onOpen(Session session) {
this.session = session;
System.out.println("连接建立: " + session.getId());
session.getBasicRemote().sendText("欢迎加入聊天室!");
}
@OnMessage
public void onMessage(String message, Session session) {
System.out.println("收到消息: " + message);
// 广播给所有连接
session.getBasicRemote().sendText("广播: " + message);
}
@OnClose
public void onClose(CloseReason reason) {
System.out.println("连接关闭: " + reason.getReasonPhrase());
}
}
Tomcat 7.0.27+ 开始支持 WebSocket,通过 WebSocketServletFactory 注册端点:
public class MyWebSocketServlet extends WebSocketServlet {
@Override
protected void configure(WebSocketServletFactory factory) {
factory.register(MyEndpoint.class);
}
}
关键配置项(conf/web.xml):
| 参数 | 默认值 | 说明 |
|---|---|---|
org.apache.tomcat.websocket.server.WsConfig.STANDARD_ENDPOINT_CONFIG |
false | 是否启用标准端点配置 |
org.apache.tomcat.websocket.server.WsConfig.TEXT_BUFFER_SIZE |
8192 | 文本缓冲区大小(字节) |
org.apache.tomcat.websocket.server.WsConfig.BINARY_BUFFER_SIZE |
8192 | 二进制缓冲区大小(字节) |
建议生产环境调整缓冲区大小以适配大消息场景(如文件传输):
factory.getPolymerConfig().setBinaryBufferSize(32768);
Jakarta WebSocket 规范(原 JSR 356)由 Jetty、Tomcat 等容器实现。Jetty 的 WebSocket API 更贴近底层,适合定制高性能场景:
public class JettyWebSocket extends AbstractWebSocket {
@Override
public void onWebSocketText(String message) {
getRemote().sendString(message, null);
}
}
Jetty 优势:更低的内存占用、更灵活的线程模型,适合百万级连接场景。
// 创建连接
const ws = new WebSocket('wss://www.xservx.com/ws/chat');
// 监听连接事件
ws.onopen = () => console.log('连接已建立');
ws.onmessage = event => console.log('收到消息:', event.data);
ws.onclose = event => console.log('连接关闭:', event.code);
ws.onerror = error => console.error('连接错误:', error);
// 发送消息
ws.send(JSON.stringify({ type: 'chat', content: 'Hello' }));
// 关闭连接
ws.close(1000, '正常退出');
ws://(非加密)和 wss://(加密,需 HTTPS 服务)Sec-WebSocket-Protocol 头指定(如 ['chat', 'game'])@ClientEndpoint
public class ChatClient {
private Session session;
@OnOpen
public void onOpen(Session session) {
this.session = session;
session.getBasicRemote().sendText("客户端已连接");
}
@OnMessage
public void onMessage(String message) {
System.out.println("收到: " + message);
}
}
// 启动客户端
WebSocketContainer container = ContainerProvider.getWebSocketContainer();
container.connectToServer(ChatClient.class, URI.create("ws://localhost:8080/ws/chat"));
// 重连示例
let retries = 0;
function connect() {
const ws = new WebSocket('ws://localhost:8080/ws');
ws.onclose = () => {
const delay = Math.min(1000 * 2 ** retries, 30000);
setTimeout(connect, delay);
retries++;
};
}
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-websocket</artifactId>
</dependency>
@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
@Override
public void registerStompEndpoints(StompEndpointRegistry registry) {
registry.addEndpoint("/ws/chat")
.setAllowedOrigins("*") // 允许跨域
.withSockJS(); // 兼容旧浏览器
}
@Override
public void configureMessageBroker(MessageBrokerRegistry registry) {
registry.enableSimpleBroker("/topic", "/queue");
registry.setApplicationDestinationPrefixes("/app");
}
}
@Controller
public class ChatController {
@MessageMapping("/chat.send")
@SendTo("/topic/messages")
public ChatMessage send(ChatMessage message) {
return message; // 自动广播到 /topic/messages
}
}
WebSocket 是传输层协议,而 STOMP(Simple Text Oriented Messaging Protocol)是应用层协议,提供消息路由、订阅/发布模型:
Spring WebSocket 默认集成 STOMP,简化客户端开发:
const stompClient = Stomp.over(() => new WebSocket('ws://localhost:8080/ws/chat'));
stompClient.connect({ 'Authorization': 'Bearer token' }, frame => {
stompClient.subscribe('/topic/messages', message => {
console.log('收到:', JSON.parse(message.body));
});
});
| 特性 | 原生 Java API | Spring WebSocket |
|---|---|---|
| 开发复杂度 | 低(注解简单) | 中(需配置消息代理) |
| 消息路由 | 需手动实现 | STOMP 自动路由 |
| 认证集成 | 需自定义拦截器 | Spring Security 深度集成 |
| 测试支持 | 需模拟 Session | MockWebSocketClient 等工具完善 |
| 适用场景 | 轻量级、低耦合 | 企业级、高内聚 |
WebSocket 连接是持久连接,每个连接占用:
单机支持连接数估算(以 16GB 内存服务器为例):
可用内存 ≈ 12GB(预留 4GB 给 OS)
每个连接消耗 ≈ 212KB(buffer) + 3KB(Session) = 215KB
理论最大连接数 ≈ 12×1024 / 215 ≈ 57,000
实际需考虑 GC、线程栈等开销,建议上限为 3~5 万/机。
Per-Message Compression(RFC 7692):
factory.getPolymerConfig().setCompressionSupported(true);
使用 Artillery(Node.js)模拟 WebSocket 负载:
config:
target: "ws://localhost:8080/ws/chat"
phases:
- duration: 60
arrivalRate: 1000 # 每秒新增1000连接
scenarios:
- flow:
- send: '{"type":"join","room":"lobby"}'
- wait: 5s
- send: '{"type":"chat","content":"test"}'
监控指标:
const ws = new WebSocket('wss://api.example.com/ws?token=' + token);
registry.addEndpoint("/ws")
.addInterceptors(new HttpSessionIdHandshakeInterceptor());
limit_req zone=ws;)server.websocket.max-text-message-size=65536)org.apache.tomcat.websocket.server.WsConfig.IDLE_TIMEOUT=30000)HtmlUtils.htmlEscape())。生产环境必须使用 wss://(WebSocket Secure),通过 Nginx 或 Tomcat 配置 SSL:
server {
listen 443 ssl;
ssl_certificate /etc/ssl/cert.pem;
ssl_certificate_key /etc/ssl/key.pem;
location /ws/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
| 错误码 | 原因 | 解决方案 |
|---|---|---|
| 1006 (ABNORMAL_CLOSURE) | 连接异常中断(网络波动、服务崩溃) | |
| 1008 (POLICY_VIOLATION) | 消息内容违反策略(如超长消息) | |
| 1011 (INTERNAL_ERROR) | 服务端处理异常(未捕获异常) | |
| 1013 (TRY_AGAIN_LATER) | 服务端过载(临时拒绝) |
spring-websocket-test 模拟客户端现象:连接数持续增长,内存溢出(OOM)。
排查步骤:
@OnClose 是否正常执行(日志缺失?)修复示例:
@OnClose
public void onClose(Session session) {
try {
// 清理资源(如移除用户在线列表)
} finally {
// 确保 Session 关闭
if (session != null && session.isOpen()) {
session.close();
}
}
}
需求:客服与用户实时对话,支持文件传输、消息已读回执。
方案:
{ type: 'chat', content: 'Hello', timestamp: 1620000000000 }
{ type: 'file', fileName: 'report.pdf', size: 102400 }
性能:单机支持 1.2 万并发会话,消息延迟 P95=65ms。
需求:每秒推送 5000+ 股票行情(JSON 数据,<2KB/条)。
优化措施:
结果:带宽消耗降低 45%,CPU 使用率下降 22%。
挑战:多用户实时编辑文档,需解决操作冲突。
技术方案:
核心 OT 操作格式:
{ op: 'insert', pos: 10, text: 'Hello', clientId: 'u123' }