注解

EnableWebSocket

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
@Import(DelegatingWebSocketConfiguration.class)
public @interface EnableWebSocket {}

DelegatingWebSocketConfiguration

@Configuration(proxyBeanMethods = false)
public class DelegatingWebSocketConfiguration extends WebSocketConfigurationSupport {private final List<WebSocketConfigurer> configurers = new ArrayList<>();@Autowired(required = false)public void setConfigurers(List<WebSocketConfigurer> configurers) {if (!CollectionUtils.isEmpty(configurers)) {this.configurers.addAll(configurers);}}@Overrideprotected void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {for (WebSocketConfigurer configurer : this.configurers) {configurer.registerWebSocketHandlers(registry);}}
}

WebSocketConfigurationSupport

public class WebSocketConfigurationSupport {@Nullableprivate ServletWebSocketHandlerRegistry handlerRegistry;@Beanpublic HandlerMapping webSocketHandlerMapping(@Qualifier("defaultSockJsSchedulerContainer") DefaultSockJsSchedulerContainer schedulerContainer) {ServletWebSocketHandlerRegistry registry = initHandlerRegistry();if (registry.requiresTaskScheduler()) {TaskScheduler scheduler = schedulerContainer.getScheduler();Assert.notNull(scheduler, "TaskScheduler is required but not initialized");registry.setTaskScheduler(scheduler);}return registry.getHandlerMapping();}private ServletWebSocketHandlerRegistry initHandlerRegistry() {if (this.handlerRegistry == null) {this.handlerRegistry = new ServletWebSocketHandlerRegistry();registerWebSocketHandlers(this.handlerRegistry);}return this.handlerRegistry;}protected void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {}@BeanDefaultSockJsSchedulerContainer defaultSockJsSchedulerContainer() {return (initHandlerRegistry().requiresTaskScheduler() ?new DefaultSockJsSchedulerContainer(initDefaultSockJsScheduler()) :new DefaultSockJsSchedulerContainer(null));}private ThreadPoolTaskScheduler initDefaultSockJsScheduler() {ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();scheduler.setThreadNamePrefix("SockJS-");scheduler.setPoolSize(Runtime.getRuntime().availableProcessors());scheduler.setRemoveOnCancelPolicy(true);return scheduler;}static class DefaultSockJsSchedulerContainer implements InitializingBean, DisposableBean {@Nullableprivate final ThreadPoolTaskScheduler scheduler;DefaultSockJsSchedulerContainer(@Nullable ThreadPoolTaskScheduler scheduler) {this.scheduler = scheduler;}@Nullablepublic ThreadPoolTaskScheduler getScheduler() {return this.scheduler;}@Overridepublic void afterPropertiesSet() throws Exception {if (this.scheduler != null) {this.scheduler.afterPropertiesSet();}}@Overridepublic void destroy() throws Exception {if (this.scheduler != null) {this.scheduler.destroy();}}}
}

WebSocketConfigurer

public interface WebSocketConfigurer {void registerWebSocketHandlers(WebSocketHandlerRegistry registry);}

WebSocketHandlerRegistry

public interface WebSocketHandlerRegistry {WebSocketHandlerRegistration addHandler(WebSocketHandler webSocketHandler, String... paths);}

ServletWebSocketHandlerRegistry

public class ServletWebSocketHandlerRegistry implements WebSocketHandlerRegistry {private final List<ServletWebSocketHandlerRegistration> registrations = new ArrayList<>(4);private int order = 1;public ServletWebSocketHandlerRegistry() {}@Overridepublic WebSocketHandlerRegistration addHandler(WebSocketHandler handler, String... paths) {ServletWebSocketHandlerRegistration registration = new ServletWebSocketHandlerRegistration();registration.addHandler(handler, paths);this.registrations.add(registration);return registration;}public AbstractHandlerMapping getHandlerMapping() {Map<String, Object> urlMap = new LinkedHashMap<>();for (ServletWebSocketHandlerRegistration registration : this.registrations) {MultiValueMap<HttpRequestHandler, String> mappings = registration.getMappings();mappings.forEach((httpHandler, patterns) -> {for (String pattern : patterns) {urlMap.put(pattern, httpHandler);}});}WebSocketHandlerMapping hm = new WebSocketHandlerMapping();hm.setUrlMap(urlMap);hm.setOrder(this.order);if (this.urlPathHelper != null) {hm.setUrlPathHelper(this.urlPathHelper);}return hm;}
}

请求

推荐阅读：[spring6: DispatcherServlet.doDispatch]-源码分析

WebSocketHandlerMapping

