Quarkus WebSocket 入门实践

前期准备&环境说明

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

安装最新的插件

quarkus ext add websockets-next

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

开发客户端

目标: 连接到指定的ws服务器

流程步骤:

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

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);
    }
}

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

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

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服务器

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

@Singleton
public class Startup {

    @Inject
    WsClientRunner runner;

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

重点说明

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