SpringBoot 2 REST 访问 MongoDB 数据

开篇词

该指南将引导你创建通过基于超媒体的 RESTful 前端访问基于文档的数据。
 

你将创建的应用

我们将构建一个 Spring 应用，该应用允许我们使用 Spring Data REST 创建和检索存储在 MongoDB NoSQL 数据库中的 Person 对象。Spring Data REST 具有 Spring HATEOAS 和 Spring Data MongoDB 的功能，并将它们自动结合在一起。
 

你将需要的工具

• 大概 15 分钟左右；
• 你最喜欢的文本编辑器或集成开发环境（IDE）
• JDK 1.8 或更高版本；
• Gradle 4+ 或 Maven 3.2+
• 你还可以将代码直接导入到 IDE 中：
  • Spring Too Suite (STS)
  • IntelliJ IDEA
     

如何完成这个指南

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

• 要从头开始，移步至从 Spring Initializr 开始；
• 要跳过基础，执行以下操作：
  • 下载并解压缩该指南将用到的源代码，或借助 Git 来对其进行克隆操作：git clone https://github.com/spring-guides/gs-accessing-mongodb-data-rest.git
  • 切换至 gs-accessing-mongodb-data-rest/initial 目录；
  • 跳转至该指南的安装并启动 MongoDB。

待一切就绪后，可以检查一下 gs-accessing-mongodb-data-rest/complete 目录中的代码。
 

从 Spring Initializr 开始

对于所有的 Spring 应用来说，你应该从 Spring Initializr 开始。Initializr 提供了一种快速的方法来提取应用程序所需的依赖，并为你完成许多设置。该示例需要 Rest Repositories 和 Spring Data MongoDB 依赖。下图显示了此示例项目的 Initializr 设置：

上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 accessing-mongodb-data-rest 的值分别显示为 Group 和 Artifact。在本示例的其余部分，将用到这些值。

以下清单显示了选择 Maven 时创建的 pom.xml 文件：

<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.0modelVersion>
	<parent>
		<groupId>org.springframework.bootgroupId>
		<artifactId>spring-boot-starter-parentartifactId>
		<version>2.2.2.RELEASEversion>
		<relativePath/> 
	parent>
	<groupId>com.examplegroupId>
	<artifactId>accessing-mongodb-data-restartifactId>
	<version>0.0.1-SNAPSHOTversion>
	<name>accessing-mongodb-data-restname>
	<description>Demo project for Spring Bootdescription>

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-data-mongodbartifactId>
		dependency>
		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-data-restartifactId>
		dependency>

		<dependency>
			<groupId>org.springframework.bootgroupId>
			<artifactId>spring-boot-starter-testartifactId>
			<scope>testscope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintagegroupId>
					<artifactId>junit-vintage-engineartifactId>
				exclusion>
			exclusions>
		dependency>
	dependencies>

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

project>

以下清单显示了在选择 Gradle 时创建的 build.gradle 文件：

plugins {
	id 'org.springframework.boot' version '2.2.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-data-mongodb'
	implementation 'org.springframework.boot:spring-boot-starter-data-rest'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

 

安装并启动 MongoDB

完成项目搭建后，我们可以安装和启动 MongoDB 数据库。

如果用的是 Mac 上的 Homebrew，则可以运行以下命令：

brew install mongodb

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：brew install mongodb-community。并且我还需要创建 /data/db 目录：mkdir -p /data/db。以及为其设置权限：sudo chown -R $USER /data/db

如果是 MacPorts 的话，可以运行以下命令：

port install mongodb

对于其他具有包管理的系统，例如 RedHat、Ubuntu、Debian、CentOS 以及 Windows，请参考 https://docs.mongodb.org/manual/installation/ 上的说明。
安装 MongoDB 之后，我们可以通过运行以下命令在控制台窗口中启动它（这也会启动服务器进程）：

mongod

我们应该看到类似于以下输出的内容：

all output going to: /usr/local/var/log/mongodb/mongo.log

 

创建域对象

我们需要创建一个新的域对象来展现一个人，如以下示例（在 src/main/java/com/example/accessingmongodbdatarest/Person.java 中）所示：

package com.example.accessingmongodbdatarest;

import org.springframework.data.annotation.Id;

public class Person {

  @Id private String id;

  private String firstName;
  private String lastName;

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }
}

Person 对象有一个名字和一个姓氏。还有一个 ID 对象，该对象被配置为自动生成，因此我们无需手动生成。
 

