对于最新稳定版本，请使用 Spring Framework 7.0.6！spring-doc.cadn.net.cn

WebSocket API

参见响应式栈中的等效内容spring-doc.cadn.net.cn

Spring Framework 提供了一个 WebSocket API，可用于编写处理 WebSocket 消息的客户端和服务器端应用程序。spring-doc.cadn.net.cn

WebSocketHandler

参见响应式栈中的等效内容spring-doc.cadn.net.cn

创建一个 WebSocket 服务器非常简单，只需实现 WebSocketHandler，或者更常见的是，继承 TextWebSocketHandler 或 BinaryWebSocketHandler。以下示例使用了 TextWebSocketHandler：spring-doc.cadn.net.cn

import org.springframework.web.socket.WebSocketHandler;
import org.springframework.web.socket.WebSocketSession;
import org.springframework.web.socket.TextMessage;

public class MyHandler extends TextWebSocketHandler {

	@Override
	public void handleTextMessage(WebSocketSession session, TextMessage message) {
		// ...
	}

}

有专门的 WebSocket Java 配置和 XML 命名空间支持，用于将上述 WebSocket 处理器映射到特定的 URL，如下例所示：spring-doc.cadn.net.cn

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 {

	@Override
	public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
		registry.addHandler(myHandler(), "/myHandler");
	}

	@Bean
	public WebSocketHandler myHandler() {
		return new MyHandler();
	}

}

以下示例展示了与前述示例等效的 XML 配置：spring-doc.cadn.net.cn

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:websocket="http://www.springframework.org/schema/websocket"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/websocket
		https://www.springframework.org/schema/websocket/spring-websocket.xsd">

	<websocket:handlers>
		<websocket:mapping path="/myHandler" handler="myHandler"/>
	</websocket:handlers>

	<bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

前面的示例用于 Spring MVC 应用程序，应包含在 DispatcherServlet 的配置中。然而，Spring 的 WebSocket 支持并不依赖于 Spring MVC。借助 WebSocketHttpRequestHandler，将 WebSocketHandler 集成到其他 HTTP 服务环境中相对简单。spring-doc.cadn.net.cn

当直接使用 WebSocketHandler API（而非间接使用，例如通过 STOMP 消息传递）时，应用程序必须同步消息的发送， 因为底层的标准 WebSocket 会话（JSR-356）不允许并发发送。一种选择是将 WebSocketSession 包装为 ConcurrentWebSocketSessionDecorator。spring-doc.cadn.net.cn

WebSocket 握手

参见响应式栈中的等效内容spring-doc.cadn.net.cn

自定义初始 HTTP WebSocket 握手请求最简单的方法是通过一个 HandshakeInterceptor，它提供了“握手前”和“握手后”的方法。 您可以使用此类拦截器来阻止握手，或者将任意属性传递给 WebSocketSession。 以下示例使用了一个内置拦截器，将 HTTP 会话属性传递到 WebSocket 会话中：spring-doc.cadn.net.cn

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

	@Override
	public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
		registry.addHandler(new MyHandler(), "/myHandler")
			.addInterceptors(new HttpSessionHandshakeInterceptor());
	}

}

以下示例展示了与前述示例等效的 XML 配置：spring-doc.cadn.net.cn

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:websocket="http://www.springframework.org/schema/websocket"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/websocket
		https://www.springframework.org/schema/websocket/spring-websocket.xsd">

	<websocket:handlers>
		<websocket:mapping path="/myHandler" handler="myHandler"/>
		<websocket:handshake-interceptors>
			<bean class="org.springframework.web.socket.server.support.HttpSessionHandshakeInterceptor"/>
		</websocket:handshake-interceptors>
	</websocket:handlers>

	<bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

一种更高级的选项是扩展 DefaultHandshakeHandler，该处理器负责执行 WebSocket 握手的各个步骤，包括验证客户端来源、协商子协议以及其他细节。如果应用程序需要配置自定义的 RequestUpgradeStrategy，以适配尚未被支持的 WebSocket 服务器引擎和版本，也可能需要使用此选项（有关此主题的更多内容，请参见部署）。Java 配置和 XML 命名空间都支持配置自定义的 HandshakeHandler。spring-doc.cadn.net.cn

