Spring Boot プロジェクト作成ハンズオン
講義の区切り
基本編の目安は 60 分です。終了条件は「API 起動・設定変更・jar 実行」です。 発展内容・次回の目安: デプロイ環境の比較。基本の確認後に取り組んでください。 準備と前後の章は 学習ガイド で確認できます。
この教材について
対象者と到達目標
Java のクラスとコンストラクタを理解していて、Spring Boot の API を初めて作る方が対象です。 完了時には、生年月日を受け取り年齢を JSON で返す API を作り、jar ファイルで起動できることを目指します。
やること
JSON を返却するミニマムな API を例に、プロジェクト構成、作り方について説明します。
- プロジェクトの作り方(Spring Initializr)
- シンプルな API の実装
- DI について
- bean について
- Controller -> Service と呼び出す API 構成
- application.yaml の機能いろいろ
- プロファイル
- 環境変数読み込み
- jar デプロイ
やらないこと
- 認証(Spring Security)
- DB アクセス
事前準備
- JDK 21(本教材の推奨環境)がインストールされていること
- curl コマンドが使えること
プロジェクトの作成
- Spring Initializr にアクセス
- 次のように設定して「Generate」をクリック
- Project: Maven
- Language: Java
- Spring Boot: 4.0.2(選べない場合は、利用可能な 4.0 系の安定版)
- Project Metadata
- Group: dev.mikoto2000.workshop
- Artifact: projectcreate
- Name: projectcreate
- Package name: dev.mikoto2000.workshop.projectcreate
- Packaging: Jar
- Configuration: YAML
- Java: 21
- Dependencies:
- Spring Web
- Spring Boot DevTools
- Lombok
- ダウンロードした zip ファイルを解凍
各依存関係の説明
- Spring Web: Web アプリケーションを作成するための基本的な機能を提供。RESTful API の作成に必要なライブラリが含まれる
- Spring Boot DevTools: 開発効率を向上させるためのツール。コード変更時の自動再起動やライブリロード機能を提供
- Lombok: ボイラープレートコード(getter/setter、コンストラクタなど)を自動生成するためのライブラリ。コードの可読性と保守性を向上させる
プロジェクトの構成
プロジェクトのディレクトリ構成は次のようになります。
各ファイル・ディレクトリの説明
src/main/java: Java ソースコードを配置するディレクトリsrc/main/resources: アプリケーションの設定ファイルや静的リソースを配置するディレクトリsrc/test/java: テストコードを配置するディレクトリpom.xml: Maven のプロジェクト設定ファイル。依存関係やビルド設定が記述されている.gitignore: Git で管理しないファイルやディレクトリを指定するファイルmvnw/mvnw.cmd: Maven Wrapper スクリプト。Maven がインストールされていない環境でもプロジェクトをビルドできるようにする
エンドポイントを作る
設計
- エンドポイント:
/api/calc-age?birthDate=1990-01-01 - HTTP メソッド: GET
- クエリパラメータ:
birthDate(ISO 8601 形式の生年月日、例: 1990-01-01) - レスポンス形式: JSON
- レスポンス内容:
{ "age": 36 }(現在の年齢)
実装手順
リクエストは Controller が受け取り、Service が年齢を計算し、DTO に結果を詰めて返します。
DTO(Data Transfer Object)は、値を受け渡すためのクラスです。今回の DTO は age だけを持ちます。
Java ファイルは、起動クラス ProjectcreateApplication と同じパッケージか、その配下に配置してください。
1. DTO の作成
src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/dtoディレクトリにCalcAgeResponse.javaファイルを作成- 次のコードを
CalcAgeResponse.javaに追加
2. Service クラスの作成
src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/serviceにCalcAgeService.javaを作成- 次のコードを
CalcAgeService.javaに追加
今回は簡単な例にするため、LocalDate.now() で実行日の年齢を計算します。
日付によって結果が変わる処理をテストする場合は、基準日を引数で渡すなど、日付を固定できる設計が役立ちます。
(詳細は「Spring Boot テスト入門」参照。)
@Service とは
@Serviceアノテーションは、Spring Framework においてサービス層のクラスを示すために使用される- サービス層は、ビジネスロジックを実装する場所であり、コントローラー層とデータアクセス層の間の仲介役
@Serviceアノテーションを付与することで、依存性注入(DI)によって他のクラスから利用できるようにする
Bean とは
- Spring コンテナによって管理されるオブジェクトのこと
@Serviceアノテーションを使用することで、CalcAgeServiceクラスが Spring の Bean として登録される- これにより、他のクラスから
CalcAgeServiceを注入して利用できるようになる - Spring は起動クラスのパッケージ以下をスキャンし、
@Serviceなどを付けたクラスを Bean として登録する @Controller、@Repository、@Componentなどのアノテーションも同様に Bean を定義する(Spring にインスタンスを管理してもらう)ために使用される
3. コントローラークラスの作成
src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/controllerにCalcAgeController.javaを作成- 次のコードを
CalcAgeController.javaに追加
@RestController とは
@RestControllerアノテーションは、Spring Framework において RESTful Web サービスのコントローラークラスを示すために使用される- クライアントからの HTTP リクエストを受け取り、適切なサービスメソッドを呼び出してレスポンスを生成する役割を果たす
DI(Dependency Injection)について
CalcAgeControllerは、@RestControllerアノテーションにより、Spring によって管理されるコントローラークラスとして登録される- コンストラクタの仮引数と同型の
CalcAgeServiceに@Serviceアノテーションがついている - そのため、Spring コンテナから
CalcAgeServiceのインスタンスが自動的に注入される- これを依存性注入(Dependency Injection, DI)と呼ぶ
- コンストラクタがひとつだけの場合、
@Autowiredアノテーションを省略できる CalcAgeServiceのインスタンスは、Spring が管理するため、コード内で直接インスタンス化する必要がない- また、DI により、テスト時にモックオブジェクトを注入することも容易になる
@DateTimeFormat は、日付を yyyy-MM-dd 形式として受け取る指定です。
@RestController の戻り値はレスポンス本文になります。Spring が DTO を JSON に変換するため、JSON 文字列を自分で組み立てる必要はありません。
Lombok の @Data は getter / setter などを、@AllArgsConstructor は全フィールドを受け取るコンストラクタを生成します。
この例では、不正な日付形式やパラメータの省略は 400 になります。 未来の日付では Service が例外を投げますが、その例外を 400 に変換する処理はまだないため、500 になります。 入力検証とエラー応答は、次のバリデーション入門で学びます。
プロジェクトの実行
-
ターミナルを開き、プロジェクトのルートディレクトリに移動
-
次のコマンドを実行してアプリケーションを起動
-
ブラウザまたは curl コマンドでエンドポイントにアクセス
応答例(年齢は実行日によって変わります):
出力例の 36 は、2026 年に実行した場合の値です。実際には実行日の年齢が返れば成功です。
未来の日付を送ると、サービスが IllegalArgumentException を投げ、この段階では HTTP 500 が返ります。業務上の入力エラーを適切な HTTP 応答に変換する方法は 例外処理・エラー応答入門 で扱います。
アプリケーションの設定
これからアプリケーションの設定を進めます。 次の挙動ができるように設定ファイルを記述します。
- 待ち受けポートはデフォルト 8080, 環境変数があればその値で上書き
- ローカル環境ではログレベル DEBUG
- プロダクション環境ではログレベル INFO
application.yaml の作成
src/main/resources/application.yamlファイルを開くapplication.yamlを次のコードに置き換えsrc/main/resources/application-local-logging.yamlを作成し、次のコードを追加src/main/resources/application-prod-logging.yamlを作成し、次のコードを追加
これにより、 src/main/resources ディレクトリの構成は次のようになります。
プロファイルの切り替えについて
起動時に指定を追加しない場合、spring.profiles.active の値に従って local が有効になります。
プロファイルグループの定義によって local-logging も有効になり、application-local-logging.yaml が読み込まれます。
起動時に prod を指定すると、prod と prod-logging が有効になり、application-prod-logging.yaml の INFO が適用されます。
実際に切り替える方法は、この後の「アプリケーションのビルドとデプロイ」で説明します。
環境変数の利用
application.yaml で server.port が ${CREATEPROJECT_SERVER_PORT:8080} と設定されているため、環境変数 CREATEPROJECT_SERVER_PORT が設定されていればその値がポート番号として使用され、設定されていなければデフォルトで 8080 が使用される。
アプリケーション設定のまとめ
このように、Spring Boot では application.yaml を使用してアプリケーションの設定を柔軟に管理できる。
プロファイルを活用することで、開発環境と本番環境で異なる設定を簡単に切り替えることができる。
また、環境変数を利用することで、デプロイ先の環境に応じた設定を動的に変更することが可能となる。
DB やクラウドのエンドポイントなど、環境ごとに異なる設定が必要な場合に特に有用です。
例えば、次のように環境依存の要素ごとにファイルを分けることもできる。
追加例の DB 設定ファイルも使う場合は、対応するプロファイルグループに local-db / prod-db を追加します。
ファイルを作るだけではグループに含まれません。
アプリケーションのビルドとデプロイ
ここでは、jar を作ってローカルで起動するところまでを体験します。
サーバーへ配置する場合も jar と JDK が必要ですが、常駐化やネットワークの設定は別途行います。
先ほど spring-boot:run で起動したアプリは Ctrl+C で停止してください。
-
ターミナルを開き、プロジェクトのルートディレクトリに移動
-
次のコマンドを実行してアプリケーションをビルド
-
ビルドが成功すると、
targetディレクトリにprojectcreate-0.0.1-SNAPSHOT.jarファイルが生成される -
次のコマンドを実行してアプリケーションを起動(デフォルトプロファイル(local))
-
ブラウザまたは curl コマンドでエンドポイントにアクセス
応答例(年齢は実行日によって変わります):
local で起動したアプリを Ctrl+C で停止します。
続けて、--spring.profiles.active オプションを使って prod で起動します。
これにより、 prod プロファイルが有効になり、 application-prod-logging.yaml の設定が適用される。
local で起動した場合と、 prod で起動した場合で、ログレベルが異なることを確認できる。
まとめ
このハンズオンでは、Spring Boot を使用してシンプルな JSON API を作成する方法を学びました。
最後に、API が年齢を返すこと、jar で起動できること、local / prod でログの量が変わることを確認してください。
これらの基本的な知識を活用して、より複雑なアプリケーションの開発に挑戦してみてください。