Quarkus WebSocket 入门实践

前期准备&环境说明

JDK 21 (大于17就行)
Quarkus Cli 3.29.3
quarkus maven工程

安装最新的插件

bash 复制代码

quarkus ext add websockets-next

为什么不用 quarkus-websockets? quarkus.net.cn/guides/webs...

开发客户端

目标 : 连接到指定的ws服务器 流程步骤:

定义客户端端点（@WebSocketClient） Quarkus 的 WebSocket Next 客户端接收消息需要一个 @WebSocketClient 注解的类。

java 复制代码

package org.acme;

import io.quarkus.websockets.next.OnTextMessage;
import io.quarkus.websockets.next.WebSocketClient;
import io.quarkus.websockets.next.WebSocketClientConnection;
import jakarta.inject.Inject;

@WebSocketClient(path = "/echo") // 远程 ws 的路径（示例）
public class MyWsClient {

    @Inject
    WebSocketClientConnection connection;

    @OnTextMessage
    void onMessage(String msg) {
        System.out.println(">>> 收到服务器消息: " + msg);
    }
}

markdown 复制代码

只要远程 ws 服务器在 `/echo` 路径上，这个端点就能接收消息。

使用 WebSocketConnector 主动连接远程 ws 需要一个业务类主动调用 connector.connect()。

java 复制代码

package org.acme;

import io.quarkus.websockets.next.WebSocketConnector;
import io.quarkus.websockets.next.WebSocketClientConnection;
import jakarta.inject.Inject;
import jakarta.inject.Singleton;

import java.net.URI;

@Singleton
public class WsClientRunner {

    @Inject
    WebSocketConnector<MyWsClient> connector;

    public void connect() {
        URI uri = URI.create("ws://localhost:9000"); // 外部 ws 服务

        WebSocketClientConnection conn = connector
                .baseUri(uri)      // ws://localhost:9000
                .connectAndAwait(); // 阻塞直到连接成功

        System.out.println(">>> 已连接到外部 WebSocket 服务");

        // 主动发送一条消息
        conn.sendTextAndAwait("Hello WS Server!");
    }
}

发送消息 / 接收消息 根据业务逻辑进行主动或自动连接到WS服务器

java 复制代码

import io.quarkus.runtime.StartupEvent;
import jakarta.enterprise.event.Observes;

@Singleton
public class Startup {

    @Inject
    WsClientRunner runner;

    void onStart(@Observes StartupEvent ev) {
        runner.connect();
    }
}

📌 重点说明

需求	对应用法
主动连接外部 ws 服务	WebSocketConnector
接收消息	在 `@WebSocketClient` 中写 `@OnTextMessage`
发送消息	connection.sendText() / sendTextAndAwait()
配路径参数	`.pathParam("name", "abc")`
连接多个 ws	使用 `Instance<WebSocketConnector<T>>`

Quarkus WebSockets Next 客户端本质上是全异步、自动管理生命周期的 WebSocket 客户端，比传统 Java WebSocket API 好用太多。