此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Framework 6.2.10！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

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

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，如以下示例所示：spring-doc.cadn.net.cn

@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。相对简单集成一个WebSocketHandler借助其他 HTTP 服务环境WebSocketHttpRequestHandler.spring-doc.cadn.net.cn

使用WebSocketHandlerAPI 直接与间接，例如，通过 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 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>

更高级的选项是扩展DefaultHandshakeHandler执行 WebSocket握手的步骤，包括验证客户端源，协商子协议和其他细节。应用程序可能还需要使用它选项，如果需要配置自定义RequestUpgradeStrategy为了适配尚不支持的 WebSocket 服务器引擎和版本（有关此主题的更多信息，请参阅部署）。 Java 配置和 XML 命名空间都可以配置自定义HandshakeHandler.spring-doc.cadn.net.cn

Spring 提供了一个WebSocketHandlerDecorator可用于装饰的基类一个WebSocketHandler具有附加行为。日志记录和异常处理使用 WebSocket Java 配置时，默认情况下提供和添加实现或 XML 命名空间。这ExceptionWebSocketHandlerDecorator捕获所有未捕获的因任何WebSocketHandler方法并关闭 WebSocket 会话1011，这表示服务器错误。

部署

Spring WebSocket API 很容易集成到 Spring MVC 应用程序中，其中这DispatcherServlet同时提供 HTTP WebSocket 握手和其他HTTP 请求。它也很容易集成到其他 HTTP 处理场景中通过调用WebSocketHttpRequestHandler. 这既方便又容易理解。但是，对于 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 容器版本后观察到重大影响，则应该可以有选择地启用或禁用 Web 片段（和 SCI 扫描）通过使用<absolute-ordering />元素web.xml，如以下示例所示：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 3Java 初始化 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 服务器，例如输入消息缓冲区大小、idle 超时等。spring-doc.cadn.net.cn

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

@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（），或WebSocketContainerFactoryBean在 XML 中。

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

Javaspring-doc.cadn.net.cn
Kotlinspring-doc.cadn.net.cn

@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 传输属性。

允许的源

请参阅响应式堆栈中的等效项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 传输。因此，当此模式已启用。spring-doc.cadn.net.cn
允许所有源：要启用此模式，您应该提供允许的源价值。在此模式下，所有传输都可用。*spring-doc.cadn.net.cn

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

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