|
此版本仍在开发中，尚未稳定。如需最新的稳定版本，请使用 Spring Framework 7.0.6！ |
WebSocket API
Spring框架提供了一个WebSocket 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处理器映射到特定URL，存在专门的WebSocket编程配置和XML命名空间支持，如下例所示：
-
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。借助WebSocketHttpRequestHandler，相对简单地将WebSocketHandler集成到其他HTTP服务环境中。
在直接使用WebSocketHandler API与间接使用（例如，通过STOMP消息传递）之间，应用程序必须同步消息发送，因为底层标准WebSocket会话（JSR-356）不允许并发发送。一种选择是将WebSocketSession包装在ConcurrentWebSocketSessionDecorator中。
WebSocket握手
定制初始HTTP WebSocket握手请求的最简单方法是通过一个HandshakeInterceptor，它提供了在握手“之前”和“之后”的方法。你可以使用此类拦截器来阻止握手或使任何属性对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>一个更高级的选项是扩展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 运行时有一些特殊注意事项。
雅加达WebSocket API（JSR-356）提供两种部署机制。第一种机制涉及在启动时进行Servlet容器类路径扫描（Servlet 3的特性）。另一种是在Servlet容器初始化时使用的注册API。这两种机制都无法实现为所有HTTP处理（包括WebSocket握手和其他所有HTTP请求）使用单一"前端控制器"，例如Spring MVC的DispatcherServlet。
这是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）上选择使用标准请求升级策略。
一个次要的考虑因素是，支持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。例如:
-
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传输 属性。 |
允许的源
从Spring Framework 4.1.5开始，默认行为是仅接受同源请求的WebSocket和SockJS。也可以允许所有或指定列表中的源。此检查主要是为浏览器客户端设计的。没有任何东西阻止其他类型的客户端修改Origin头值（有关详细信息，请参阅RFC 6454: Web Origin Concept）。
三种可能的行为是：
-
仅允许同源请求（默认）：在这种模式下，当SockJS启用时，Iframe HTTP响应头
X-Frame-Options被设置为SAMEORIGIN，并且禁用JSONP传输，因为它不允许检查请求的来源。因此，当启用此模式时，IE6和IE7不受支持。 -
允许指定的来源列表：每个允许的来源必须以
http://或https://开头。在这种模式下，当 SockJS 启用时，IFrame 传输将被禁用。因此，启用此模式时，IE6 到 IE9 不受支持。 -
允许所有源：要启用此模式，您应提供
*作为允许的源值。在此模式下，所有传输方式都可用。
您可以配置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>