このガイドでは、ハイパーメディアベースの RESTful フロントエンドを通じてドキュメントベースのデータにアクセスするアプリケーションを作成するプロセスを順を追って説明します。

構築するもの

Spring Data REST を使用して、MongoDB (英語) NoSQL データベースに格納された Person オブジェクトを作成および取得できる Spring アプリケーションを構築します。Spring Data REST は、Spring HATEOAS および Spring Data MongoDB の機能を使用して、自動的に結合します。

Spring Data REST は、バックエンドデータストアとして Spring Data JPA、Spring Data Gemfire、Spring Data Neo4j もサポートしていますが、これらはこのガイドの一部ではありません。

何が必要

このガイドを完了する方法

ほとんどの Spring 入門ガイドと同様に、最初から始めて各ステップを完了するか、すでに慣れている場合は基本的なセットアップステップをバイパスできます。いずれにしても、最終的に動作するコードになります。

最初から始めるには、Spring Initializr から開始に進みます。

基本をスキップするには、次の手順を実行します。

完了したときは、gs-accessing-mongodb-data-rest/complete のコードに対して結果を確認できます。

Spring Initializr から開始

すべての Spring アプリケーションでは、Spring Initializr (英語) (Eclipse の場合は Spring スタータープロジェクト) から始める必要があります。Initializr は、アプリケーションに必要なすべての依存関係をすばやく取り込む方法を提供し、多くの設定を行います。この例では、Rest リポジトリと Spring Data MongoDB の依存関係が必要です。

必要な依存関係を含む Maven ビルドファイルを Spring Initializr (英語) から直接取得できます。次のリストは、Maven を選択したときに作成される 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>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.4.2</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>

必要な依存関係を含む Gradle ビルドファイルを Spring Initializr (英語) から直接取得できます。次のリストは、Gradle を選択したときに作成される build.gradle ファイルを示しています。

plugins {
	id 'org.springframework.boot' version '2.4.2'
	id 'io.spring.dependency-management' version '1.0.11.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'
}

test {
	useJUnitPlatform()
}

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

mongo コマンドを実行して、別のターミナルウィンドウから MongoDB クライアントを起動できます。

ドメインオブジェクトを作成する

次の例（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 を継承することによりこれらの操作を取得し、Spring Data Commons で定義された PagingAndSortingRepository (Javadoc) インターフェースを継承します。

実行時に、Spring Data REST はこのインターフェースの実装を自動的に作成します。次に、@RepositoryRestResource (英語) アノテーションを使用して Spring MVC に /people で RESTful エンドポイントを作成するよう指示します。

@RepositoryRestResource は、リポジトリのエクスポートには必要ありません。/persons のデフォルト値の代わりに /people を使用するなど、エクスポートの詳細を変更するためにのみ使用されます。

ここでは、lastName 値に基づいて Person オブジェクトのリストを取得するカスタムクエリも定義しました。このガイドのさらに下で呼び出す方法を確認できます。

デフォルトでは、Spring Boot はローカルでホストされている MongoDB のインスタンスに接続しようとします。他の場所でホストされている MongoDB のインスタンスをアプリケーションに指定する方法については、リファレンスドキュメントをご覧ください。

@SpringBootApplication は、次のすべてを追加する便利なアノテーションです。

  • @Configuration: アプリケーションコンテキストの Bean 定義のソースとしてクラスにタグを付けます。

  • @EnableAutoConfiguration: クラスパス設定、他の Bean、さまざまなプロパティ設定に基づいて Bean の追加を開始するよう Spring Boot に指示します。例: spring-webmvc がクラスパスにある場合、このアノテーションはアプリケーションに Web アプリケーションとしてフラグを立て、DispatcherServlet のセットアップなどの主要な動作をアクティブにします。

  • @ComponentScan: Spring に、com/example パッケージ内の他のコンポーネント、構成、サービスを探して、コントローラーを検出させるように指示します。

main() メソッドは、Spring Boot の SpringApplication.run() メソッドを使用してアプリケーションを起動します。XML が 1 行もないことに気付きましたか？ web.xml ファイルもありません。この Web アプリケーションは 100% 純粋な Java であり、接続機能やインフラストラクチャの構成に対処する必要はありませんでした。

実行可能 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

Maven を使用する場合、./mvnw spring-boot:run を使用してアプリケーションを実行できます。または、次のように、./mvnw clean package で JAR ファイルをビルドしてから、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
    }
  }
}

前の例は、このサーバーが提供するものの最初の垣間見ることを提供します。http://localhost:8080/people に people リンクがあります。?page、?size、?sort などのいくつかのオプションがあります。

Spring Data REST は、JSON 出力に HAL フォーマット (英語) を使用します。柔軟性があり、提供されるデータに隣接するリンクを提供する便利な方法を提供します。

人物リンクを使用すると、データベースに 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 シェルのクイックリファレンス (英語) を参照してください。

次のコマンドは、「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" : "Baggins" }': データが送信されています。

前の POST 操作に Location ヘッダーが含まれていることに注意してください。これには、新しく作成されたリソースの URI が含まれます。Spring Data REST には 2 つのメソッド（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 インフレクター (英語) を使用して、グループ化するエンティティの名前を複数形にします。

次の例に示すように、個々のレコードを直接照会できます。

$ curl http://localhost:8080/people/53149b8e3004990b1af9f229
{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/people/53149b8e3004990b1af9f229"
    }
  }
}
これは純粋に Web ベースのように見えるかもしれませんが、バックグラウンドでは、開始した MongoDB データベースと通信しています。

このガイドでは、ドメインオブジェクトは 1 つだけです。ドメインオブジェクトが互いに関連しているより複雑なシステムでは、Spring Data REST は追加のリンクをレンダリングして、接続されたレコードへのナビゲートを支援します。

次の例に示すように、すべてのカスタムクエリを検索します。

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

HTTP クエリパラメーター name を含む、クエリの URL を確認できます。これは、インターフェースに埋め込まれた @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 のみを返すように定義していた場合、Person オブジェクトの 1 つを選択して返します。これは予測できないため、複数のエントリを返す可能性のあるクエリに対してはそうしたくないでしょう。

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 エンドポイントを検出する方法です。正式な契約書やインターフェースドキュメントを顧客と交換する必要はありません。

要約

おめでとう！ ハイパーメディアベースの REST フロントエンドと MongoDB ベースのバックエンドを備えたアプリケーションを開発しました。

関連事項

次のガイドも役立ちます。

新しいガイドを作成したり、既存のガイドに貢献したいですか？ 投稿ガイドラインを参照してください: GitHub (英語) 。

すべてのガイドは、コード用の ASLv2 ライセンス、およびドキュメント用の Attribution、NoDerivatives クリエイティブコモンズライセンス (英語) でリリースされています。