WebSocket API

請參閱 Reactive stack 中的對等項目

Spring Framework 提供 WebSocket API，您可以使用它來撰寫處理 WebSocket 訊息的用戶端和伺服器端應用程式。

WebSocketHandler

請參閱 Reactive stack 中的對等項目

建立 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 程式化組態和 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 的協助下，將 WebSocketHandler 整合到其他 HTTP 伺服環境中相對簡單。

當直接與間接使用 WebSocketHandler API 時，例如透過 STOMP 訊息傳遞，應用程式必須同步訊息傳送，因為基礎標準 WebSocket 工作階段 (JSR-356) 不允許並行傳送。一種選項是使用 ConcurrentWebSocketSessionDecorator 包裝 WebSocketSession。

WebSocket 交握

請參閱 Reactive stack 中的對等項目

自訂初始 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 執行階段，有一些特殊的考量。

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>

然後，您可以依名稱選擇性地啟用 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>

組態伺服器

請參閱 Reactive stack 中的對等項目

您可以組態基礎 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)
	}
}
當使用 STOMP over WebSocket 時，您也需要組態 STOMP WebSocket 傳輸 屬性。

允許的來源

請參閱 Reactive stack 中的對等項目

從 Spring Framework 4.1.5 開始，WebSocket 和 SockJS 的預設行為是僅接受同源請求。也可以允許所有來源或指定的來源清單。此檢查主要針對瀏覽器用戶端而設計。沒有任何東西可以阻止其他類型的用戶端修改 Origin 標頭值 (如需更多詳細資訊，請參閱 RFC 6454：Web 來源概念)。

三種可能的行為是

  • 僅允許同源請求 (預設)：在此模式下，當啟用 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>