【经验分享】SpringBoot集成Websocket开发之使用由 Jakarta EE 规范提供的 API开发

在 Spring Boot 中整合、使用 WebSocket

WebSocket 是一种基于 TCP 协议的全双工通信协议，它允许客户端和服务器之间建立持久的、双向的通信连接。相比传统的 HTTP 请求 - 响应模式，WebSocket 提供了实时、低延迟的数据传输能力。通过 WebSocket，客户端和服务器可以在任意时间点互相发送消息，实现实时更新和即时通信的功能。WebSocket 协议经过了多个浏览器和服务器的支持，成为了现代 Web 应用中常用的通信协议之一。它广泛应用于聊天应用、实时数据更新、多人游戏等场景，为 Web 应用提供了更好的用户体验和更高效的数据传输方式。

本文将会指导你如何在 Spring Boot 中整合、使用 WebSocket，以及如何在 @ServerEndpoint 类中注入其他 Bean 依赖。

在 Spring Boot 中使用 WebSocket 有 2 种方式。第 1 种是使用由 Jakarta EE 规范提供的 Api，也就是 jakarta.websocket 包下的接口。第 2 种是使用 spring 提供的支持，也就是 spring-websocket 模块。前者是一种独立于框架的技术规范，而后者是 Spring 生态系统的一部分，可以与其他 Spring 模块（如 Spring MVC、Spring Security）无缝集成，共享其配置和功能。

2 种方式各有优劣，你可以按需选择。本文将使用第 1 种方式，也就是使用 jakarta.websocket 来开发 WebSocket 应用。

软件版本：

Spring Boot：3.1.3

在 Spring Boot 中整合 WebSocket

添加依赖

在 pom.xml 中添加 spring-boot-starter-websocket 依赖。

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-websocket</artifactId>
</dependency>

开发 ServerEndpoint 端点

服务端 WebSocket 端点的开发也有 2 种方式。第 1 种是实现规范所提供的各种接口，通过接口定义的回调方法来处理新的连接、客户端消息、连接断开等等事件。另一种方式是使用注解，类似于 Spring 中的 Controller，通过在方法上使用不同的注解来监听不同的 WebSocket 事件，灵活性比较高，推荐使用。

我们打算创建一个 echo 端点，该端点会处理客户端的连接、断开、消息事件。在收到消息后，我们会在消息前面加上服务器时间戳和 Hello 前缀，原样写回给客户端。如果客户端发送的消息为 bye，则服务器会主动断开与客户端的连接。

package cn.springdoc.demo.channel;import java.io.IOException;
import java.time.Instant;import org.slf4j.Logger;
import org.slf4j.LoggerFactory;import jakarta.websocket.CloseReason;
import jakarta.websocket.EndpointConfig;
import jakarta.websocket.OnClose;
import jakarta.websocket.OnError;
import jakarta.websocket.OnMessage;
import jakarta.websocket.OnOpen;
import jakarta.websocket.Session;
import jakarta.websocket.server.ServerEndpoint;// 使用 @ServerEndpoint 注解表示此类是一个 WebSocket 端点
// 通过 value 注解，指定 websocket 的路径
@ServerEndpoint(value = "/channel/echo")
public class EchoChannel {private static final Logger LOGGER = LoggerFactory.getLogger(EchoChannel.class);private Session session;// 收到消息@OnMessagepublic void onMessage(String message) throws IOException{LOGGER.info("[websocket] 收到消息：id={}，message={}", this.session.getId(), message);if (message.equalsIgnoreCase("bye")) {// 由服务器主动关闭连接。状态码为 NORMAL_CLOSURE（正常关闭）。this.session.close(new CloseReason(CloseReason.CloseCodes.NORMAL_CLOSURE, "Bye"));;return;}this.session.getAsyncRemote().sendText("["+ Instant.now().toEpochMilli() +"] Hello " + message);}// 连接打开@OnOpenpublic void onOpen(Session session, EndpointConfig endpointConfig){// 保存 session 到对象this.session = session;LOGGER.info("[websocket] 新的连接：id={}", this.session.getId());}// 连接关闭@OnClosepublic void onClose(CloseReason closeReason){LOGGER.info("[websocket] 连接断开：id={}，reason={}", this.session.getId(),closeReason);}// 连接异常@OnErrorpublic void onError(Throwable throwable) throws IOException {LOGGER.info("[websocket] 连接异常：id={}，throwable={}", this.session.getId(), throwable.getMessage());// 关闭连接。状态码为 UNEXPECTED_CONDITION（意料之外的异常）this.session.close(new CloseReason(CloseReason.CloseCodes.UNEXPECTED_CONDITION, throwable.getMessage()));}
}