创建一个 Person 存储库

接下来，我们需要创建一个简单的存储库，如以下示例所示（在 src/main/java/com/example/accessingmongodbdatarest/PersonRepository.java 中）：

package com.example.accessingmongodbdatarest;

import java.util.List;

import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource(collectionResourceRel = "people", path = "people")
public interface PersonRepository extends MongoRepository<Person, String> {

  List<Person> findByLastName(@Param("name") String name);

}

该存储库是一个接口，可让我们执行涉及 Person 对象的各种操作。它通过扩展 MongoRepository 中定义的 PagingAndSortingRepository 接口来获得这些操作。

在运行时，Spring Data REST 自动创建该接口的实现。然后，它使用 @RepositoryRestResources 注解指示 Spring MVC 在 /people 处创建 RESTful 端点。

导出存储库不需要 @RepositoryRestResource。它仅用于更改导出详细信息，例如使用 /people 代替 /persons 的默认值。

这里，我们还定义了一个自定义查询，以基于 lastName 值检索 Person 对象的列表。我们可以在该指南的后续部分中看到如何调用它。

默认情况下，Spring Boot 尝试连接到本地托管的 MongoDB 实例。阅读参考文档，了解如何将我们的应用指向其他地方托管的 MongoDB 实例。

@SpringBootApplication 是一个便利的注解，它添加了以下所有内容：

• @Configuration：将类标记为应用上下文 Bean 定义的源；
• @EnableAutoConfiguration：告诉 Spring Boot 根据类路径配置、其他 bean 以及各种属性的配置来添加 bean。
• @ComponentScan：告知 Spring 在 com/example 包中寻找他组件、配置以及服务。

main() 方法使用 Spring Boot 的 SpringApplication.run() 方法启动应用。
 

构建可执行 JAR

我们可以结合 Gradle 或 Maven 来从命令行运行该应用。我们还可以构建一个包含所有必须依赖项、类以及资源的可执行 JAR 文件，然后运行该文件。在整个开发生命周期中，跨环境等等情况下，构建可执行 JAR 可以轻松地将服务作为应用进行发布、版本化以及部署。

如果使用 Gradle，则可以借助 ./gradlew bootRun 来运行应用。或通过借助 ./gradlew build 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar build/libs/gs-accessing-mongodb-data-rest-0.1.0.jar

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar build/libs/accessing-mongodb-data-rest-0.0.1-SNAPSHOT.jar。

如果使用 Maven，则可以借助 ./mvnw spring-boot:run 来运行该用。或可以借助 ./mvnw clean package 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar target/gs-accessing-mongodb-data-rest-0.1.0.jar

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar target/accessing-mongodb-data-rest-0.0.1-SNAPSHOT.jar。

我们还可以将 JAR 应用转换成 WAR 应用。

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

测试应用

现在该应用正在运行，我们可以对其进行测试。我们可以使用任何喜欢的 REST 客户端。以下示例使用 curl。

首先，我们要查看顶级服务。以下示例（带有输出）显示了如何执行该操作：

curl http://localhost:8080

{
  "_links" : {
    "people" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    }
  }
}

这里，我们可以初步了解该服务器所提供的功能。在 http://localhost:8080/people 上有一个 people 链接。它有一些选项，例如 ?page、?size 及 ?sort。

Spring Data REST 使用 HAL 格式进行 JSON 输出。它非常灵活，并提供了一种便捷的方式来提供与所提供数据相邻的链接。

使用 people 链接时，我们会在数据库中看到 Person 的记录（目前没有）：

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

当前没有任何元素，因此也没有分页内容，所以是时候创建一个新的 Person 了！

如果我们多次运行该指南，则可能有剩余数据。如果需要全新的开始，请参考 MongoDB Shell 快速参考中有关查找和删除数据库的命令。

以下命令创建一个名为 “Frodo Baggins” 的人：

curl -i -X POST -H "Content-Type:application/json" -d "{  \"firstName\" : \"Frodo\",  \"lastName\" : \"Baggins\" }" http://localhost:8080/people

HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: http://localhost:8080/people/53149b8e3004990b1af9f229
Content-Length: 0
Date: Mon, 03 Mar 2014 15:08:46 GMT

• -i：确保我们可以看到包括标题的响应消息。显示新创建的 Person 的 URI；
• -X POST 表示这是用于创建新条目的 POST；
• -H "Content-Type:application/json"：设置内容类型，以便应用知道有效负载包含 JSON 对象；
• -d'{"firstName: "Frodo", "lastName": "Barggins""}'：被发送的数据；