Spring 提供了一个 WebSocketHandlerDecorator 基类，可用于为 WebSocketHandler 添加额外的行为。日志记录和异常处理的实现已提供，并在使用 WebSocket 的 Java 配置或 XML 命名空间时默认添加。ExceptionWebSocketHandlerDecorator 会捕获所有从任意 WebSocketHandler 方法中抛出的未捕获异常，并以状态码 1011（表示服务器错误）关闭 WebSocket 会话。

部署

Spring WebSocket API 很容易集成到 Spring MVC 应用程序中，其中 DispatcherServlet 同时处理 HTTP WebSocket 握手和其他 HTTP 请求。通过调用 WebSocketHttpRequestHandler，也很容易将其集成到其他 HTTP 处理场景中。这种方式既方便又易于理解。然而，在 JSR-356 运行时环境下，需要考虑一些特殊事项。spring-doc.cadn.net.cn

Jakarta WebSocket API（JSR-356）提供了两种部署机制。第一种是在启动时通过 Servlet 容器进行类路径扫描（Servlet 3 的一项特性）。另一种是在 Servlet 容器初始化时使用的注册 API。这两种机制都无法使用单一的“前端控制器”来处理所有 HTTP 请求——包括 WebSocket 握手以及所有其他 HTTP 请求——例如 Spring MVC 中的 DispatcherServlet。spring-doc.cadn.net.cn

这是 JSR-356 的一个重大限制，Spring 的 WebSocket 支持通过服务器特定的 RequestUpgradeStrategy 实现来解决该问题，即使在 JSR-356 运行时环境中也是如此。 目前，Tomcat、Jetty、GlassFish、WebLogic、WebSphere 和 Undertow（以及 WildFly）都已有相应的策略实现。 从 Jakarta WebSocket 2.1 开始，提供了一个标准的请求升级策略，Spring 会在基于 Jakarta EE 10 的 Web 容器（例如 Tomcat 10.1 和 Jetty 12）中使用该标准策略。spring-doc.cadn.net.cn

另一个次要的考虑因素是，支持 JSR-356 的 Servlet 容器会执行 ServletContainerInitializer（SCI）扫描，这可能会减慢应用程序的启动速度——在某些情况下，甚至会显著降低。如果在升级到支持 JSR-356 的 Servlet 容器版本后观察到明显的性能影响，则应可通过在 <absolute-ordering /> 中使用 web.xml 元素，有选择地启用或禁用 Web 片段（以及 SCI 扫描），如下例所示：spring-doc.cadn.net.cn

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="
		https://jakarta.ee/xml/ns/jakartaee
		https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
	version="5.0">

	<absolute-ordering/>

</web-app>

然后，您可以按名称选择性地启用 Web 片段，例如 Spring 自带的 SpringServletContainerInitializer，它为 Servlet 3 的 Java 初始化 API 提供支持。以下示例展示了如何实现这一点：spring-doc.cadn.net.cn

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="
		https://jakarta.ee/xml/ns/jakartaee
		https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
	version="5.0">

	<absolute-ordering>
		<name>spring_web</name>
	</absolute-ordering>

</web-app>

配置服务器

参见响应式栈中的等效内容spring-doc.cadn.net.cn

您可以配置底层 WebSocket 服务器的参数，例如输入消息缓冲区大小、空闲超时时间等。spring-doc.cadn.net.cn

对于 Jakarta WebSocket 服务器，您可以在 Java 配置中添加一个 ServletServerContainerFactoryBean。例如：spring-doc.cadn.net.cn

@Bean
public ServletServerContainerFactoryBean createWebSocketContainer() {
    ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean();
    container.setMaxTextMessageBufferSize(8192);
    container.setMaxBinaryMessageBufferSize(8192);
    return container;
}

或者添加到您的 XML 配置中：spring-doc.cadn.net.cn

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:websocket="http://www.springframework.org/schema/websocket"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/websocket
		https://www.springframework.org/schema/websocket/spring-websocket.xsd">

	<bean class="org.springframework...ServletServerContainerFactoryBean">
		<property name="maxTextMessageBufferSize" value="8192"/>
		<property name="maxBinaryMessageBufferSize" value="8192"/>
	</bean>

