所有指南

使用 REST 访问 Neo4j 数据

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

您将构建什么

您将构建一个 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。

您需要什么

如何完成本指南

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

要从头开始，请继续阅读[scratch]。

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

完成后，您可以将您的结果与 {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 http://localhost: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 开始

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

手动初始化项目

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

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

  3. 点击 Dependencies 并选择 Rest Repositories 和 Spring Data Neo4j。

  4. 点击 Generate。

  5. 下载生成的 ZIP 文件，它是一个根据您的选择配置好的 Web 应用程序的压缩包。

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

访问 Neo4j 的权限

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

spring.neo4j.uri=bolt://localhost: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 中定义的PagingAndSortingRepository 接口来获得这些操作。

在运行时，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 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 输出。它非常灵活，并提供了一种便捷的方式来提供与提供的数据相邻的链接。 
$ 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 了！要创建，请运行以下命令（包含输出）

$ 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/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 http://localhost:8080/people
{
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people{?page,size,sort}",
      "templated" : true
    },
    "search" : {
      "href" : "http://localhost:8080/people/search"
    }
  },
  "_embedded" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

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

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

$ curl http://localhost:8080/people/0
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
这看起来似乎完全是基于 Web 的，但实际上，背后有一个嵌入式 Neo4j 图数据库。在生产环境中，您可能会连接到一个独立的 Neo4j 服务器。

在本指南中，只有一个领域对象。在一个更复杂的系统中，如果领域对象相互关联，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" : {
    "people" : [ {
      "firstName" : "Frodo",
      "lastName" : "Baggins",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/people/0"
        },
        "person" : {
          "href" : "http://localhost:8080/people/0"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "http://localhost: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" }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}

下面的示例（包含输出）展示了一个 PATCH 调用

$ curl -X PATCH -H "Content-Type:application/json" -d '{ "firstName": "Bilbo Jr." }' http://localhost:8080/people/0
$ curl http://localhost:8080/people/0
{
  "firstName" : "Bilbo Jr.",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/0"
    }
  }
}
PUT 替换整个记录。未提供的字段将被替换为 null。 PATCH 可用于更新项目的子集。

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

$ curl -X DELETE http://localhost:8080/people/0
$ 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 前端和基于 Neo4j 的后端应用程序。

另请参阅

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

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

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

获取代码

转到仓库