WebSocket API

Spring Framework 提供了 WebSocket API，您可以使用该 API 编写处理 WebSocket 消息的客户端和服务端应用程序。

`WebSocketHandler`

创建 WebSocket 服务器与实现 WebSocketHandler 一样简单，或更可能的情况是扩展 TextWebSocketHandler 或 BinaryWebSocketHandler。以下示例使用 TextWebSocketHandler：

Java
Kotlin

public class MyHandler extends TextWebSocketHandler {

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

class MyHandler : TextWebSocketHandler() {

	override fun handleTextMessage(session: WebSocketSession, message: TextMessage) {
		// ...
	}
}

有专门的 WebSocket 编程配置和 XML 命名空间支持，用于将前面的 WebSocket 处理程序映射到特定 URL，如下例所示：

Java
Kotlin
Xml

@Configuration
@EnableWebSocket
public class WebSocketConfiguration implements WebSocketConfigurer {

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

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

@Configuration
@EnableWebSocket
class WebSocketConfiguration : WebSocketConfigurer {

	override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
		registry.addHandler(myHandler(), "/myHandler")
	}

	@Bean
	fun myHandler(): WebSocketHandler {
		return MyHandler()
	}
}

<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.docs.web.websocket.websocketserverhandler.MyHandler"/>

</beans>

前面的示例用于 Spring MVC 应用程序，并且应该包含在 DispatcherServlet的配置中。然而，Spring 的 WebSocket 支持并不依赖于 Spring MVC。在https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/socket/server/support/WebSocketHttpRequestHandler.html[WebSocketHttpRequestHandler]的帮助下，将 `WebSocketHandler`集成到其他 HTTP 服务环境中相对简单。

在直接对 WebSocketHandler`API 使用或间接（例如，通过STOMP消息传递）使用时，应用程序必须同步发送消息，因为底层标准 WebSocket 会话 (JSR-356) 不允许并发发送。其中一种选择是使用https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/socket/handler/ConcurrentWebSocketSessionDecorator.html[`ConcurrentWebSocketSessionDecorator]包装 WebSocketSession。

WebSocket Handshake

自定义初始 HTTP WebSocket 握手请求最简单的方法是通过 HandshakeInterceptor，该拦截器会公开握手中的“before”和“after”方法。你可以使用这样的拦截器来阻止握手或向 WebSocketSession 提供任何属性。以下示例使用内置拦截器将 HTTP 会话属性传递到 WebSocket 会话：

Java
Kotlin
Xml

@Configuration
@EnableWebSocket
public class WebSocketConfiguration implements WebSocketConfigurer {

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

}

@Configuration
@EnableWebSocket
class WebSocketConfiguration : WebSocketConfigurer {

	override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
		registry.addHandler(MyHandler(), "/myHandler")
			.addInterceptors(HttpSessionHandshakeInterceptor())
	}
}

<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.docs.web.websocket.websocketserverhandler.MyHandler"/>

</beans>

更高级的选项是扩展执行 WebSocket 握手步骤的`DefaultHandshakeHandler`，包括验证客户端原点、协商子协议和其他详细信息。应用程序也可能需要使用此选项，如果它需要配置自定义`RequestUpgradeStrategy`，以适应尚未受支持的 WebSocket 服务器引擎和版本（有关此问题的更多信息，请参见Deployment）。Java 配置和 XML 命名空间都可以配置自定义`HandshakeHandler`。

Spring 提供了一个 WebSocketHandlerDecorator 基本类，您可使用该类为 WebSocketHandler 添加其他行为。在使用 WebSocket Java 配置或 XML 命名空间时，会提供并默认添加日志记录和异常处理实现。ExceptionWebSocketHandlerDecorator 会捕获由任何 WebSocketHandler 方法引发的所有未捕获异常，并关闭具有状态 1011 的 WebSocket 会话，该状态表示服务器错误。

Deployment

Spring WebSocket API 很容易集成到 DispatcherServlet 同时提供 HTTP WebSocket 握手及其他 HTTP 请求的 Spring MVC 应用程序中。通过调用 WebSocketHttpRequestHandler，也很容易集成到其他 HTTP 处理场景中。这很方便且易于理解。但是，对于 JSR-356 运行时，需要特别考虑。

Jakarta WebSocket API (JSR-356) 提供两种部署机制。第一个涉及在启动时进行 Servlet 容器类路径扫描（Servlet 3 功能）。另一个是在 Servlet 容器初始化时使用的注册 API。这两种机制都不可能为所有 HTTP 处理（包括 WebSocket 握手和所有其他 HTTP 请求）使用一个“前端控制器”，例如 Spring MVC 的 DispatcherServlet。

