Getting started with WebSockets Next

本指南说明了你的 Quarkus 应用程序如何利用 Web 套接字创建交互式 Web 应用程序。在本指南中，我们将使用 Web 套接字开发一个非常简单的聊天应用程序，以便接收和向其他已连接用户发送消息。 :iokays-category: quarkus :iokays-path: modules/ROOT/pages/_includes/extension-status.adoc :keywords: Quarkus, 中文文档, 编程技术

该技术被认为是 {extension-status}。 有关可能状态的完整列表，请查看我们的 FAQ entry.

Prerequisites

如要完成本指南，您需要：

  • Roughly 15 minutes

  • An IDE

  • 安装了 JDK 17+，已正确配置 JAVA_HOME

  • Apache Maven ${proposed-maven-version}

  • 如果你想使用 Quarkus CLI, 则可以选择使用

  • 如果你想构建一个本机可执行文件（或如果你使用本机容器构建，则使用 Docker），则可以选择安装 Mandrel 或 GraalVM 以及 configured appropriately

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 的网络层高效配合使用。

What you’ll learn

  • 如何使用 quarkus-websockets-next 扩展

  • 如何声明一个 Web 套接字端点

  • 如何使用 Web 套接字发送和接收消息

  • 如何广播消息给所有已连接用户

  • 如何得知新的连接和断开连接

  • 如何在 Web 套接字 URL 中使用 path parameters

Architecture

在本指南中，我们创建一个简单的聊天应用程序，使用 Web 套接字接收和向其他已连接用户发送消息。

websockets next architecture

Solution

我们建议你按照后续章节中的说明，逐步创建应用程序。但是，你可以直接跳到已完成的示例。

克隆 Git 存储库： git clone $${quickstarts-base-url}.git，或下载 $${quickstarts-base-url}/archive/main.zip[存档]。

解决方案位于 websockets-next-quickstart directory 。

Creating the Maven project

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

CLI
quarkus create app {create-app-group-id}:{create-app-artifact-id} \
    --no-code
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。 有关如何安装和使用 Quarkus CLI 的详细信息，请参见 Quarkus CLI 指南。

Maven
mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId={create-app-group-id} \
    -DprojectArtifactId={create-app-artifact-id} \
    -DnoCode
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

适用于 Windows 用户：

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

  • 如果使用 Powershell，将 -D 参数用双引号引起来，例如 "-DprojectArtifactId={create-app-artifact-id}"

该命令生成项目（不含任何类）并导入`websockets-next`扩展。

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

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

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

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-websockets-next</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-websockets-next")

Declaring a WebSocket endpoint

我们的应用程序包含处理 WebSocket 的单个类。在`src/main/java`目录中创建class 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 表示与客户端连接的_session scoped bean_。它允许以编程方式发送消息和检索路径参数。
3 当新客户端连接时，调用此方法。`broadcast = true`属性表示应该将返回的消息发送给所有已连接的客户端。
4 当客户端断开连接时，调用该方法。该方法使用`WebSocketConnection`向所有剩余连接的客户端广播消息。
5 当客户端发送消息时，调用此方法。`broadcast = true`属性表示应该将返回的消息发送给所有已连接的客户端。这里，我们只返回接收到的（文本）消息。

正如您所见，Quarkus 使用注释处理 WebSocket 生命周期和消息处理。它还使用 JSON 自动序列化和反序列化消息。

A slick web frontend

所有聊天应用程序都需要一个 _nice_UI，嗯，这个可能不太好，但却能完成工作。Quarkus 会自动提供 `META-INF/resources`目录中包含的静态资源。创建 `src/main/resources/META-INF/resources`目录并将此 index.html文件复制到其中。

Run the application

现在，让我们看看应用程序在实际应用中的情况。使用以下命令运行它：

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

然后在 2 个浏览器窗口中打开 [role="bare"][role="bare"]http://localhost:8080/：

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

  2. Click on connect

  3. Send and receive messages

websockets next chat

和往常一样，可以使用以下命令打包应用程序：

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

Conclusion

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