Spring Data REST API の自動生成 (MongoDB)

このガイドでは、ハイパーメディアベースの 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 もサポートしますが、これらはこのガイドの一部ではありません。

必要なもの

約 15 分
Eclipse STS や IntelliJ IDEA のような任意の IDE または VSCode のようなテキストエディター
Java 17 以降
Gradle 7.5+ (英語) または Maven 3.5+ [Apache] (英語)
コードを直接 IDE にインポートすることもできます。

本ガイドの完成までの流れ

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

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

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

このガイドを Eclipse で「Spring 入門コンテンツのインポート」するか、ソースリポジトリをダウンロードして解凍、または、Git (英語) を使用してクローンを作成します。git clone https://github.com/spring-guides/gs-accessing-mongodb-data-rest.git
gs-accessing-mongodb-data-rest/initial に cd
MongoDB をインストールして起動するにジャンプしてください。

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

Spring Initializr から開始

IDE を使用する場合はプロジェクト作成ウィザードを使用します。IDE を使用せずにコマンドラインなどで開発する場合は、この事前に初期化されたプロジェクトからプロジェクトを ZIP ファイルとしてダウンロードできます。このプロジェクトは、このチュートリアルの例に合うように構成されています。

プロジェクトを手動で初期化するには:

IDE のメニューまたはブラウザーから Spring Initializr を開きます。アプリケーションに必要なすべての依存関係を取り込み、ほとんどのセットアップを行います。
Gradle または Maven のいずれかと、使用する言語を選択します。このガイドは、Java を選択したことを前提としています。
依存関係をクリックし、Rest リポジトリと Spring Data MongoDB を選択します。
生成をクリックします。
結果の ZIP ファイルをダウンロードします。これは、選択して構成された Web アプリケーションのアーカイブです。

Eclipse や IntelliJ のような IDE は新規プロジェクト作成ウィザードから Spring Initializr の機能が使用できるため、手動での ZIP ファイルのダウンロードやインポートは不要です。

プロジェクトを Github からフォークして、IDE または他のエディターで開くこともできます。

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 オブジェクトもありますが、これは自動的に生成されるように構成されているため、処理する必要はありません。)

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

実行時に、Spring Data REST はこのインターフェースの実装を自動的に作成します。次に、@RepositoryRestResource (Javadoc) アノテーションを使用して、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 シェルのクイックリファレンス (英語) を参照してください。

次のコマンドは、"FrodoBaggins" という名前の人物を作成します。

$ 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 Inflector (英語) を使用して、グループ化するエンティティの名前を複数形にします。

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

$ 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 ベースのバックエンドを備えたアプリケーションを開発しました。

コードを入手する

リポジトリに移動