首先，使用 @ServerEndpoint 注解表示此类是一个 WebSocket 端点，value 属性是必须的，用于设置路由。它还有其他的一些可选属性可以用于自定义子协议、消息编码器、消息解码器、握手处理器等等，篇幅原因这里不展开。

@OnMessage

@OnMessage 注解用于监听客户端消息事件，它只有一个属性 long maxMessageSize() default -1; 用于限制客户端消息的大小，如果小于等于 0 则表示不限制。当客户端消息体积超过这个阈值，那么服务器就会主动断开连接，状态码为：1009。方法的参数可以是基本的 String / byte[] 或者是 Reader / InputStream，分别表示 WebSocket 中的文本和二进制消息。也可以是自定义的 Java 对象，但是需要在 @ServerEndpoint 中配置对象的解码器（jakarta.websocket.Decoder）。对于内容较长的消息，支持分批发送，可以在消息参数后面定义一个布尔类型的 boolean last参数，如果该值为 true 则表示此消息是批次消息中的最后一条。

@OnMessage
public void onMessage(String message, boolean last) throws IOException{if (last) {// 这是批量消息的最后一条}
}

@OnOpen

@OnOpen 方法用于监听客户端的连接事件，它没有任何属性。可以作为方法参数的对象有很多，Session 对象是必须的，表示当前连接对象，我们可以通过此对象来执行发送消息、断开连接等操作。WebSocket 的连接 URL，类似于 Http 的 URL，也可以传递查询参数、path 参数。通常用于传递认证、鉴权用的 Token 或其他信息。

要获取查询参数，我们可以通过 Session 的 getRequestParameterMap(); 获取。

Map<String, List<String>> query = session.getRequestParameterMap();

要获取 path 参数，首先要在 @ServerEndpoint 中定义 path 参数，类似于 Spring Mvc 的 path 参数定义。例如： @ServerEndpoint(value = "/channel/echo/{id}")。那么我们可以在 @OnOpen 方法中使用 @PathParam 注解接收，如下：

@ServerEndpoint(value = "/channel/echo/{id}")...@OnOpen
public void onOpen(Session session, @PathParam("id") Long id, EndpointConfig endpointConfig){....
}

示例中的最后一个参数 EndpointConfig ，它是可选，用于获取全局的一些配置。在本文中未用到。

@OnClose

@OnClose 用于处理连接断开事件，参数中可以指定一个 CloseReason 对象，它封装了断开连接的状态码、原因信息。

@OnError

@OnError 用于处理异常事件，该方法必须要有一个 Throwable 类型的参数，表示发生的异常。否则应用会启用失败：

Caused by: jakarta.websocket.DeploymentException: No Throwable parameter was present on the method [onError] of class [cn.springdoc.demo.channel.EchoChannel] that was annotated with OnErrorat org.apache.tomcat.websocket.pojo.PojoMethodMapping.getPathParams(PojoMethodMapping.java:311) ~[tomcat-embed-websocket-10.1.12.jar:10.1.12]at org.apache.tomcat.websocket.pojo.PojoMethodMapping.<init>(PojoMethodMapping.java:194) ~[tomcat-embed-websocket-10.1.12.jar:10.1.12]at org.apache.tomcat.websocket.server.WsServerContainer.addEndpoint(WsServerContainer.java:130) ~[tomcat-embed-websocket-10.1.12.jar:10.1.12]at org.apache.tomcat.websocket.server.WsServerContainer.addEndpoint(WsServerContainer.java:240) ~[tomcat-embed-websocket-10.1.12.jar:10.1.12]at org.apache.tomcat.websocket.server.WsServerContainer.addEndpoint(WsServerContainer.java:198) ~[tomcat-embed-websocket-10.1.12.jar:10.1.12]at org.springframework.web.socket.server.standard.ServerEndpointExporter.registerEndpoint(ServerEndpointExporter.java:156) ~[spring-websocket-6.0.11.jar:6.0.11]... 12 common frames omitted

所有事件方法，都支持使用 Session 作为参数，表示当前连接参数。但是为了更加方便，我们在 @OnOpen 事件中直接把 Session 存储到了当前对象中，可以在任意方法中使用 this 访问。服务器会为每个连接创建一个端点对象，所以这是线程安全的。

上面还提到了一个 “连接关闭状态码”，WebSocket 协议定义了一系列状态码来表示连接断开的原因，这些状态码定义在了 CloseReason.CloseCodes 枚举中。

配置 ServerEndpointExporter

定义好端点后，需要在配置类中通过定义 ServerEndpointExporter Bean 进行注册。

package cn.springdoc.demo.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.socket.server.standard.ServerEndpointExporter;import cn.springdoc.demo.channel.EchoChannel;@Configuration
public class WebSocketConfiguration {@Bean  public ServerEndpointExporter serverEndpointExporter (){ServerEndpointExporter exporter = new ServerEndpointExporter();// 手动注册 WebSocket 端点exporter.setAnnotatedEndpointClasses(EchoChannel.class);return exporter;}  
}

你也可以在 WebSocket 端点上添加 @Component 注解，使用 Spring 自动扫描，这样的话不需要手动调用 setAnnotatedEndpointClasses 方法进行注册。

说明：

另外一点就是服务端如何发送消息给客户端，服务端发送消息必须通过上面说的 Session 类，通常是在@OnOpen 方法中，当连接成功后把 session 存入 Map 的 value，key 是与 session 对应的用户标识，当要发送的时候通过 key 获得 session 再发送，这里可以通过 session.getBasicRemote () .sendText ( ) 来对客户端发送消息。

测试

在项目的 src/main/resources 目录下创建一个 public 文件夹，再在此文件夹中新建一个 index.html 文件，作为 WebSocket 客户端。内容如下：

Spring Boot 默认会把 public 目录下的 index.html 作为应用主页。

<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"><title>WebSocket</title>
</head>
<body><script type="text/javascript">let websocket = new WebSocket("ws://localhost:8080/channel/echo");// 连接断开websocket.onclose = e => {console.log(`连接关闭: code=${e.code}, reason=${e.reason}`)}// 收到消息websocket.onmessage = e => {console.log(`收到消息：${e.data}`);}// 异常websocket.onerror = e => {console.log("连接异常")console.error(e)}// 连接打开websocket.onopen = e => {console.log("连接打开");// 创建连接后，往服务器连续写入3条消息websocket.send("springdoc.cn");websocket.send("springdoc.cn");websocket.send("springdoc.cn");// 最后发送 bye，由服务器断开连接websocket.send("bye");// 也可以由客户端主动断开// websocket.close();}</script>
</body>
</html>

内容很简单，网页加载后运行 Javascript 代码。立即创建与 ws://localhost:8080/channel/echo 的 WebSocket 连接对象，通过注册对象的各种监听方法来处理事件。

在连接就绪后，也就是在 onopen 方法中往服务器端点发送了 3 条消息。按照逻辑，服务端也会回复 3 条消息，这会触发 onmessage 事件，把消息内容输出到控制台。最后，发送 bye，服务器收到消息后会主动断开连接，这就会触发 onclose 事件，把 “连接关闭状态码” 和原因输出到控制台。

其实你可以直接把这段 Javascript 代码复制到任意支持 WebSocket 的浏览器的控制台执行，WebSocket 没有跨域的说法！

启动应用，打开浏览器（先打开控制台），然后访问 http://localhost:8080/，查看控制台输出的日志：

连接打开
收到消息：[1694505275009] Hello springdoc.cn
收到消息：[1694505275012] Hello springdoc.cn
收到消息：[1694505275014] Hello springdoc.cn
连接关闭: code=1000, reason=Bye

再看看服务端控制台日志：

cn.springdoc.demo.channel.EchoChannel    : [websocket] 新的连接：id=0
cn.springdoc.demo.channel.EchoChannel    : [websocket] 收到消息：id=0，message=springdoc.cn
cn.springdoc.demo.channel.EchoChannel    : [websocket] 收到消息：id=0，message=springdoc.cn
cn.springdoc.demo.channel.EchoChannel    : [websocket] 收到消息：id=0，message=springdoc.cn
cn.springdoc.demo.channel.EchoChannel    : [websocket] 收到消息：id=0，message=bye
cn.springdoc.demo.channel.EchoChannel    : [websocket] 连接断开：id=0，reason=CloseReason: code [1000], reason [Bye]

没有任何问题，一切按照我们预定义的逻辑在运行。客户端发送 3 条消息，服务器响应 3 条消息，最后断开连接。客户端、服务器相应的事件方法都成功执行。

服务端日志中的 sessionId（id=0），是通过 Session 的 String getId(); 方法获取的。服务器会为每个连接分配一个不同的 id 值，不同服务器生成的 id 类型不一样。 Tomcat 使用从 0 开始的自增值（本例），Undertow 使用的是类似于 UUID 的 32 位长度的字符串。

在端点中注入 Bean

往往我们需要在端点中使用其他 Spring 管理的 Bean 来完成业务，例如认证、鉴权、保存消息。。。等等。

假如我们有一个 UserService 服务类，内容如下：

package cn.springdoc.demo.service;import org.springframework.stereotype.Service;@Service
public class UserService {public void foo() {}// ....
}

我们现在要在端点中注入使用它，很多人会直接在端点类上使用 @Component 注解，然后注入：

@ServerEndpoint(value = "/channel/echo")
@Component  // 注册为 Spring 组件
public class EchoChannel {@Autowired // 注入需要的 Beanprivate UserService userService;// ...@OnOpenpublic void onOpen(Session session, EndpointConfig endpointConfig){this.session = session;// 在业务中使用this.userService.foo();}
}

服务可以正常启动，看似一切都没问题！可是当你在事件方法中使用这 Bean 的时候就会导致 NullPointerException 异常。

java.lang.NullPointerException: Cannot invoke "cn.springdoc.demo.service.UserService.foo()" because "this.userService" is nullat cn.springdoc.demo.channel.EchoChannel.onOpen(EchoChannel.java:54)at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)at java.base/java.lang.reflect.Method.invoke(Method.java:568)at org.apache.tomcat.websocket.pojo.PojoEndpointBase.doOnOpen(PojoEndpointBase.java:67)at org.apache.tomcat.websocket.pojo.PojoEndpointServer.onOpen(PojoEndpointServer.java:46)at org.apache.tomcat.websocket.server.WsHttpUpgradeHandler.init(WsHttpUpgradeHandler.java:131)at org.apache.coyote.AbstractProtocol$ConnectionHandler.process(AbstractProtocol.java:936)at org.apache.tomcat.util.net.NioEndpoint$SocketProcessor.doRun(NioEndpoint.java:1740)at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:52)at org.apache.tomcat.util.threads.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1191)at org.apache.tomcat.util.threads.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:659)at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61)at java.base/java.lang.Thread.run(Thread.java:833)