请注意，对 POST 操作的响应如何包含 Location 标头。它包含新创建资源的 URI。Spring Data REST 还具有两个方法（RepositoryRestConfiguration.setReturnBodyOnCreate(…) 与 setReturnBodyOnUpdate(…)），我们可以使用它们来配置框架以立即返回刚刚创建的资源的表示形式。
RepositoryRestConfiguration.setReturnBodyForPutAndPost(…) 是一种启用创建和更新操作的表示形式响应的快捷方式。

我们可以查询所有人，如以下示例所示：

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "persons" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

people 对象包含一个包含 Frodo 的列表。注意它是如何包含一个 self 链接的。Spring Data REST 还使用 Evo Inflector 来对实体名称进行复数以进行分组。

我们可以直接查询单个记录，如下所示：

curl http://localhost:8080/people/53149b8e3004990b1af9f229

{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
    }
  }
}

这似乎完全是基于 Web 的，但是后台有一个我们启动的 MongoDB 数据库。

在该指南中，只有一个域对象。在域对象相互关联的更复杂的系统中，Spring Data REST 展示了更多链接，以帮助导航至连接的记录。

我们可以通过运行以下命令（及其输出显示）找到所有自定义查询：

curl http://localhost:8080/people/search

{
  "_links" : {
    "findByLastName" : {
      "href" : "http://localhost:8080/people/search/findByLastName{?name}",
      "templated" : true
    }
  }
}

我们可以看到查询的 URL，包括 HTTP 查询参数，name。请注意，这与接口中嵌入的 @Param("name") 注解匹配。

以下示例显示了如何使用 findByLastName 查询：

curl http://localhost:8080/people/search/findByLastName?name=Baggins

{
  "_embedded" : {
    "persons" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
        }
      }
    } ]
  }
}

因为我们已将其定义为在代码中返回 List，所以它将返回所有结果。如果已将其定义为仅返回 Person，则它将选择要返回的 Person 对象之一。由于这可能是不可预测的，因此对于可能返回多个条目的查询，我们可能不想这样做。

我还可以发出 PUT、PATCH 和 DELETE REST 调用来分别替换、更新或删除现有记录。以下示例使用 PUT 调用：

curl -X PUT -H "Content-Type:application/json" -d "{ \"firstName\": \"Bilbo\", \"lastName\": \"Baggins\" }" http://localhost:8080/people/53149b8e3004990b1af9f229

curl http://localhost:8080/people/53149b8e3004990b1af9f229

{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
    }
  }
}

下面示例使用 PATCH 调用：

curl -X PATCH -H "Content-Type:application/json" -d "{ \"firstName\": \"Bilbo Jr.\" }" http://localhost:8080/people/53149b8e3004990b1af9f229

curl http://localhost:8080/people/53149b8e3004990b1af9f229

{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
    }
  }
}

PUT 替换整个记录。未提供的字段将替换为 null。我们可以使用 PATCH 更新项的子集。

我们还可以删除记录，如以下示例所示：

curl -X DELETE http://localhost:8080/people/53149b8e3004990b1af9f229

curl http://localhost:8080/people

{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

该超媒体驱动接口的一个方便方面是，我们可以使用 curl（或您喜欢的任何REST客户端）来发现所有 RESTful 端点。我们无需与客户交换正式契约或接口文件。
 

概述

恭喜你！我们已经开发了具有基于超媒体的 RESTful 前端和基于 MongoDB 后端的应用。
 

参见

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

• 使用 REST 访问 JPA 数据
• 使用 REST 访问 GemFire 数据（尽请期待～）
• 使用 MySQL 访问数据（尽请期待～）
• 使用 REST 访问 Neo4j 数据
• 消费 RESTful Web 服务
• 使用 AngularJS 消费 RESTful Web 服务
• 使用 jQuery 消费 RESTful Web 服务
• 使用 rest.js 消费 RESTful Web 服务
• 加固 Web 应用
• 使用 Spring 构建 REST 服务
• 使用 Spring Boot 构建应用程序
• 使用 Restdocs 创建 API 文档（尽请期待～）
• 为 RESTful Web 服务启用跨源请求（尽请期待～）
• 构建超媒体驱动的 RESTful Web 服务

想看指南的其他内容？请访问该指南的所属专栏：《Spring 官方指南》