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

本指南将引导您完成创建“ hello world”应用程序的过程，该应用程序在浏览器和服务器之间来回发送消息。WebSocket是TCP之上非常薄，轻便的层。使用“子协议”嵌入消息非常适合。在本指南中，我们将深入研究STOMP消息并将其与Spring一起使用，以创建一个交互式Web应用程序。

你会建立什么

您将构建一个服务器，该服务器将接受带有用户名的消息。作为响应，它将把问候推送到客户端已订阅的队列中。

你需要什么

约15分钟
最喜欢的文本编辑器或IDE
JDK 1.8或更高版本
Gradle 4+或Maven 3.2+
您还可以将代码直接导入到IDE中：
- Spring Tool Suite (STS)
- IntelliJ IDEA

如何完成本指南

像大多数Spring 入门指南一样，您可以从头开始并完成每个步骤，也可以绕过您已经熟悉的基本设置步骤。无论哪种方式，您最终都可以使用工作代码。

要从头开始 ，请继续使用Gradle构建。

要跳过基础知识 ，请执行以下操作：

下载并解压缩本指南的源存储库，或使用Git对其进行克隆：git clone https://github.com/spring-guides/gs-messaging-stomp-websocket.git
光盘进入gs-messaging-stomp-websocket/initial
继续创建资源表示形式类。

完成后 ，您可以根据中的代码检查结果gs-messaging-stomp-websocket/complete 。

用Gradle构建

首先，您设置一个基本的构建脚本。在使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含使用Gradle和Maven所需的代码。如果您都不熟悉，请参阅使用Gradle 构建Java项目或使用Maven构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如， mkdir -p src/main/java/hello在* nix系统上：

└── src
    └── main
        └── java
            └── hello

创建一个Gradle构建文件

以下是最初的Gradle构建文件。

build.gradle

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:2.1.6.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'org.springframework.boot'
apply plugin: 'io.spring.dependency-management'

bootJar {
    baseName = 'gs-messaging-stomp-websocket'
    version =  '0.1.0'
}
sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile("org.springframework.boot:spring-boot-starter-websocket")
    compile("org.webjars:webjars-locator-core")
    compile("org.webjars:sockjs-client:1.0.2")
    compile("org.webjars:stomp-websocket:2.3.3")
    compile("org.webjars:bootstrap:3.3.7")
    compile("org.webjars:jquery:3.1.0")

    testCompile("org.springframework.boot:spring-boot-starter-test")
}

Spring Boot gradle插件提供了许多方便的功能：

它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。
它搜索public static void main()标记为可运行类的方法。
它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

用Maven构建

首先，您设置一个基本的构建脚本。使用Spring构建应用程序时，可以使用任何喜欢的构建系统，但是此处包含了使用Maven所需的代码。如果您不熟悉Maven，请参阅使用Maven 构建Java项目。

创建目录结构

在您选择的项目目录中，创建以下子目录结构；例如， mkdir -p src/main/java/hello在* nix系统上：

└── src
    └── main
        └── java
            └── hello

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.springframework</groupId>
    <artifactId>gs-messaging-stomp-websocket</artifactId>
    <version>0.1.0</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.6.RELEASE</version>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-websocket</artifactId>
        </dependency>

        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>webjars-locator-core</artifactId>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>sockjs-client</artifactId>
            <version>1.0.2</version>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>stomp-websocket</artifactId>
            <version>2.3.3</version>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>bootstrap</artifactId>
            <version>3.3.7</version>
        </dependency>
        <dependency>
            <groupId>org.webjars</groupId>
            <artifactId>jquery</artifactId>
            <version>3.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <properties>
        <java.version>1.8</java.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

Spring Boot Maven插件提供了许多方便的功能：

它收集类路径上的所有jar，并构建一个可运行的单个“über-jar”，这使执行和传输服务更加方便。
它搜索public static void main()标记为可运行类的方法。
它提供了一个内置的依赖项解析器，用于设置版本号以匹配Spring Boot依赖项。您可以覆盖所需的任何版本，但是它将默认为Boot选择的一组版本。

使用您的IDE进行构建

阅读如何将本指南直接导入Spring Tool Suite中。
在IntelliJ IDEA中阅读如何使用本指南。

创建资源表示形式类

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

通过考虑服务交互来开始该过程。

该服务将接受正文为JSON对象的STOMP消息中包含名称的消息。如果给定的名称是“ Fred”，则消息可能看起来像这样：

{
    "name": "Fred"
}

要对带有名称的消息进行建模，可以创建一个普通的旧Java对象，其中包含name属性和相应的getName()方法：

src/main/java/hello/HelloMessage.java

package hello;

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/hello/Greeting.java

package hello;

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。

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

创建一个消息处理控制器

在Spring使用STOMP消息传递的方法中，可以将STOMP消息路由到@Controller类。例如GreetingController被映射为处理到目标“ / hello”的消息。

src/main/java/hello/GreetingController.java

package hello;

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() 。

在内部，该方法的实现通过使线程休眠1秒来模拟处理延迟。这是为了证明客户端发送消息后，服务器可以花很多时间来异步处理消息。客户可以继续进行任何需要做的工作，而无需等待响应。

延迟1秒后， greeting()方法创建一个Greeting对象并返回它。该返回值将按照“ / topic / greetings”的规定向所有订阅者广播。 @SendTo注解。请注意，输入消息中的名称已被清除，因为在这种情况下，它将在客户端的浏览器DOM中回显并重新呈现。

为STOMP消息传递配置Spring

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

创建一个名为的Java类WebSocketConfig看起来像这样：

src/main/java/hello/WebSocketConfig.java

package hello;

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").withSockJS();
    }

}