这是 JSR-356 的一个重大限制，即使在 JSR-356 运行时中运行，Spring 的 WebSocket 支持也通过特定于服务器的 RequestUpgradeStrategy 实现解决了这个限制。目前针对 Tomcat、Jetty、GlassFish、WebLogic、WebSphere 和 Undertow（和 WildFly）有此类策略。从 Jakarta WebSocket 2.1 开始，有标准的请求升级策略可用，Spring 会在基于 Jakarta EE 10 的 Web 容器（例如 Tomcat 10.1 和 Jetty 12）上选择该策略。

第二个考虑因素是，支持 JSR-356 的 Servlet 容器有望执行 ServletContainerInitializer (SCI) 扫描，这可能会显着减慢应用程序启动速度——在某些情况下，是大幅减慢。如果在升级到支持 JSR-356 的 Servlet 容器版本后观察到重大影响，则应该可以通过在 web.xml 中使用 <absolute-ordering /> 元素来选择性地启用或禁用 Web 片段（和 SCI 扫描），如下例所示：

<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 的支持。以下示例展示了如何操作：

<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>

Configuring the Server

你可以配置底层 WebSocket 服务器，例如输入消息缓冲区大小、空闲超时等。

对于 Jakarta WebSocket 服务器，你可以向你的配置添加一个 ServletServerContainerFactoryBean。例如：

Java
Kotlin
Xml

@Configuration
public class WebSocketConfiguration {

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

@Configuration
class WebSocketConfiguration {

	@Bean
	fun createWebSocketContainer() = ServletServerContainerFactoryBean().apply {
		maxTextMessageBufferSize = 8192
		maxBinaryMessageBufferSize = 8192
	}
}

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

对于客户端 Jakarta WebSocket 配置，请在以编程方式配置时使用 ContainerProvider.getWebSocketContainer()，或在 XML 中使用 WebSocketContainerFactoryBean。

对于 Jetty，你可以提供一个回调来配置 WebSocket 服务器：

Java
Kotlin

@Configuration
@EnableWebSocket
public class JettyWebSocketConfiguration implements WebSocketConfigurer {

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

	@Bean
	public WebSocketHandler echoWebSocketHandler() {
		return new MyEchoHandler();
	}

	@Bean
	public DefaultHandshakeHandler handshakeHandler() {
		JettyRequestUpgradeStrategy strategy = new JettyRequestUpgradeStrategy();
		strategy.addWebSocketConfigurer(configurable -> {
			configurable.setInputBufferSize(8192);
			configurable.setIdleTimeout(Duration.ofSeconds(600));
		});
		return new DefaultHandshakeHandler(strategy);
	}
}

@Configuration
@EnableWebSocket
class JettyWebSocketConfiguration : WebSocketConfigurer {

	override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
		registry.addHandler(echoWebSocketHandler(), "/echo").setHandshakeHandler(handshakeHandler())
	}

	@Bean
	fun echoWebSocketHandler(): WebSocketHandler {
		return MyEchoHandler()
	}

	@Bean
	fun handshakeHandler(): DefaultHandshakeHandler {
		val strategy = JettyRequestUpgradeStrategy()
		strategy.addWebSocketConfigurer {
			it.inputBufferSize = 8192
			it.idleTimeout = Duration.ofSeconds(600)
		}
		return DefaultHandshakeHandler(strategy)
	}
}

当在 WebSocket 上使用 STOMP 时，还需要配置 STOMP WebSocket transport 属性。

Allowed Origins

在 Spring Framework 4.1.5 中，WebSocket 和 SockJS 的默认行为仅接受同源请求。也可允许全部来源或者特定来源列表。此项检查主要针对浏览器客户端设计。没有任何内容能够阻止其它类型的客户端修改 `Origin`头值（请参阅https://datatracker.ietf.org/doc/html/rfc6454[RFC 6454: Web 源概念]了解更多详细信息）。

三种可能的现象：

仅允许同源请求（默认）：在此模式中，当 SockJS 启用时，Iframe HTTP 响应头 @(13) 设置为 @(14)，并禁用 JSONP 传输，因为它不允许检查请求的来源。因此，当启用此模式时不支持 IE6 和 IE7。
允许指定的来源列表：每个允许的来源都必须以 @(15) 或 @(16) 开头。在此模式中，当 SockJS 启用时，将禁用 IFrame 传输。因此，当启用此模式时不支持 IE6 至 IE9。
允许所有来源：要启用此模式，您应提供 @(17) 作为允许的来源值。在此模式中，所有传输都可用。

您可以配置 WebSocket 和 SockJS 允许的来源，如下面的示例所示：

Java
Kotlin
Xml

@Configuration
@EnableWebSocket
public class WebSocketConfiguration implements WebSocketConfigurer {

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

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

@Configuration
@EnableWebSocket
class WebSocketConfiguration : WebSocketConfigurer {

	override fun registerWebSocketHandlers(registry: WebSocketHandlerRegistry) {
		registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("https://mydomain.com")
	}

	@Bean
	fun myHandler(): WebSocketHandler {
		return MyHandler()
	}
}

<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.docs.web.websocket.websocketserverhandler.MyHandler" />

</beans>