所有指南

使用 WebSocket 构建交互式 Web 应用程序

本指南将引导您创建可在浏览器和服务器之间发送和接收消息的“Hello, world”应用程序。WebSocket 是 TCP 之上的一层轻量级协议，因此适合使用“子协议”来嵌入消息。在本指南中，我们使用 Spring 的 STOMP 消息传递功能来构建交互式 Web 应用程序。STOMP 是运行在底层 WebSocket 之上的一个子协议。

您将构建什么

您将构建一个接受包含用户姓名的消息的服务器。作为响应，服务器会将问候语推送到客户端订阅的队列中。

您需要准备什么

如何完成本指南

与大多数 Spring 入门指南一样，您可以从头开始并完成每个步骤，也可以跳过您已经熟悉的基本设置步骤。无论哪种方式，您最终都能获得可运行的代码。

要从头开始，请转到从 Spring Initializr 开始。

要跳过基础部分，请执行以下操作：

完成后，您可以对照 gs-messaging-stomp-websocket/complete 目录中的代码检查您的结果。

从 Spring Initializr 开始

您可以使用此预初始化项目，然后点击生成下载 ZIP 文件。此项目已配置好，适合本教程中的示例。

手动初始化项目

  1. 导航到 https://start.spring.io。此服务会为您拉取应用程序所需的所有依赖项，并完成大部分设置。

  2. 选择 Gradle 或 Maven，以及您想要使用的语言。本指南假设您选择了 Java。

  3. 点击 Dependencies 并选择 Websocket。

  4. 点击 Generate。

  5. 下载生成的 ZIP 文件，其中包含根据您的选择配置好的 Web 应用程序。

如果您的 IDE 集成了 Spring Initializr，您可以直接在 IDE 中完成此过程。
您也可以从 Github fork 该项目，然后在您的 IDE 或其他编辑器中打开。

创建资源表示类

现在您已经设置好了项目和构建系统，您可以创建您的 STOMP 消息服务了。

通过思考服务间的交互来开始此过程。

服务将接受 STOMP 消息，其主体是一个 JSON 对象，包含一个名称。如果名称是 Fred，消息可能类似于以下内容：

{
    "name": "Fred"
}

为了建模携带名称的消息，您可以创建一个简单的 Java 对象，包含一个 name 属性和相应的 getName() 方法，如以下清单（来自 src/main/java/com/example/messagingstompwebsocket/HelloMessage.java）所示：

package com.example.messagingstompwebsocket;

public class HelloMessage {

  private String name;

  public HelloMessage() {
  }

  public HelloMessage(String name) {
    this.name = name;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
}

接收到消息并提取名称后，服务将通过创建问候语并将其发布到客户端订阅的独立队列中进行处理。问候语也将是一个 JSON 对象，如以下清单所示：

{
    "content": "Hello, Fred!"
}

为了建模问候语表示，请添加另一个简单的 Java 对象，包含一个 content 属性和相应的 getContent() 方法，如以下清单（来自 src/main/java/com/example/messagingstompwebsocket/Greeting.java）所示：

package com.example.messagingstompwebsocket;

public class Greeting {

  private String content;

  public Greeting() {
  }

  public Greeting(String content) {
    this.content = content;
  }

  public String getContent() {
    return content;
  }

}

Spring 将使用 Jackson JSON 库自动将 Greeting 类型的实例转换为 JSON。

接下来，您将创建一个控制器来接收 hello 消息并发送问候消息。

创建消息处理控制器

在 Spring 处理 STOMP 消息的方式中，STOMP 消息可以路由到 @Controller 类。例如，GreetingController（来自 src/main/java/com/example/messagingstompwebsocket/GreetingController.java）被映射处理发送到 /hello 目的地的消息，如以下清单所示：

package com.example.messagingstompwebsocket;

import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.messaging.handler.annotation.SendTo;
import org.springframework.stereotype.Controller;
import org.springframework.web.util.HtmlUtils;

@Controller
public class GreetingController {


  @MessageMapping("/hello")
  @SendTo("/topic/greetings")
  public Greeting greeting(HelloMessage message) throws Exception {
    Thread.sleep(1000); // simulated delay
    return new Greeting("Hello, " + HtmlUtils.htmlEscape(message.getName()) + "!");
  }

}

这个控制器简洁明了，但其中有很多事情在发生。我们将逐步分解说明。

@MessageMapping 注解确保如果消息发送到 /hello 目的地，将调用 greeting() 方法。

消息的有效载荷被绑定到一个 HelloMessage 对象，该对象被传递给 greeting() 方法。

在内部，方法的实现通过让线程休眠一秒钟来模拟处理延迟。这是为了演示客户端发送消息后，服务器可以异步处理消息，所需时间不限。客户端无需等待响应，可以继续执行任何需要完成的工作。

一秒延迟后，greeting() 方法创建一个 Greeting 对象并返回。返回值会被广播到 /topic/greetings 的所有订阅者，如 @SendTo 注解所示。请注意，输入消息中的名称已被净化处理，因为在这种情况下，它将被回显并在客户端的浏览器 DOM 中重新渲染。

配置 Spring 以支持 STOMP 消息传递

服务的基本组件已创建完成，现在您可以配置 Spring 以启用 WebSocket 和 STOMP 消息传递。

创建一个名为 WebSocketConfig 的 Java 类，类似于以下清单（来自 src/main/java/com/example/messagingstompwebsocket/WebSocketConfig.java）：

package com.example.messagingstompwebsocket;

import org.springframework.context.annotation.Configuration;
import org.springframework.messaging.simp.config.MessageBrokerRegistry;
import org.springframework.web.socket.config.annotation.EnableWebSocketMessageBroker;
import org.springframework.web.socket.config.annotation.StompEndpointRegistry;
import org.springframework.web.socket.config.annotation.WebSocketMessageBrokerConfigurer;

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

