跳到主要内容

WebSocket API

ChatGPT-4o 中英对照 WebSocket API

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

WebSocketHandler​

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

public class MyHandler extends TextWebSocketHandler {

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

有专门的 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();
    }
}
java

前面的示例用于 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());
    }

}
java

一个更高级的选项是扩展 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 支持通过服务器特定的 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>
xml

然后，您可以通过名称有选择地启用 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>
xml

配置服务器​

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

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

@Configuration
public class WebSocketConfiguration {

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

对于客户端 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);
    }
}
java
提示

使用 STOMP over WebSocket 时，您还需要配置 STOMP WebSocket 传输 属性。

允许的来源​

从 Spring Framework 4.1.5 开始，WebSocket 和 SockJS 的默认行为是仅接受同源请求。也可以允许所有来源或指定的来源列表。此检查主要是为浏览器客户端设计的。没有什么能阻止其他类型的客户端修改 Origin 头的值（更多详情请参见 RFC 6454: The Web Origin Concept）。

三种可能的行为是：

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

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

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

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

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