WebSocket API
Spring Framework 提供了一个 WebSocket API，您可以使用它来编写 client- 和 处理 WebSocket 消息的服务器端应用程序。
WebSocketHandler
创建 WebSocket 服务器就像实现 WebSocket 服务器一样简单，或者更多
可能扩展 或 。以下内容
示例用途 ：WebSocketHandlerTextWebSocketHandlerBinaryWebSocketHandlerTextWebSocketHandler
-
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。它相对简单
在 WebSocketHttpRequestHandler 的帮助下集成到其他 HTTP 服务环境中。WebSocketHandler
当直接使用与间接使用 API 时，例如，通过 STOMP 消息传递，应用程序必须同步消息的发送
因为底层标准 WebSocket 会话 （JSR-356） 不允许并发
发送。一种选择是用 ConcurrentWebSocketSessionDecorator 包装。WebSocketHandlerWebSocketSession
WebSocket 握手
自定义初始 HTTP WebSocket 握手请求的最简单方法是通过
a ，它公开了握手的“之前”和“之后”的方法。
你可以使用这样的拦截器来排除握手或创建任何属性
可用于 .以下示例使用内置侦听器
要将 HTTP 会话属性传递给 WebSocket 会话：HandshakeInterceptorWebSocketSession
-
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 握手的步骤，包括验证客户端源，
协商子协议和其他细节。应用程序可能还需要使用此
选项（如果需要配置自定义），以便
适配尚不支持的 WebSocket 服务器引擎和版本
（有关此主题的更多信息，请参阅部署）。
Java 配置和 XML 名称空间都可以配置自定义 .DefaultHandshakeHandlerRequestUpgradeStrategyHandshakeHandler
Spring 提供了一个可用于装饰的基类
a 具有附加行为。日志记录和异常处理
使用 WebSocket Java 配置时，默认提供和添加 implementations
或 XML 命名空间。渔获物均未捕获
异常，并关闭 WebSocket
session with status ，这表示服务器错误。WebSocketHandlerDecoratorWebSocketHandlerExceptionWebSocketHandlerDecoratorWebSocketHandler1011 |
部署
Spring WebSocket API 很容易集成到 Spring MVC 应用程序中，其中
它同时提供 HTTP WebSocket 握手和其他
HTTP 请求。它也很容易集成到其他 HTTP 处理场景中
通过调用 .这既方便又容易
理解。但是，对于 JSR-356 运行时，需要特别注意。DispatcherServletWebSocketHttpRequestHandler
Jakarta WebSocket API （JSR-356） 提供了两种部署机制。第一个
涉及启动时的 Servlet 容器类路径扫描（Servlet 3 的一项功能）。
另一个是在 Servlet 容器初始化时使用的注册 API。
这两种机制都无法实现使用单个 “前端控制器”
用于所有 HTTP 处理 — 包括 WebSocket 握手和所有其他 HTTP
请求 — 例如 Spring MVC 的 .DispatcherServlet
这是 JSR-356 的一个重大限制，Spring 的 WebSocket 支持解决了这个限制
特定于服务器的实现，即使在 JSR-356 运行时中运行时也是如此。
目前，Tomcat、Jetty、GlassFish、WebLogic、WebSphere 和 Undertow 都存在这样的策略
（和 WildFly）。从 Jakarta WebSocket 2.1 开始，可以使用标准请求升级策略
Spring 在基于 Jakarta EE 10 的 Web 容器（如 Tomcat 10.1 和 Jetty 12）上选择。RequestUpgradeStrategy
第二个考虑因素是需要支持 JSR-356 的 Servlet 容器
执行可能减慢应用程序速度的 （SCI） 扫描
启动 — 在某些情况下，效果会非常显著。如果在
升级到支持 JSR-356 的 Servlet 容器版本，它应该
可以有选择地启用或禁用 Web 片段（和 SCI 扫描）
通过使用 中的 元素，如下例所示：ServletContainerInitializer<absolute-ordering />web.xml
<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 片段，例如为 Servlet 3 提供支持的 Spring 自己的 Web 片段
Java 初始化 API。以下示例显示了如何执行此操作：SpringServletContainerInitializer
<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 的默认行为是接受
仅限同源请求。也可以允许所有或指定的源列表。
此检查主要针对浏览器客户端设计。没有什么能阻止其他类型
的客户端修改标头值（有关更多详细信息，请参阅 RFC 6454：Web Origin 概念）。Origin
三种可能的行为是：
-
仅允许同源请求（默认）：在此模式下，启用 Sockjs 时， Iframe HTTP 响应标头设置为 ，JSONP transport 被禁用，因为它不允许检查请求的来源。 因此，启用此模式时，不支持 IE6 和 IE7。
X-Frame-OptionsSAMEORIGIN -
允许指定的源列表：每个允许的源都必须以 或 开头。在此模式下，启用 Sockjs 时，将禁用 IFrame 传输。 因此，IE6 到 IE9 在执行此操作时不受支持 mode 已启用。
http://https:// -
允许所有源：要启用此模式，您应该提供作为允许的源 价值。在此模式下，所有传输都可用。
*
您可以配置 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>