public class WebSocketHandlerMapping extends SimpleUrlHandlerMapping implements SmartLifecycle {private boolean webSocketUpgradeMatch;@Nullableprivate Integer phase;private volatile boolean running;@Override@Nullableprotected Object getHandlerInternal(HttpServletRequest request) throws Exception {// new HandlerExecutionChain(WebSocketHttpRequestHandler)Object handler = super.getHandlerInternal(request);return (matchWebSocketUpgrade(handler, request) ? handler : null);}private boolean matchWebSocketUpgrade(@Nullable Object handler, HttpServletRequest request) {handler = (handler instanceof HandlerExecutionChain chain ? chain.getHandler() : handler);if (this.webSocketUpgradeMatch && handler instanceof WebSocketHttpRequestHandler) {String header = request.getHeader(HttpHeaders.UPGRADE);return (HttpMethod.GET.matches(request.getMethod()) &&header != null && header.equalsIgnoreCase("websocket"));}return true;}}

HttpRequestHandlerAdapter

public class HttpRequestHandlerAdapter implements HandlerAdapter {@Overridepublic boolean supports(Object handler) {return (handler instanceof HttpRequestHandler);}@Override@Nullablepublic ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler)throws Exception {((HttpRequestHandler) handler).handleRequest(request, response);return null;}@Override@SuppressWarnings("deprecation")public long getLastModified(HttpServletRequest request, Object handler) {if (handler instanceof LastModified lastModified) {return lastModified.getLastModified(request);}return -1L;}}

WebSocketHttpRequestHandler

public class WebSocketHttpRequestHandler implements HttpRequestHandler, Lifecycle, ServletContextAware {private static final Log logger = LogFactory.getLog(WebSocketHttpRequestHandler.class);private final WebSocketHandler wsHandler;private final HandshakeHandler handshakeHandler;private final List<HandshakeInterceptor> interceptors = new ArrayList<>();private volatile boolean running;public WebSocketHttpRequestHandler(WebSocketHandler wsHandler, HandshakeHandler handshakeHandler) {Assert.notNull(wsHandler, "wsHandler must not be null");Assert.notNull(handshakeHandler, "handshakeHandler must not be null");this.wsHandler = decorate(wsHandler);this.handshakeHandler = handshakeHandler;}protected WebSocketHandler decorate(WebSocketHandler handler) {return new ExceptionWebSocketHandlerDecorator(new LoggingWebSocketHandlerDecorator(handler));}@Overridepublic void handleRequest(HttpServletRequest servletRequest, HttpServletResponse servletResponse) throws ServletException, IOException {ServerHttpRequest request = new ServletServerHttpRequest(servletRequest);ServerHttpResponse response = new ServletServerHttpResponse(servletResponse);HandshakeInterceptorChain chain = new HandshakeInterceptorChain(this.interceptors, this.wsHandler);HandshakeFailureException failure = null;try {if (logger.isDebugEnabled()) {logger.debug(servletRequest.getMethod() + " " + servletRequest.getRequestURI());}Map<String, Object> attributes = new HashMap<>();if (!chain.applyBeforeHandshake(request, response, attributes)) {return;}// 握手流程，校验请求头、协议版本、Origin 等信息后，底层调用StandardWebSocketUpgradeStrategy完成协议升级this.handshakeHandler.doHandshake(request, response, this.wsHandler, attributes);chain.applyAfterHandshake(request, response, null);}catch (HandshakeFailureException ex) {failure = ex;}catch (Exception ex) {failure = new HandshakeFailureException("Uncaught failure for request " + request.getURI() + " - " + ex.getMessage(), ex);}finally {if (failure != null) {chain.applyAfterHandshake(request, response, failure);response.close();throw failure;}response.close();}}
}

StandardWebSocketUpgradeStrategy

基于标准 Java WebSocket API，实现了通过 Servlet 容器（如 Tomcat）将 HTTP 请求升级为 WebSocket 连接的核心逻辑。

public class StandardWebSocketUpgradeStrategy extends AbstractStandardUpgradeStrategy {private static final String[] SUPPORTED_VERSIONS = new String[] {"13"};@Overridepublic String[] getSupportedVersions() {return SUPPORTED_VERSIONS;}// endpoint: StandardWebSocketHandlerAdapter@Overrideprotected void upgradeInternal(ServerHttpRequest request, ServerHttpResponse response,@Nullable String selectedProtocol, List<Extension> selectedExtensions, Endpoint endpoint)throws HandshakeFailureException {HttpServletRequest servletRequest = getHttpServletRequest(request);HttpServletResponse servletResponse = getHttpServletResponse(response);StringBuffer requestUrl = servletRequest.getRequestURL();String path = servletRequest.getRequestURI();  // shouldn't matterMap<String, String> pathParams = Collections.<String, String> emptyMap();ServerEndpointRegistration endpointConfig = new ServerEndpointRegistration(path, endpoint);endpointConfig.setSubprotocols(Collections.singletonList(selectedProtocol));endpointConfig.setExtensions(selectedExtensions);try {upgradeHttpToWebSocket(servletRequest, servletResponse, endpointConfig, pathParams);}catch (Exception ex) {throw new HandshakeFailureException("Servlet request failed to upgrade to WebSocket: " + requestUrl, ex);}}protected void upgradeHttpToWebSocket(HttpServletRequest request, HttpServletResponse response,ServerEndpointConfig endpointConfig, Map<String,String> pathParams) throws Exception {getContainer(request).upgradeHttpToWebSocket(request, response, endpointConfig, pathParams);}}

StandardWebSocketHandlerAdapter

/*** Adapts a {@link WebSocketHandler} to the standard WebSocket for Java API.** @author Rossen Stoyanchev* @since 4.0*/
public class StandardWebSocketHandlerAdapter extends Endpoint {private final Log logger = LogFactory.getLog(StandardWebSocketHandlerAdapter.class);private final WebSocketHandler handler;private final StandardWebSocketSession wsSession;public StandardWebSocketHandlerAdapter(WebSocketHandler handler, StandardWebSocketSession wsSession) {Assert.notNull(handler, "WebSocketHandler must not be null");Assert.notNull(wsSession, "WebSocketSession must not be null");this.handler = handler;this.wsSession = wsSession;}@Overridepublic void onOpen(final jakarta.websocket.Session session, EndpointConfig config) {this.wsSession.initializeNativeSession(session);// The following inner classes need to remain since lambdas would not retain their// declared generic types (which need to be seen by the underlying WebSocket engine)if (this.handler.supportsPartialMessages()) {session.addMessageHandler(new MessageHandler.Partial<String>() {@Overridepublic void onMessage(String message, boolean isLast) {handleTextMessage(session, message, isLast);}});session.addMessageHandler(new MessageHandler.Partial<ByteBuffer>() {@Overridepublic void onMessage(ByteBuffer message, boolean isLast) {handleBinaryMessage(session, message, isLast);}});}else {session.addMessageHandler(new MessageHandler.Whole<String>() {@Overridepublic void onMessage(String message) {handleTextMessage(session, message, true);}});session.addMessageHandler(new MessageHandler.Whole<ByteBuffer>() {@Overridepublic void onMessage(ByteBuffer message) {handleBinaryMessage(session, message, true);}});}session.addMessageHandler(new MessageHandler.Whole<jakarta.websocket.PongMessage>() {@Overridepublic void onMessage(jakarta.websocket.PongMessage message) {handlePongMessage(session, message.getApplicationData());}});try {this.handler.afterConnectionEstablished(this.wsSession);}catch (Exception ex) {ExceptionWebSocketHandlerDecorator.tryCloseWithError(this.wsSession, ex, logger);}}private void handleTextMessage(jakarta.websocket.Session session, String payload, boolean isLast) {TextMessage textMessage = new TextMessage(payload, isLast);try {this.handler.handleMessage(this.wsSession, textMessage);}catch (Exception ex) {ExceptionWebSocketHandlerDecorator.tryCloseWithError(this.wsSession, ex, logger);}}private void handleBinaryMessage(jakarta.websocket.Session session, ByteBuffer payload, boolean isLast) {BinaryMessage binaryMessage = new BinaryMessage(payload, isLast);try {this.handler.handleMessage(this.wsSession, binaryMessage);}catch (Exception ex) {ExceptionWebSocketHandlerDecorator.tryCloseWithError(this.wsSession, ex, logger);}}private void handlePongMessage(jakarta.websocket.Session session, ByteBuffer payload) {PongMessage pongMessage = new PongMessage(payload);try {this.handler.handleMessage(this.wsSession, pongMessage);}catch (Exception ex) {ExceptionWebSocketHandlerDecorator.tryCloseWithError(this.wsSession, ex, logger);}}@Overridepublic void onClose(jakarta.websocket.Session session, CloseReason reason) {CloseStatus closeStatus = new CloseStatus(reason.getCloseCode().getCode(), reason.getReasonPhrase());try {this.handler.afterConnectionClosed(this.wsSession, closeStatus);}catch (Exception ex) {if (logger.isWarnEnabled()) {logger.warn("Unhandled on-close exception for " + this.wsSession, ex);}}}@Overridepublic void onError(jakarta.websocket.Session session, Throwable exception) {try {this.handler.handleTransportError(this.wsSession, exception);}catch (Exception ex) {ExceptionWebSocketHandlerDecorator.tryCloseWithError(this.wsSession, ex, logger);}}}

WebSocketHandler

public interface WebSocketHandler {void afterConnectionEstablished(WebSocketSession session) throws Exception;void handleMessage(WebSocketSession session, WebSocketMessage<?> message) throws Exception;void handleTransportError(WebSocketSession session, Throwable exception) throws Exception;void afterConnectionClosed(WebSocketSession session, CloseStatus closeStatus) throws Exception;boolean supportsPartialMessages();}

实战

页面

<!DOCTYPE html>
<html lang="zh-CN">
<head><meta charset="UTF-8" /><title>WebSocket 测试页面</title><style>body { font-family: Arial, sans-serif; margin: 20px; }#messages { border: 1px solid #ccc; height: 200px; overflow-y: scroll; padding: 10px; }#inputArea { margin-top: 10px; }</style>
</head>
<body><h2>WebSocket 测试客户端</h2><label for="wsUrl">WebSocket 地址:</label><input type="text" id="wsUrl" size="40" value="ws://localhost:8080/demo" /><button id="connectBtn">连接</button><button id="disconnectBtn" disabled>断开连接</button><div id="status">状态：未连接</div><div id="messages"></div><div id="inputArea"><input type="text" id="messageInput" size="40" placeholder="输入消息..." /><button id="sendBtn" disabled>发送</button></div><script>let websocket;const statusEl = document.getElementById('status');const messagesEl = document.getElementById('messages');const connectBtn = document.getElementById('connectBtn');const disconnectBtn = document.getElementById('disconnectBtn');const sendBtn = document.getElementById('sendBtn');const messageInput = document.getElementById('messageInput');const wsUrlInput = document.getElementById('wsUrl');function appendMessage(msg) {const p = document.createElement('p');p.textContent = msg;messagesEl.appendChild(p);messagesEl.scrollTop = messagesEl.scrollHeight; // 自动滚动到底部}connectBtn.onclick = () => {const url = wsUrlInput.value;websocket = new WebSocket(url);websocket.onopen = () => {statusEl.textContent = '状态：已连接';appendMessage('已连接到 ' + url);connectBtn.disabled = true;disconnectBtn.disabled = false;sendBtn.disabled = false;};websocket.onmessage = (event) => {appendMessage('收到消息: ' + event.data);};websocket.onerror = (event) => {appendMessage('发生错误');console.error('WebSocket 错误:', event);};websocket.onclose = () => {statusEl.textContent = '状态：已断开';appendMessage('连接已关闭');connectBtn.disabled = false;disconnectBtn.disabled = true;sendBtn.disabled = true;};};disconnectBtn.onclick = () => {if (websocket) {websocket.close();}};sendBtn.onclick = () => {const msg = messageInput.value;if (msg && websocket && websocket.readyState === WebSocket.OPEN) {websocket.send(msg);appendMessage('发送消息: ' + msg);messageInput.value = '';}};// 支持回车发送消息messageInput.addEventListener('keypress', function(event) {if (event.key === 'Enter') {sendBtn.click();event.preventDefault();}});
</script>
</body>
</html>

配置

package xyz.idoly.demo;import org.springframework.context.annotation.Configuration;
import org.springframework.web.socket.WebSocketSession;
import org.springframework.web.socket.TextMessage;
import org.springframework.web.socket.CloseStatus;
import org.springframework.web.socket.handler.TextWebSocketHandler;
import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;@Configuration
@EnableWebSocket
public class WebsocketConfig implements WebSocketConfigurer {@Overridepublic void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {registry.addHandler(new DemoHandler(), "/demo").setAllowedOrigins("*");}private static class DemoHandler extends TextWebSocketHandler {@Overridepublic void afterConnectionEstablished(WebSocketSession session) throws Exception {System.out.println("连接建立：" + session.getId());session.sendMessage(new TextMessage("欢迎连接 WebSocket 服务"));}@Overrideprotected void handleTextMessage(WebSocketSession session, TextMessage message) throws Exception {System.out.println("收到消息：" + message.getPayload());session.sendMessage(new TextMessage("服务器收到: " + message.getPayload()));}@Overridepublic void afterConnectionClosed(WebSocketSession session, CloseStatus status) throws Exception {System.out.println("连接关闭：" + session.getId());}}
}

效果