Spring Framework 參考文件（WebSocket API）

博弈發表於2018-10-17
SpringFrameworkWebAPI

WebSocket API

Spring Framework提供了一個WebSocket API，你可以使用它來編寫處理WebSocket訊息的客戶端和伺服器端應用程式。

WebSocketHandler

建立WebSocket伺服器就像實現WebSocketHandler一樣簡單，或者更可能是擴充套件TextWebSocketHandler或BinaryWebSocketHandler，下面的示例使用TextWebSocketHandler：

import org.springframework.web.socket.WebSocketHandler;
import org.springframework.web.socket.WebSocketSession;
import org.springframework.web.socket.TextMessage;

public class MyHandler extends TextWebSocketHandler {

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

}

有專門的WebSocket Java配置和XML名稱空間支援將前面的WebSocket處理程式對映到特定的URL，如下面的示例所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

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

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

}

下面的示例顯示了與前面示例等價的XML配置：

<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
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers>
        <websocket:mapping path="/myHandler" handler="myHandler"/>
    </websocket:handlers>

    <bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

本示例用於Spring MVC應用程式，並且應該包含在DispatcherServlet的配置中，然而，Spring的WebSocket支援不依賴於Spring MVC，在WebSocketHttpRequestHandler的幫助下，將WebSocketHandler整合到其他http服務環境中相對簡單。

WebSocket握手

定製初始的HTTP WebSocket握手請求的最簡單方法是通過HandshakeInterceptor，它公開握手之前和之後的方法，你可以使用這樣的攔截器來阻止握手或使WebSocketSession的任何屬性有效，下面的示例使用內建的攔截器將HTTP會話屬性傳遞給WebSocket會話：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

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

}

下面的示例顯示了與前面示例等價的XML配置：

<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
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://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.samples.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執行時，需要特別考慮。

Java 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），目前存在這樣的策略。

已經建立了克服Java WebSocket API中上述限制的請求，可以在eclipse-ee4j/websocket-api#211中進行跟蹤。Tomcat、Undertow和WebSphere提供了它們自己的API選項，可以實現這一點，Jetty也是如此，我們希望更多的伺服器也能這樣做。

第二個需要考慮的問題是，具有JSR-356支援的Servlet容器預計將執行ServletContainerInitializer（SCI）掃描，這可能會減慢應用程式的啟動速度 — 在某些情況下，會顯著降低啟動速度。如果在升級到支援JSR-356的Servlet容器版本後觀察到重大影響，通過使用web.xml中的<absolute-ordering />元素，應該可以選擇性地啟用或禁用web片段（和SCI掃描），如下例所示：

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    <absolute-ordering/>

</web-app>

然後可以根據名稱選擇性地啟用web片段，比如Spring自己的SpringServletContainerInitializer，它為Servlet 3 Java初始化API提供支援，下面的示例展示瞭如何做到這一點：

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://java.sun.com/xml/ns/javaee
        http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
    version="3.0">

    <absolute-ordering>
        <name>spring_web</name>
    </absolute-ordering>

</web-app>

伺服器配置

每個基礎WebSocket引擎都公開了控制執行時特性的配置屬性，比如訊息緩衝區大小、空閒超時等等。

對於Tomcat、WildFly和GlassFish，你可以將ServletServerContainerFactoryBean新增到WebSocket Java配置中，如下面的示例所示：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

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

}

下面的示例顯示了與前面示例等價的XML配置：

<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
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <bean class="org.springframework...ServletServerContainerFactoryBean">
        <property name="maxTextMessageBufferSize" value="8192"/>
        <property name="maxBinaryMessageBufferSize" value="8192"/>
    </bean>

</beans>

對於客戶端WebSocket配置，你應該使用WebSocketContainerFactoryBean（XML）或ContainerProvider.getWebSocketContainer()（Java配置）。

對於Jetty，需要提供預配置的Jetty WebSocketServerFactory，並通過WebSocket Java配置將其插入Spring的DefaultHandshakeHandler，下面的示例展示瞭如何做到這一點：

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(echoWebSocketHandler(),
            "/echo").setHandshakeHandler(handshakeHandler());
    }

    @Bean
    public DefaultHandshakeHandler handshakeHandler() {

        WebSocketPolicy policy = new WebSocketPolicy(WebSocketBehavior.SERVER);
        policy.setInputBufferSize(8192);
        policy.setIdleTimeout(600000);

        return new DefaultHandshakeHandler(
                new JettyRequestUpgradeStrategy(new WebSocketServerFactory(policy)));
    }

}

下面的示例顯示了與前面示例等價的XML配置：

<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
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers>
        <websocket:mapping path="/echo" handler="echoHandler"/>
        <websocket:handshake-handler ref="handshakeHandler"/>
    </websocket:handlers>

    <bean id="handshakeHandler" class="org.springframework...DefaultHandshakeHandler">
        <constructor-arg ref="upgradeStrategy"/>
    </bean>

    <bean id="upgradeStrategy" class="org.springframework...JettyRequestUpgradeStrategy">
        <constructor-arg ref="serverFactory"/>
    </bean>

    <bean id="serverFactory" class="org.eclipse.jetty...WebSocketServerFactory">
        <constructor-arg>
            <bean class="org.eclipse.jetty...WebSocketPolicy">
                <constructor-arg value="SERVER"/>
                <property name="inputBufferSize" value="8092"/>
                <property name="idleTimeout" value="600000"/>
            </bean>
        </constructor-arg>
    </bean>

</beans>

允許的源

在Spring Framework 4.1.5中，WebSocket和SockJS的預設行為是隻接受相同源的請求，也可以允許所有或指定的源列表。這種檢查主要是為瀏覽器客戶端設計的，沒有什麼可以阻止其他型別的客戶端修改Origin header值（請參閱RFC 6454: Web Origin概念以瞭解更多細節）。

三種可能的行為是：

  • 只允許相同源的請求（預設）：在這種模式下，當啟用SockJS時，Iframe HTTP響應header X-Frame-Options被設定為SAMEORIGIN，並且JSONP傳輸被禁用，因為它不允許檢查請求的源，因此，當啟用該模式時，不支援IE6和IE7。
  • 允許指定的源列表：每個允許的源必須以http://或https://開始，在這種模式下，當啟用SockJS時，IFrame傳輸將被禁用，因此，當啟用該模式時，將不支援IE6到IE9。
  • 允許所有的源：要啟用此模式，你應該提供*作為允許的源值，在這種模式下，所有的傳輸都是可用的。

你可以配置WebSocket和SockJS允許的源，如下面的例子所示：

import org.springframework.web.socket.config.annotation.EnableWebSocket;
import org.springframework.web.socket.config.annotation.WebSocketConfigurer;
import org.springframework.web.socket.config.annotation.WebSocketHandlerRegistry;

@Configuration
@EnableWebSocket
public class WebSocketConfig implements WebSocketConfigurer {

    @Override
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
        registry.addHandler(myHandler(), "/myHandler").setAllowedOrigins("http://mydomain.com");
    }

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

}

下面的示例顯示了與前面示例等價的XML配置：

<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
        http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/websocket
        http://www.springframework.org/schema/websocket/spring-websocket.xsd">

    <websocket:handlers allowed-origins="http://mydomain.com">
        <websocket:mapping path="/myHandler" handler="myHandler" />
    </websocket:handlers>

    <bean id="myHandler" class="org.springframework.samples.MyHandler"/>

</beans>

上一篇：WebSocket介紹

下一篇：SockJS Fallback

相關文章