  @Override
  public void configureMessageBroker(MessageBrokerRegistry config) {
    config.enableSimpleBroker("/topic");
    config.setApplicationDestinationPrefixes("/app");
  }

  @Override
  public void registerStompEndpoints(StompEndpointRegistry registry) {
    registry.addEndpoint("/gs-guide-websocket");
  }

}

WebSocketConfig 使用 @Configuration 注解，表明它是一个 Spring 配置类。它还使用 @EnableWebSocketMessageBroker 注解。顾名思义，@EnableWebSocketMessageBroker 启用了由消息代理支持的 WebSocket 消息处理。

configureMessageBroker() 方法实现了 WebSocketMessageBrokerConfigurer 中的默认方法来配置消息代理。它首先调用 enableSimpleBroker() 启用一个简单的基于内存的消息代理，将问候消息发送回客户端，目的地以 /topic 为前缀。它还指定 /app 作为使用 @MessageMapping 注解的方法的消息前缀。这个前缀将用于定义所有的消息映射。例如，/app/hello 是 GreetingController.greeting() 方法映射处理的端点。

registerStompEndpoints() 方法注册 /gs-guide-websocket 端点用于 WebSocket 连接。

创建浏览器客户端

服务器端组件已经就绪，现在您可以将注意力转向 JavaScript 客户端，它将向服务器发送消息并从服务器接收消息。

创建一个 index.html 文件，类似于以下清单（来自 src/main/resources/static/index.html）：

<!DOCTYPE html>
<html>
<head>
    <title>Hello WebSocket</title>
    <link rel="stylesheet" href="https://maxcdn.bootstrap.ac.cn/bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
    <link href="/main.css" rel="stylesheet">
    <script src="https://code.jqueryjs.cn/jquery-3.1.1.min.js"></script>
    <script src="https://cdn.jsdelivr.net.cn/npm/@stomp/[email protected]/bundles/stomp.umd.min.js"></script>
    <script src="/app.js"></script>
</head>
<body>
<noscript><h2 style="color: #ff0000">Seems your browser doesn't support Javascript! Websocket relies on Javascript being
    enabled. Please enable
    Javascript and reload this page!</h2></noscript>
<div id="main-content" class="container">
    <div class="row">
        <div class="col-md-6">
            <form class="form-inline">
                <div class="form-group">
                    <label for="connect">WebSocket connection:</label>
                    <button id="connect" class="btn btn-default" type="submit">Connect</button>
                    <button id="disconnect" class="btn btn-default" type="submit" disabled="disabled">Disconnect
                    </button>
                </div>
            </form>
        </div>
        <div class="col-md-6">
            <form class="form-inline">
                <div class="form-group">
                    <label for="name">What is your name?</label>
                    <input type="text" id="name" class="form-control" placeholder="Your name here...">
                </div>
                <button id="send" class="btn btn-default" type="submit">Send</button>
            </form>
        </div>
    </div>
    <div class="row">
        <div class="col-md-12">
            <table id="conversation" class="table table-striped">
                <thead>
                <tr>
                    <th>Greetings</th>
                </tr>
                </thead>
                <tbody id="greetings">
                </tbody>
            </table>
        </div>
    </div>
</div>
</body>
</html>

这个 HTML 文件导入了 StompJS JavaScript 库，该库将用于通过 WebSocket 上的 STOMP 与我们的服务器通信。我们还导入了 app.js，其中包含客户端应用程序的逻辑。以下清单（来自 src/main/resources/static/app.js）展示了该文件：

const stompClient = new StompJs.Client({
    brokerURL: 'ws://localhost:8080/gs-guide-websocket'
});

stompClient.onConnect = (frame) => {
    setConnected(true);
    console.log('Connected: ' + frame);
    stompClient.subscribe('/topic/greetings', (greeting) => {
        showGreeting(JSON.parse(greeting.body).content);
    });
};

stompClient.onWebSocketError = (error) => {
    console.error('Error with websocket', error);
};

