このガイドでは、Springで「Hello, World」RESTful Webサービスを作成するプロセスを説明します。

構築するもの

http://localhost:8080/greetingでHTTP GET要求を受け入れるサービスを構築します。

次のリストに示すように、挨拶のJSON表現で応答します。

{"id":1,"content":"Hello, World!"}

次のリストに示すように、クエリ文字列のオプションの name パラメーターを使用して、グリーティングをカスタマイズできます。

http://localhost:8080/greeting?name=User

name パラメーター値は、次のリストに示すように、World のデフォルト値をオーバーライドし、応答に反映されます。

{"id":1,"content":"Hello, User!"}

必要なもの

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

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

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

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

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

Spring Initializrから開始

すべてのSpringアプリケーションの場合、Spring Initializr(英語) から開始する必要があります。Initializrは、アプリケーションに必要なすべての依存関係をすばやく取り込む方法を提供し、多くのセットアップを行います。この例では、Spring Web依存関係のみが必要です。次のイメージは、このサンプルプロジェクト用に設定されたInitializrを示しています。

initializr
前の図は、Mavenがビルドツールとして選択されたInitializrを示しています。Gradleも使用できます。また、com.example および rest-service の値をそれぞれグループおよびアーティファクトとして表示します。このサンプルの残りの部分では、これらの値を使用します。

次のリストは、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.2.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>rest-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>rest-service</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-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

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

</project>

次のリストは、Gradleを選択したときに作成される build.gradle ファイルを示しています。

plugins {
	id 'org.springframework.boot' version '2.2.0.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-web'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

リソース表現クラスを作成する

プロジェクトとビルドシステムをセットアップしたため、Webサービスを作成できます。

サービスの相互作用について考えることでプロセスを開始します。

サービスは、/greetingGET リクエストを処理します。オプションで、クエリ文字列に name パラメーターを使用します。 GET 要求は、挨拶を表す本文にJSONを含む 200 OK 応答を返す必要があります。次の出力のようになります。

{
    "id": 1,
    "content": "Hello, World!"
}

id フィールドは挨拶の一意の識別子であり、content は挨拶のテキスト表現です。

挨拶表現をモデル化するには、リソース表現クラスを作成します。これを行うには、次のリスト( src/main/java/com/example/restservice/Greeting.javaから)が示すように、id および content データのフィールド、コンストラクター、およびアクセサーを持つプレーンな古いJavaオブジェクトを提供します。

package com.example.restservice;

public class Greeting {

	private final long id;
	private final String content;

	public Greeting(long id, String content) {
		this.id = id;
		this.content = content;
	}

	public long getId() {
		return id;
	}

	public String getContent() {
		return content;
	}
}
このアプリケーションは、Jackson JSON(GitHub) ライブラリを使用して、タイプ Greeting のインスタンスをJSONに自動的にマーシャリングします。Jacksonは、Webスターターによってデフォルトで含まれています。

リソースコントローラーを作成する

RESTful Webサービスを構築するSpringのアプローチでは、HTTPリクエストはコントローラーによって処理されます。これらのコンポーネントは @RestController (Javadoc) アノテーションによって識別され、次のリスト( src/main/java/com/example/restservice/GreetingController.javaから)に示されている GreetingController は、Greeting クラスの新しいインスタンスを返すことにより、/greeting に対する GET 要求を処理します。

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

このコントローラーは簡潔でシンプルですが、内部ではさまざまなことが行われています。段階的にそれを分解します。

@GetMapping アノテーションは、/greeting へのHTTP GET要求が greeting() メソッドにマップされることを保証します。

他のHTTP動詞のコンパニオンアノテーションがあります(POSTの場合は @PostMapping など)。また、@RequestMapping アノテーションもあり、それらはすべて派生しており、同義語として機能します(例: @RequestMapping(method=GET))。

@RequestParam は、クエリ文字列パラメーター name の値を greeting() メソッドの name パラメーターにバインドします。 name パラメーターが要求にない場合、WorlddefaultValue が使用されます。

メソッド本体の実装は、counter の次の値に基づいて id および content 属性を持つ新しい Greeting オブジェクトを作成して返し、挨拶 templateを使用して指定された name をフォーマットします。

従来のMVCコントローラーと前述のRESTful Webサービスコントローラーの主な違いは、HTTPレスポンスの本文が作成される方法です。このRESTful Webサービスコントローラーは、ビューテクノロジーに依存して、グリーティングデータをHTMLにサーバー側でレンダリングするのではなく、Greeting オブジェクトを生成して返します。オブジェクトデータは、JSONとしてHTTPレスポンスに直接書き込まれます。

このコードはSpring @RestController (Javadoc) アノテーションを使用します。これは、すべてのメソッドがビューではなくドメインオブジェクトを返すコントローラーとしてクラスをマークします。 @Controller@ResponseBodyの両方を含めるための略記です。

Greeting オブジェクトはJSONに変換する必要があります。SpringのHTTPメッセージコンバーターのサポートにより、この変換を手動で行う必要はありません。Jackson 2(英語) はクラスパス上にあるため、Springの MappingJackson2HttpMessageConverter (Javadoc) が自動的に選択され、Greeting インスタンスがJSONに変換されます。

@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-rest-service-0.1.0.jar

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

java -jar target/gs-rest-service-0.1.0.jar
ここで説明する手順は、実行可能なJARを作成します。クラシックWARファイルを作成することもできます。

ロギング出力が表示されます。サービスは数秒以内に起動して実行されるはずです。

サービスをテストする

サービスが起動したため、http://localhost:8080/greetingにアクセスしてください:

{"id":1,"content":"Hello, World!"}

http://localhost:8080/greeting?name=Userにアクセスして、name クエリ文字列パラメーターを提供します。次のリストに示すように、content 属性の値が Hello, World! から Hello, User!に変化することに注意してください。

{"id":2,"content":"Hello, User!"}

この変更は、GreetingController@RequestParam 配置が期待どおりに機能していることを示しています。 name パラメーターには World のデフォルト値が指定されていますが、照会ストリングを介して明示的にオーバーライドできます。

id 属性が 1 から 2に変更されたことにも注意してください。これは、複数の要求にわたって同じ GreetingController インスタンスに対して作業していることと、その counter フィールドが期待どおりに各呼び出しで増加していることを証明しています。

要約

おめでとう! Springを使用してRESTful Webサービスを開発しました。