</beans>
对于客户端 Jakarta WebSocket 的配置，在 Java 配置中使用 ContainerProvider.getWebSocketContainer()，或在 XML 中使用 WebSocketContainerFactoryBean。

对于 Jetty，你可以提供一个 Consumer 回调来配置 WebSocket 服务器：spring-doc.cadn.net.cn

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

	@Override
	public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
		registry.addHandler(echoWebSocketHandler(),
			"/echo").setHandshakeHandler(handshakeHandler());
	}

	@Bean
	public DefaultHandshakeHandler handshakeHandler() {
		WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER);
		policy.setInputBufferSize(8192);
		policy.setIdleTimeout(600000);
		return new DefaultHandshakeHandler(
				new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy)));
	}

}

以下示例展示了与前述示例等效的 XML 配置：spring-doc.cadn.net.cn

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:websocket="http://www.springframework.org/schema/websocket"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/websocket
		https://www.springframework.org/schema/websocket/spring-websocket.xsd">

	<websocket:handlers>
		<websocket:mapping path="/echo" handler="echoHandler"/>
		<websocket:handshake-handler ref="handshakeHandler"/>
	</websocket:handlers>

	<bean id="handshakeHandler" class="org.springframework...DefaultHandshakeHandler">
		<constructor-arg ref="upgradeStrategy"/>
	</bean>

	<bean id="upgradeStrategy" class="org.springframework...JettyRequestUpgradeStrategy">
		<constructor-arg ref="serverFactory"/>
	</bean>

	<bean id="serverFactory" class="org.eclipse.jetty...WebSocketServerFactory">
		<constructor-arg>
			<bean class="org.eclipse.jetty...WebSocketPolicy">
				<constructor-arg value="SERVER"/>
				<property name="inputBufferSize" value="8092"/>
				<property name="idleTimeout" value="600000"/>
			</bean>
		</constructor-arg>
	</bean>

</beans>
使用基于 WebSocket 的 STOMP 时，您还需要配置 STOMP WebSocket 传输 属性。

允许的源

参见响应式栈中的等效内容spring-doc.cadn.net.cn

从 Spring Framework 4.1.5 起，WebSocket 和 SockJS 的默认行为是仅接受同源请求。也可以配置为允许所有来源或指定的来源列表。 此检查主要是为浏览器客户端设计的。其他类型的客户端仍然可以随意修改 Origin 请求头的值（更多详情请参见 RFC 6454：Web 源概念）。spring-doc.cadn.net.cn

三种可能的行为是：spring-doc.cadn.net.cn

  • 仅允许同源请求（默认）：在此模式下，当启用 SockJS 时，Iframe 的 HTTP 响应头 X-Frame-Options 会被设置为 SAMEORIGIN，同时 JSONP 传输方式将被禁用，因为它无法检查请求的来源。 因此，启用此模式后，IE6 和 IE7 将不再受支持。spring-doc.cadn.net.cn

  • 允许指定的来源列表：每个允许的来源必须以 http:// 或 https:// 开头。在此模式下，当启用 SockJS 时，IFrame 传输将被禁用。 因此，启用此模式后，IE6 至 IE9 将不再受支持。spring-doc.cadn.net.cn

  • 允许所有源：要启用此模式，您应将 * 作为允许的源值提供。在此模式下，所有传输方式均可用。spring-doc.cadn.net.cn

您可以配置 WebSocket 和 SockJS 的允许来源（allowed origins），如下例所示：spring-doc.cadn.net.cn

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 {

	@Override
	public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
		registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("https://mydomain.com");
	}

	@Bean
	public WebSocketHandler myHandler() {
		return new MyHandler();
	}

}

以下示例展示了与前述示例等效的 XML 配置：spring-doc.cadn.net.cn

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:websocket="http://www.springframework.org/schema/websocket"
	xsi:schemaLocation="
		http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/websocket
		https://www.springframework.org/schema/websocket/spring-websocket.xsd">

	<websocket:handlers allowed-origins="https://mydomain.com">
		<websocket:mapping path="/myHandler" handler="myHandler" />
	</websocket:handlers>

	<bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>