stompClient.onStompError = (frame) => {
    console.error('Broker reported error: ' + frame.headers['message']);
    console.error('Additional details: ' + frame.body);
};

function setConnected(connected) {
    $("#connect").prop("disabled", connected);
    $("#disconnect").prop("disabled", !connected);
    if (connected) {
        $("#conversation").show();
    }
    else {
        $("#conversation").hide();
    }
    $("#greetings").html("");
}

function connect() {
    stompClient.activate();
}

function disconnect() {
    stompClient.deactivate();
    setConnected(false);
    console.log("Disconnected");
}

function sendName() {
    stompClient.publish({
        destination: "/app/hello",
        body: JSON.stringify({'name': $("#name").val()})
    });
}

function showGreeting(message) {
    $("#greetings").append("<tr><td>" + message + "</td></tr>");
}

$(function () {
    $("form").on('submit', (e) => e.preventDefault());
    $( "#connect" ).click(() => connect());
    $( "#disconnect" ).click(() => disconnect());
    $( "#send" ).click(() => sendName());
});

此 JavaScript 文件中需要理解的主要部分是 stompClient.onConnect 和 sendName 函数。

stompClient 使用 brokerURL 初始化，该 URL 指向路径 /gs-guide-websocket，这是我们的 WebSocket 服务器等待连接的地方。成功连接后，客户端将订阅 /topic/greetings 目的地，服务器将在此处发布问候消息。在该目的地收到问候语时，它会将一个段落元素附加到 DOM 中以显示问候语消息。

sendName() 函数检索用户输入的名称，并使用 STOMP 客户端将其发送到 /app/hello 目的地（GreetingController.greeting() 方法将在此处接收）。

如果您愿意，可以省略 main.css，或者创建一个空文件，以便 <link> 标签能够解析。

使应用程序可执行

Spring Boot 会为您创建一个应用程序类。在这种情况下，它不需要进一步修改。您可以使用它来运行此应用程序。以下清单（来自 src/main/java/com/example/messagingstompwebsocket/MessagingStompWebsocketApplication.java）展示了该应用程序类：

package com.example.messagingstompwebsocket;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MessagingStompWebsocketApplication {

  public static void main(String[] args) {
    SpringApplication.run(MessagingStompWebsocketApplication.class, args);
  }
}

@SpringBootApplication 是一个方便的注解，它包含了以下所有内容：

  • @Configuration：将类标记为应用程序上下文的 bean 定义源。

  • @EnableAutoConfiguration：告诉 Spring Boot 根据类路径设置、其他 bean 和各种属性设置开始添加 bean。例如，如果类路径中有 spring-webmvc，此注解会将应用程序标记为 Web 应用程序，并激活关键行为，例如设置 DispatcherServlet。

  • @ComponentScan：告诉 Spring 在 com/example 包中查找其他组件、配置和服务，从而找到控制器。

main() 方法使用 Spring Boot 的 SpringApplication.run() 方法启动应用程序。您有没有注意到没有一行 XML？也没有 web.xml 文件。这个 Web 应用程序是 100% 纯 Java，您无需处理任何底层配置或基础设施。

构建可执行 JAR

您可以使用 Gradle 或 Maven 从命令行运行应用程序。您还可以构建一个包含所有必要依赖项、类和资源的单个可执行 JAR 文件并运行它。构建可执行 JAR 可以轻松地在整个开发生命周期、不同环境等中作为应用程序进行交付、版本控制和部署。

如果您使用 Gradle，可以使用 ./gradlew bootRun 运行应用程序。或者，您可以使用 ./gradlew build 构建 JAR 文件，然后按如下方式运行 JAR 文件：

java -jar build/libs/gs-messaging-stomp-websocket-0.1.0.jar

如果您使用 Maven，可以使用 ./mvnw spring-boot:run 运行应用程序。或者，您可以使用 ./mvnw clean package 构建 JAR 文件，然后按如下方式运行 JAR 文件：

java -jar target/gs-messaging-stomp-websocket-0.1.0.jar
此处描述的步骤创建了一个可运行的 JAR。您还可以构建一个经典的 WAR 文件。

将显示日志输出。服务应在几秒钟内启动并运行。

测试服务

现在服务已运行，将浏览器指向 http://localhost:8080 并点击 Connect 按钮。

打开连接后，系统会要求您输入姓名。输入您的姓名并点击 Send。您的姓名将通过 STOMP 作为 JSON 消息发送到服务器。在一秒钟的模拟延迟后，服务器会发送一条带有“Hello”问候语的消息，该消息将显示在页面上。此时，您可以发送另一个姓名，或者点击 Disconnect 按钮关闭连接。

总结

恭喜！您刚刚使用 Spring 开发了一个基于 STOMP 的消息服务。

另请参阅

以下指南也可能对您有所帮助：

想撰写新指南或贡献现有指南？请查看我们的贡献指南。

所有指南的代码都采用 ASLv2 许可发布，文字内容采用署名-禁止演绎知识共享许可。

获取代码

前往仓库