入门 | 使用 REST 访问 Neo4j 数据

您将构建什么

您将构建一个 Spring 应用程序，它允许您使用 Spring Data REST 创建和检索存储在 Neo4j NoSQL 数据库中的 Person 对象。Spring Data REST 结合了 Spring HATEOAS 和 Spring Data Neo4j 的功能，并自动将它们组合在一起。

Spring Data REST 还支持 Spring Data JPA、Spring Data Gemfire 和 Spring Data MongoDB 作为后端数据存储，但本指南只涉及 Neo4j。

你需要什么

大约 15 分钟
一个喜欢的文本编辑器或 IDE
Java 17 或更高版本
Gradle 7.5+ 或 Maven 3.5+
您还可以将代码直接导入到您的 IDE 中

如何完成本指南

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

要从头开始，请转到[从头开始]。

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

下载并解压本指南的源存储库，或者使用 Git 克隆它：git clone https://github.com/spring-guides/{project_id}.git
进入 {project_id}/initial
跳到访问 Neo4j 的权限。

完成后，您可以将结果与 {project_id}/complete 中的代码进行比较。

搭建 Neo4j 服务器

在构建此应用程序之前，您需要设置一个 Neo4j 服务器。

Neo4j 有一个开源服务器，您可以免费安装。

在安装了 Homebrew 的 Mac 上，您可以在终端窗口中键入以下内容

$ brew install neo4j

有关其他选项，请参阅 https://neo4j.ac.cn/download/community-edition/

安装 Neo4j 后，您可以通过运行以下命令以其默认设置启动它

$ neo4j start

您应该会看到类似以下消息

Starting Neo4j.
Started neo4j (pid 96416). By default, it is available at https://:7474/
There may be a short delay until the server is ready.
See /usr/local/Cellar/neo4j/3.0.6/libexec/logs/neo4j.log for current status.

默认情况下，Neo4j 的用户名和密码均为 neo4j。但是，它要求更改新账户密码。为此，请运行以下命令

$ curl -v -u neo4j:neo4j POST localhost:7474/user/neo4j/password -H "Content-type:application/json" -d "{\"password\":\"secret\"}"

这将密码从 neo4j 更改为 secret（在生产环境中不要这样做！）。完成后，您应该已准备好运行本指南。

从 Spring Initializr 开始

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

手动初始化项目

导航到 https://start.spring.io。此服务会为您拉取应用程序所需的所有依赖项，并为您完成大部分设置。
选择 Gradle 或 Maven 以及您想要使用的语言。本指南假设您选择了 Java。
点击 Dependencies 并选择 Rest Repositories 和 Spring Data Neo4j。
单击生成。
下载生成的 ZIP 文件，这是一个已根据您的选择配置好的 Web 应用程序存档。

如果您的 IDE 集成了 Spring Initializr，您可以从 IDE 中完成此过程。

您还可以从 Github fork 该项目并在您的 IDE 或其他编辑器中打开它。

访问 Neo4j 的权限

Neo4j 社区版需要凭据才能访问。您可以通过在 src/main/resources/application.properties 中设置属性来配置凭据，如下所示

spring.neo4j.uri=bolt://:7687
spring.neo4j.authentication.username=neo4j
spring.neo4j.authentication.password=secret

这包括您之前设置的默认用户名（neo4j）和新设置的密码（secret）。

请勿将实际凭据存储在您的源代码仓库中。相反，请使用Spring Boot 的属性覆盖在运行时配置它们。

创建领域对象

您需要创建一个新的领域对象来表示一个人，如下面的示例（在 src/main/java/com/example/accessingneo4jdatarest/Person.java 中）所示

package com.example.accessingneo4jdatarest;

import org.springframework.data.neo4j.core.schema.Id;
import org.springframework.data.neo4j.core.schema.Node;
import org.springframework.data.neo4j.core.schema.GeneratedValue;

@Node
public class Person {

  @Id @GeneratedValue private Long 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/accessingneo4jdatarest/PersonRepository.java 中）所示

package com.example.accessingneo4jdatarest;

import java.util.List;

import org.springframework.data.repository.PagingAndSortingRepository;
import org.springframework.data.repository.CrudRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource(collectionResourceRel = "people", path = "people")
public interface PersonRepository extends PagingAndSortingRepository<Person, Long>, CrudRepository<Person, Long> {

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

}

此存储库是一个接口，允许您执行涉及 Person 对象的各种操作。它通过扩展 Spring Data Commons 中定义的 PagingAndSortingRepositry 接口来获取这些操作。

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

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

这里您还定义了一个自定义查询，用于根据 lastName 值检索 Person 对象的列表。您可以在本指南后面看到如何调用它。

查找应用程序类

当您使用 Spring Initializr 创建项目时，它会创建一个应用程序类。您可以在 src/main/java/com/example/accessingneo4jdatarest/Application.java 中找到它。请注意，Spring Initializr 会连接（并正确更改大小写）包名并将其添加到 Application 以创建应用程序类名。在这种情况下，我们得到 AccessingNeo4jDataRestApplication，如下面的列表所示

package com.example.accessingneo4jdatarest;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.neo4j.repository.config.EnableNeo4jRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

@EnableTransactionManagement
@EnableNeo4jRepositories
@SpringBootApplication
public class AccessingNeo4jDataRestApplication {

