このガイドでは、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.3.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.3.2.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 サービスを作成できます。

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

サービスは、/greeting の GET リクエストを処理します。オプションで、クエリ文字列に 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 パラメーターがリクエストにない場合、World の defaultValue が使用されます。

メソッド本体の実装は、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 サービスを開発しました。