跳到主要内容
版本：7.0.3

WebSocket API

Hunyuan 7b 中英对照 WebSocket API

Spring框架提供了一个WebSocket API，你可以使用它来编写处理WebSocket消息的客户端和服务器端应用程序。

WebSocketHandler​

创建一个WebSocket服务器就像实现WebSocketHandler一样简单，或者更确切地说，是扩展TextWebSocketHandler或BinaryWebSocketHandler。以下示例使用了TextWebSocketHandler：

public class MyHandler extends TextWebSocketHandler {

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

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

@Configuration
@EnableWebSocket
public class WebSocketConfiguration implements WebSocketConfigurer {

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

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

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

在使用WebSocketHandler API时，无论是直接使用还是通过STOMP消息传递等方式间接使用，应用程序都必须同步发送消息，因为底层的标准WebSocket会话（JSR-356）不允许并发发送。一种解决方案是使用ConcurrentWebSocketSessionDecorator来包装WebSocketSession。

WebSocket握手​

自定义初始HTTP WebSocket握手请求的最简单方法是通过HandshakeInterceptor，它提供了“握手之前”和“握手之后”运行的方法。你可以使用这样的拦截器来阻止握手过程，或者将某些属性传递给WebSocketSession。以下示例使用了一个内置的拦截器，将HTTP会话属性传递给WebSocket会话：

@Configuration
@EnableWebSocket
public class WebSocketConfiguration implements WebSocketConfigurer {

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

}

一个更高级的选项是扩展DefaultHandshakeHandler，该处理器执行WebSocket握手过程的各个步骤，包括验证客户端来源、协商子协议以及其他细节。如果应用程序需要配置自定义的RequestUpgradeStrategy以便适应尚未支持的WebSocket服务器引擎和版本，那么也可能需要使用这个选项（有关此主题的更多信息，请参见部署）。无论是Java配置还是XML命名空间，都允许配置自定义的HandshakeHandler。

提示

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

部署​

Spring WebSocket API很容易集成到Spring MVC应用程序中，在该应用程序中，DispatcherServlet同时处理HTTP WebSocket握手和其他HTTP请求。通过调用WebSocketHttpRequestHandler，它也容易集成到其他HTTP处理场景中。这既方便又易于理解。然而，对于JSR-356运行时来说，需要特别考虑一些问题。

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

这是JSR-356的一个重大限制，而Spring在WebSocket API 2.1+运行环境中通过标准的RequestUpgradeStrategy实现解决了这一问题。

另一个需要考虑的因素是，支持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>

配置服务器​

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

对于Jakarta WebSocket服务器，您可以在配置中添加一个ServletServerContainerFactoryBean。例如：

@Configuration
public class WebSocketConfiguration {

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

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

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

@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);
	}
}
提示

在使用基于WebSocket的STOMP协议时，您还需要配置STOMP WebSocket传输层的相关属性。

允许的来源​

从 Spring Framework 4.1.5 开始，WebSocket 和 SockJS 的默认行为是仅接受同源请求。也可以允许所有来源或指定的来源列表。这种检查主要是针对浏览器客户端设计的。没有机制阻止其他类型的客户端修改 Origin 请求头值（更多细节请参见 RFC 6454：Web Origin 概念）。

三种可能的行为是：

  • 仅允许同源请求（默认模式）：在此模式下，当启用 SockJS 时，Iframe 的 HTTP 响应头 X-Frame-Options 被设置为 SAMEORIGIN，并且禁用了 JSONP 传输方式，因为 JSONP 无法检查请求的来源。因此，当此模式启用时，不支持 IE6 和 IE7。

  • 允许指定的来源列表：每个允许的来源必须以 http:// 或 https:// 开头。在此模式下，当启用 SockJS 时，Iframe 传输方式被禁用。因此，当此模式启用时，不支持 IE6 到 IE9。

  • 允许所有来源：要启用此模式，应使用 * 作为允许的来源值。在此模式下，所有传输方式都是可用的。

你可以配置WebSocket和SockJS允许的源地址（origins），如下例所示：

@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();
	}
}