WebSocketConfig带有注释@Configuration表示它是Spring配置类。也有注释@EnableWebSocketMessageBroker 。顾名思义， @EnableWebSocketMessageBroker启用由消息代理支持的WebSocket消息处理。

的configureMessageBroker()方法在中实现默认方法WebSocketMessageBrokerConfigurer配置消息代理。它开始于enableSimpleBroker()使简单的基于内存的消息代理可以将问候消息在以“ / topic”为前缀的目标位置上携带回客户端。它还为绑定的消息指定“ / app”前缀@MessageMapping -带注释的方法。此前缀将用于定义所有消息映射。例如，“ / app / hello”是GreetingController.greeting()方法被映射为句柄。

的registerStompEndpoints()方法注册“ / gs-guide-websocket”端点，启用SockJS后备选项，以便在WebSocket不可用时可以使用备用传输。SockJS客户端将尝试连接到“ / gs-guide-websocket”并使用可用的最佳传输方式（websocket，xhr-streaming，xhr-polling等）。

创建一个浏览器客户端

在服务器端组件就位之后，现在让我们将注意力转向JavaScript客户端，该客户端将向服务器端发送消息并从服务器端接收消息。

创建一个如下所示的index.html文件：

src/main/resources/static/index.html

<!DOCTYPE html>
<html>
<head>
    <title>Hello WebSocket</title>
    <link href="/webjars/bootstrap/css/bootstrap.min.css" rel="stylesheet">
    <link href="/main.css" rel="stylesheet">
    <script src="/webjars/jquery/jquery.min.js"></script>
    <script src="/webjars/sockjs-client/sockjs.min.js"></script>
    <script src="/webjars/stomp-websocket/stomp.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文件导入SockJS和STOMP javascript库，这些库将用于通过websocket使用STOMP与我们的服务器进行通信。我们也在这里导入app.js其中包含我们客户应用程序的逻辑。

让我们创建该文件：

src/main/resources/static/app.js

var stompClient = null;

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

function connect() {
    var socket = new SockJS('/gs-guide-websocket');
    stompClient = Stomp.over(socket);
    stompClient.connect({}, function (frame) {
        setConnected(true);
        console.log('Connected: ' + frame);
        stompClient.subscribe('/topic/greetings', function (greeting) {
            showGreeting(JSON.parse(greeting.body).content);
        });
    });
}

function disconnect() {
    if (stompClient !== null) {
        stompClient.disconnect();
    }
    setConnected(false);
    console.log("Disconnected");
}

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

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

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

该JavaScript文件要注意的主要部分是connect()和sendName()功能。

的connect()该函数使用SockJS和stomp.js打开到“ / gs-guide-websocket”的连接，这是我们的SockJS服务器正在等待连接的地方。连接成功后，客户端将预订“ / topic / greetings”目的地，服务器将在该目的地发布问候消息。在该目的地上收到问候语时，它将在DOM后面添加一个段落元素以显示问候语消息。

的sendName()函数检索用户输入的名称，并使用STOMP客户端将其发送到“ / app / hello”目的地（其中GreetingController.greeting()将会收到）。

使应用程序可执行

尽管可以将该服务打包为传统的WAR文件以部署到外部应用程序服务器，但是下面演示的更简单的方法创建了一个独立的应用程序。您将所有内容打包在一个可运行的JAR文件中，由一个好的旧Java驱动main()方法。在此过程中，您将使用Spring的支持将Tomcat Servlet容器作为HTTP运行时嵌入，而不是部署到外部实例。

src/main/java/hello/Application.java

package hello;

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

@SpringBootApplication
public class Application {

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

@SpringBootApplication是一个方便注释，它添加了以下所有内容：

@Configuration ：将类标记为应用程序上下文的Bean定义的源。
@EnableAutoConfiguration ：告诉Spring Boot根据类路径设置，其他bean和各种属性设置开始添加bean。例如，如果spring-webmvc在类路径上，此注释将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet 。
@ComponentScan ：告诉Spring在其中寻找其他组件，配置和服务hello包，让它找到控制器。

的main()方法使用Spring Boot的SpringApplication.run()启动应用程序的方法。您是否注意到没有一行XML？没有web.xml文件。该Web应用程序是100％纯Java，因此您无需处理任何管道或基础结构。

构建可执行的JAR

您可以使用Gradle或Maven从命令行运行该应用程序。您还可以构建一个包含所有必需的依赖项，类和资源的可执行JAR文件，然后运行该文件。构建可执行的jar使得在整个开发生命周期中，跨不同环境等等的情况下，可以轻松地将服务作为应用程序进行发布，版本化和部署。

如果您使用Gradle，则可以使用./gradlew bootRun 。或者，您可以通过使用以下命令构建JAR文件： ./gradlew build然后运行JAR文件，如下所示：

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

如果使用Maven，则可以通过使用以下命令运行应用程序./mvnw spring-boot:run 。或者，您可以使用以下命令构建JAR文件： ./mvnw clean package然后运行JAR文件，如下所示：

java -jar target/gs-messaging-stomp-websocket-0.1.0.jar

此处描述的步骤将创建可运行的JAR。您还可以构建经典的WAR文件。

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

测试服务

现在该服务正在运行，将浏览器指向http：// localhost：8080并单击“连接”按钮。

打开连接后，系统会要求您输入名称。输入您的姓名，然后单击“发送”。您的姓名将通过STOMP作为JSON消息发送到服务器。经过1秒钟的模拟延迟后，服务器将向页面发送回带有“ Hello”问候的消息，该问候显示在页面上。此时，您可以发送其他名称，也可以单击“断开连接”按钮以关闭连接。

摘要

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

也可以看看

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

是否要编写新指南或为现有指南做出贡献？查看我们的贡献准则。

所有指南均以代码的ASLv2许可证和写作的Attribution，NoDerivatives创作共用许可证发布。