WebSocket API

檢視 Reactive 棧中的對應內容

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

WebSocketHandler

檢視 Reactive 棧中的對應內容

建立一個 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 handler 對映到特定 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 服務環境中相對簡單。

當直接或間接（例如，透過 STOMP 訊息傳遞）使用 WebSocketHandler API 時，應用程式必須同步訊息傳送，因為底層標準 WebSocket session (JSR-356) 不允許併發傳送。一種選擇是使用 ConcurrentWebSocketSessionDecorator 包裝 WebSocketSession。

WebSocket 握手

檢視 Reactive 棧中的對應內容

自定義初始 HTTP WebSocket 握手請求的最簡單方法是使用 HandshakeInterceptor，它公開了握手“之前”和“之後”的方法。您可以使用此類攔截器來阻止握手或使任何屬性可用於 WebSocketSession。以下示例使用內建攔截器將 HTTP session 屬性傳遞給 WebSocket session

  • 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 session，這表示伺服器錯誤。

部署

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 fragments（以及 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 fragments，例如 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: The Web Origin Concept）。

三種可能的行為是

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