本指南将引导您完成创建通过基于超媒体的 RESTful前端访问基于文档的数据的应用程序的过程。

你会建立什么

您将构建一个Spring应用程序,用于创建和检索Person使用Spring Data REST将对象存储在MongoDB NoSQL数据库中。 Spring Data REST具有Spring HATEOASSpring Data MongoDB的功能,并将它们自动组合在一起。

Spring Data REST还支持将Spring Data JPASpring Data GemfireSpring Data Neo4j作为后端数据存储,但是这些都不属于本指南的一部分。

你需要什么

如何完成本指南

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

从头开始 ,请继续进行“ 从Spring Initializr开始”

跳过基础知识 ,请执行以下操作:

完成后 ,您可以根据中的代码检查结果gs-accessing-mongodb-data-rest/complete

从Spring Initializr开始

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

初始化
上图显示了选择Maven作为构建工具的Initializr。您也可以使用Gradle。它还显示了com.exampleaccessing-mongodb-data-rest分别是Group和Artifact。在本示例的其余部分中,将使用这些值。

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

<?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>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.1.7.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>accessing-mongodb-data-rest</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>accessing-mongodb-data-rest</name>
	<description>Demo project for Spring Boot</description>

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

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-mongodb</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-rest</artifactId>
		</dependency>

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

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

</project>

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

plugins {
	id 'org.springframework.boot' version '2.1.7.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'
}

安装并启动MongoDB

为了使本指南生效,您必须站立本地MongoDB服务器。

在安装了Homebrew的Mac OS X计算机上,运行以下命令:

brew install mongodb

您可以在https://docs.mongodb.org/manual/installation/中找到更多安装选项。

安装MongoDB之后,您需要启动mongo守护程序。在Mac上,可以使用以下命令:

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

您可以通过运行另一个终端窗口来启动MongoDB客户端mongo命令。

创建一个域对象

创建一个新的域对象来呈现一个人,如下面的示例(在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对象,该对象配置为自动生成,因此无需处理。)

创建个人资料库

接下来,您需要创建一个简单的存储库,如下清单(在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 Commons中定义的接口。

在运行时,Spring Data REST自动创建此接口的实现。然后,它使用@RepositoryRestResource批注指示Spring MVC在以下位置创建RESTful端点/people

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

在这里,您还定义了一个自定义查询来检索以下内容的列表Person基于的对象lastName值。您可以在本指南中进一步了解如何调用它。

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

@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 。或者,您可以通过使用以下命令构建JAR文件: ./gradlew build然后运行JAR文件,如下所示:

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

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

java -jar target/gs-accessing-mongodb-data-rest-0.1.0.jar
此处描述的步骤将创建可运行的JAR。您还可以构建经典的WAR文件

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

测试应用

现在该应用程序正在运行,您可以对其进行测试。您可以使用任何所需的REST客户端。以下示例使用* nix工具curl

首先,您想查看顶级服务,如以下示例所示:

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

前面的示例提供了该服务器必须提供的功能的第一印象。有一个people链接位于http:// localhost:8080 / people 。它有一些选择,例如?page?size?sort

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

使用人员链接时,您会看到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 :确保您可以看到包含标题的响应消息。新创建的URI Person显示。

  • -X POST :发出信号POST用于创建新条目。

  • -H "Content-Type:application/json" :设置内容类型,以便应用程序知道有效负载包含JSON对象。

  • -d '{ "firstName" : "Frodo", "lastName" : "Baggins" }' :正在发送数据。

注意前面的POST操作包括Location标头。它包含新创建资源的URI。Spring Data REST也有两种方法( RepositoryRestConfiguration.setReturnBodyOnCreate(…)setReturnBodyOnUpdate(…) ),您可以将其配置为立即返回刚刚创建/更新的资源的表示形式的框架。

从中可以查询所有人,如以下示例所示:

$ 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
  }
}

persons对象包含带有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要返回的对象。由于这可能是不可预测的,因此对于可能返回多个条目的查询,您可能不想这样做。

您也可以发出PUTPATCHDELETE 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端点。无需与客户交换正式合同或接口文档。

摘要

恭喜你!您刚刚开发了一个具有基于超媒体的 REST前端和基于MongoDB的后端的应用程序。