Getting started with WebSockets Next

本指南说明了你的 Quarkus 应用程序如何利用 Web 套接字创建交互式 Web 应用程序。在本指南中，我们将使用 Web 套接字开发一个非常简单的聊天应用程序，以便接收和向其他已连接用户发送消息。 Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/extension-status.adoc[]

Prerequisites

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/prerequisites.adoc[]

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-clone-url}，或下载 {quickstarts-archive-url}[存档]。

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

Creating the Maven project

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

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/devtools/create-app.adoc[]

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

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

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/devtools/extension-add.adoc[]

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

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`。
<1>  表示与客户端连接的_session scoped bean_。它允许以编程方式发送消息和检索路径参数。
<1>  当新客户端连接时，调用此方法。`broadcast = true`属性表示应该将返回的消息发送给所有已连接的客户端。
<1>  当客户端断开连接时，调用该方法。该方法使用`WebSocketConnection`向所有剩余连接的客户端广播消息。
<1>  当客户端发送消息时，调用此方法。`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

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

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/devtools/dev.adoc[]

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

在顶部文本区域中输入一个名称（使用 2 个不同的名称）。
Click on connect
Send and receive messages

websockets next chat

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

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/devtools/build.adoc[]

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

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

Unresolved directive in websockets-next-tutorial.adoc - include::{includes}/devtools/build-native.adoc[]

Conclusion

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