WebSocket Next 入门
本指南介绍如何使用 Quarkus 应用程序利用 WebSockets 创建交互式 Web 应用程序。在本指南中,我们将开发一个非常简单的聊天应用程序,使用 WebSockets 接收消息并将其发送给其他连接的用户。
先决条件
要完成本指南,您需要
-
大约 15 分钟
-
一个 IDE
-
已安装 JDK 17+ 并正确配置了
JAVA_HOME
-
Apache Maven 3.9.9
-
如果您想使用它,可以选择 Quarkus CLI
-
如果您想构建本机可执行文件(或者如果您使用本机容器构建,则为 Docker),可以选择安装 Mandrel 或 GraalVM 并进行适当的配置
Quarkus WebSockets vs. Quarkus WebSockets Next
本指南使用 quarkus-websockets-next
扩展。此扩展是 WebSocket API 的一种新的实现,它比原始的 quarkus-websockets
扩展更高效、更易于使用。原始的 quarkus-websockets
扩展仍然可用,并将继续得到支持。
与 quarkus-websockets
不同,quarkus-web-socket-next
不实现 Jakarta WebSocket。相反,它提供了一个更简单、更现代的 API,更易于使用。它还被设计为可以高效地与 Quarkus 的反应式编程模型和 Quarkus 的网络层一起工作。
您将学到什么
-
如何使用
quarkus-websockets-next
扩展 -
如何声明 WebSocket 端点
-
如何使用 WebSockets 发送和接收消息
-
如何将消息广播给所有连接的用户
-
如何接收新连接和断开连接的通知
-
如何在 WebSocket URL 中使用路径参数
解决方案
我们建议您按照以下部分的说明逐步创建应用程序。但是,您可以直接跳到完成的示例。
克隆 Git 存储库:git clone https://github.com/quarkusio/quarkus-quickstarts.git
,或者下载一个存档。
解决方案位于 websockets-next-quickstart
目录中。
创建 Maven 项目
首先,我们需要一个新项目。使用以下命令创建一个新项目
对于 Windows 用户
-
如果使用 cmd,(不要使用反斜杠
\
并将所有内容放在同一行上) -
如果使用 Powershell,请将
-D
参数用双引号括起来,例如"-DprojectArtifactId=websockets-next-quickstart"
此命令生成项目(没有任何类)并导入 websockets-next
扩展。
如果您已经配置了 Quarkus 项目,则可以通过在项目基本目录中运行以下命令将 websockets-next
扩展添加到您的项目中
quarkus extension add websockets-next
./mvnw quarkus:add-extension -Dextensions='websockets-next'
./gradlew addExtension --extensions='websockets-next'
这会将以下内容添加到您的构建文件中
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-websockets-next</artifactId>
</dependency>
implementation("io.quarkus:quarkus-websockets-next")
声明 WebSocket 端点
我们的应用程序包含一个处理 WebSockets 的类。在 src/main/java
目录中创建 org.acme.websockets.ChatWebSocket
类。将以下内容复制到创建的文件中
package org.acme.websockets;
import io.quarkus.websockets.next.OnClose;
import io.quarkus.websockets.next.OnOpen;
import io.quarkus.websockets.next.OnTextMessage;
import io.quarkus.websockets.next.WebSocket;
import io.quarkus.websockets.next.WebSocketConnection;
import jakarta.inject.Inject;
@WebSocket(path = "/chat/{username}") (1)
public class ChatWebSocket {
// Declare the type of messages that can be sent and received
public enum MessageType {USER_JOINED, USER_LEFT, CHAT_MESSAGE}
public record ChatMessage(MessageType type, String from, String message) {
}
@Inject
WebSocketConnection connection; (2)
@OnOpen(broadcast = true) (3)
public ChatMessage onOpen() {
return new ChatMessage(MessageType.USER_JOINED, connection.pathParam("username"), null);
}
@OnClose (4)
public void onClose() {
ChatMessage departure = new ChatMessage(MessageType.USER_LEFT, connection.pathParam("username"), null);
connection.broadcast().sendTextAndAwait(departure);
}
@OnTextMessage(broadcast = true) (5)
public ChatMessage onMessage(ChatMessage message) {
return message;
}
}
1 | 声明 WebSocket 端点并配置路径。请注意,该路径可以包含路径参数:username 。 |
2 | 一个会话作用域的 bean,表示与客户端的连接。它允许以编程方式发送消息并检索路径参数。 |
3 | 当新客户端连接时调用此方法。broadcast = true 属性指示应将返回的消息发送给所有连接的客户端。 |
4 | 当客户端断开连接时调用此方法。该方法使用 WebSocketConnection 将消息广播给所有剩余的连接客户端。 |
5 | 当客户端发送消息时调用此方法。broadcast = true 属性指示应将返回的消息发送给所有连接的客户端。在这里,我们只返回接收到的(文本)消息。 |
如您所见,Quarkus 使用注解处理 WebSocket 生命周期和消息处理。它还自动使用 JSON 序列化和反序列化消息。
一个漂亮的 Web 前端
所有聊天应用程序都需要一个漂亮的 UI,嗯,这个可能不是那么漂亮,但能完成工作。Quarkus 自动提供 META-INF/resources
目录中包含的静态资源。创建 src/main/resources/META-INF/resources
目录并将此 index.html 文件复制到其中。
运行应用程序
现在,让我们看看我们的应用程序的运行情况。使用以下命令运行它
quarkus dev
./mvnw quarkus:dev
./gradlew --console=plain quarkusDev
然后打开您的 2 个浏览器窗口访问 https://:8080/
-
在顶部文本区域中输入一个名称(使用 2 个不同的名称)。
-
点击连接
-
发送和接收消息
与往常一样,可以使用以下命令打包应用程序
quarkus build
./mvnw install
./gradlew build
并使用 java -jar target/quarkus-app/quarkus-run.jar
执行。
您也可以使用以下命令构建本机可执行文件
quarkus build --native
./mvnw install -Dnative
./gradlew build -Dquarkus.native.enabled=true
结论
这个简短的入门指南向您展示了如何使用 quarkus-websockets-next
扩展创建一个简单的聊天应用程序。在专用参考指南上了解有关此扩展的更多信息。