原因：运行时的 WebSocket 连接对象，也就是端点实例，是由服务器创建，而不是 Spring，所以不能使用自动装配。上文也提到过 “服务器会为每个连接创建一个端点实例对象”。

知道了原因后，解决办法也很简单，我们可以使用 Spring 的 ApplicationContextAware 接口，在应用启动时获取到 ApplicationContext 并且保存在全局静态变量中。

服务器每次创建连接的时候，我们就在 @OnOpen 事件方法中从 ApplicationContext 获取到需要 Bean 来初始化端点对象。

@ServerEndpoint(value = "/channel/echo")
@Component  // 由 spring 扫描管理
public class EchoChannel implementsApplicationContextAware { // 实现 ApplicationContextAware 接口， Spring 会在运行时注入 ApplicationContextprivate static final Logger LOGGER = LoggerFactory.getLogger(EchoChannel.class);// 全局静态变量，保存 ApplicationContextprivate static ApplicationContext applicationContext;private Session session;// 声明需要的 Beanprivate UserService userService;// 保存 Spring 注入的 ApplicationContext 到静态变量@Overridepublic void setApplicationContext(ApplicationContext applicationContext) throws BeansException {EchoChannel.applicationContext = applicationContext;}@OnOpenpublic void onOpen(Session session, EndpointConfig endpointConfig){// 保存 session 到对象this.session = session;// 连接创建的时候，从 ApplicationContext 获取到 Bean 进行初始化this.userService = EchoChannel.applicationContext.getBean(UserService.class);// 在业务中使用this.userService.foo();LOGGER.info("[websocket] 新的连接：id={}", this.session.getId());}// ....
}