编辑此页面

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 中使用路径参数

架构

在本指南中,我们创建了一个简单的聊天应用程序,使用 WebSockets 接收消息并将其发送给其他连接的用户。

Architecture

解决方案

我们建议您按照以下部分的说明逐步创建应用程序。但是,您可以直接跳到完成的示例。

克隆 Git 存储库:git clone https://github.com/quarkusio/quarkus-quickstarts.git,或者下载一个存档

解决方案位于 websockets-next-quickstart 目录中。

创建 Maven 项目

首先,我们需要一个新项目。使用以下命令创建一个新项目

CLI
quarkus create app org.acme:websockets-next-quickstart \
    --extension='websockets-next' \
    --no-code
cd websockets-next-quickstart

要创建 Gradle 项目,请添加 --gradle--gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息,请参阅 Quarkus CLI 指南。

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.24.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=websockets-next-quickstart \
    -Dextensions='websockets-next' \
    -DnoCode
cd websockets-next-quickstart

要创建 Gradle 项目,请添加 -DbuildTool=gradle-DbuildTool=gradle-kotlin-dsl 选项。

对于 Windows 用户

  • 如果使用 cmd,(不要使用反斜杠 \ 并将所有内容放在同一行上)

  • 如果使用 Powershell,请将 -D 参数用双引号括起来,例如 "-DprojectArtifactId=websockets-next-quickstart"

此命令生成项目(没有任何类)并导入 websockets-next 扩展。

如果您已经配置了 Quarkus 项目,则可以通过在项目基本目录中运行以下命令将 websockets-next 扩展添加到您的项目中

CLI
quarkus extension add websockets-next
Maven
./mvnw quarkus:add-extension -Dextensions='websockets-next'
Gradle
./gradlew addExtension --extensions='websockets-next'

这会将以下内容添加到您的构建文件中

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-websockets-next</artifactId>
</dependency>
build.gradle
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 文件复制到其中。

运行应用程序

现在,让我们看看我们的应用程序的运行情况。使用以下命令运行它

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

然后打开您的 2 个浏览器窗口访问 https://:8080/

  1. 在顶部文本区域中输入一个名称(使用 2 个不同的名称)。

  2. 点击连接

  3. 发送和接收消息

Application

与往常一样,可以使用以下命令打包应用程序

CLI
quarkus build
Maven
./mvnw install
Gradle
./gradlew build

并使用 java -jar target/quarkus-app/quarkus-run.jar 执行。

您也可以使用以下命令构建本机可执行文件

CLI
quarkus build --native
Maven
./mvnw install -Dnative
Gradle
./gradlew build -Dquarkus.native.enabled=true

结论

这个简短的入门指南向您展示了如何使用 quarkus-websockets-next 扩展创建一个简单的聊天应用程序。在专用参考指南上了解有关此扩展的更多信息。

相关内容