WebSocket API

Spring Framework 提供了一個 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 程式設計式配置和 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 棧中的對應內容

自定義初始 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 支援在 WebSocket API 2.1+ 執行時透過標準 RequestUpgradeStrategy 實現來解決。

一個次要的考慮是，具有 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 棧中的對應內容

你可以配置底層 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 傳輸屬性。

允許的來源

參見 Reactive 棧中的對應內容

從 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>