  public static void main(String[] args) {
    SpringApplication.run(AccessingNeo4jDataRestApplication.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，您不必处理任何管道或基础设施的配置。

@EnableNeo4jRepositories 注解激活 Spring Data Neo4j。Spring Data Neo4j 创建 PersonRepository 的具体实现，并配置它使用 Cypher 查询语言与嵌入式 Neo4j 数据库通信。

构建可执行 JAR

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

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

java -jar build/libs/{project_id}-0.1.0.jar

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

java -jar target/{project_id}-0.1.0.jar

这里描述的步骤创建了一个可运行的 JAR。您还可以构建一个经典的 WAR 文件。

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

测试应用程序

现在应用程序已运行，您可以对其进行测试。您可以使用任何您喜欢的 REST 客户端。以下示例使用名为 curl 的 *nix 工具。

首先，您想查看顶层服务。以下示例（带输出）展示了如何操作

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

这里您第一次了解了这个服务器可以提供什么。在 https://:8080/people 有一个 people 链接。它有一些选项，例如 ?page、?size 和 ?sort。

Spring Data REST 使用 HAL 格式进行 JSON 输出。它灵活方便，提供了一种在所服务数据旁边提供链接的方法。

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

目前没有元素，因此也没有页面，所以是时候创建一个新的 Person 了！为此，请运行以下命令（显示其输出）

$ curl -i -X POST -H "Content-Type:application/json" -d '{  "firstName" : "Frodo",  "lastName" : "Baggins" }' https://:8080/people
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Location: https://:8080/people/0
Content-Length: 0
Date: Wed, 26 Feb 2014 20:26:55 GMT

-i 确保您可以看到响应消息，包括头部信息。显示了新创建的 Person 的 URI
-X POST 表示这是一个用于创建新条目的 POST 请求
-H "Content-Type:application/json" 设置内容类型，以便应用程序知道有效负载包含一个 JSON 对象
-d '{ "firstName" : "Frodo", "lastName" : "Baggins" }' 是正在发送的数据

注意前面的 POST 操作如何包含一个 Location 头部。这包含新创建资源的 URI。Spring Data REST 还有两种方法（RepositoryRestConfiguration.setReturnBodyOnCreate(…) 和 setReturnBodyOnCreate(…)），您可以使用它们来配置框架，使其在创建资源后立即返回资源的表示。

由此，您可以通过运行以下命令（显示其输出）查询所有人员

$ curl https://:8080/people
{
  "_links" : {
    "self" : {
      "href" : "https://:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "https://:8080/people/search"
    }
  },
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "https://:8080/people/0"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

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

您可以通过运行以下命令（显示其输出）直接查询单个记录

$ curl https://:8080/people/0
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "https://:8080/people/0"
    }
  }
}

这可能看起来纯粹基于网络，但幕后有一个嵌入式的 Neo4j 图数据库。在生产环境中，您可能会连接到独立的 Neo4j 服务器。

在本指南中，只有一个领域对象。在一个更复杂的系统中，如果领域对象之间存在关联，Spring Data REST 会渲染额外的链接以帮助导航到连接的记录。

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

$ curl https://:8080/people/search
{
  "_links" : {
    "findByLastName" : {
      "href" : "https://:8080/people/search/findByLastName{?name}",
      "templated" : true
    }
  }
}

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

要使用 findByLastName 查询，请运行以下命令（显示其输出）

$ curl https://:8080/people/search/findByLastName?name=Baggins
{
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "https://:8080/people/0"
        },
        "person" : {
          "href" : "https://:8080/people/0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://:8080/people/search/findByLastName?name=Baggins"
    }
  }
}

由于您在代码中将其定义为返回 List<Person>，因此它会返回所有结果。如果您将其定义为仅返回 Person，它将选择一个 Person 对象返回。由于这可能是不可预测的，因此对于可以返回多个条目的查询，您可能不希望这样做。

您还可以发出 PUT、PATCH 和 DELETE REST 调用，以替换、更新或删除现有记录。以下示例（显示其输出）展示了一个 PUT 调用

$ curl -X PUT -H "Content-Type:application/json" -d '{ "firstName": "Bilbo", "lastName": "Baggins" }' https://:8080/people/0
$ curl https://:8080/people/0
{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "https://:8080/people/0"
    }
  }
}

以下示例（显示其输出）展示了一个 PATCH 调用

$ curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' https://:8080/people/0
$ curl https://:8080/people/0
{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "https://:8080/people/0"
    }
  }
}

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

您还可以删除记录，如下面的示例（显示其输出）所示

$ curl -X DELETE https://:8080/people/0
$ curl https://:8080/people
{
  "_links" : {
    "self" : {
      "href" : "https://:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "https://:8080/people/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

这种超媒体驱动的接口的一个方便之处在于，您可以使用 curl（或您喜欢的任何 REST 客户端）发现所有 RESTful 端点。您无需与客户交换正式的合同或接口文档。

总结

恭喜！您刚刚开发了一个具有基于超媒体的 RESTful 前端和基于 Neo4j 的后端的应用程序。

另请参阅

以下指南也可能有所帮助

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

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

使用 REST 访问 Neo4j 数据