For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/プロジェクト作成・デプロイ入門.md.

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 コマンドが使えること

プロジェクトの作成

  1. Spring Initializr にアクセス
  2. 次のように設定して「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
  3. ダウンロードした zip ファイルを解凍

各依存関係の説明

  • Spring Web: Web アプリケーションを作成するための基本的な機能を提供。RESTful API の作成に必要なライブラリが含まれる
  • Spring Boot DevTools: 開発効率を向上させるためのツール。コード変更時の自動再起動やライブリロード機能を提供
  • Lombok: ボイラープレートコード(getter/setter、コンストラクタなど)を自動生成するためのライブラリ。コードの可読性と保守性を向上させる

プロジェクトの構成

プロジェクトのディレクトリ構成は次のようになります。

projectcreate
├── src
│   ├── main
│   │   ├── java
│   │   │   └── dev
│   │   │       └── mikoto2000
│   │   │           └── workshop
│   │   │               └── projectcreate
│   │   │                   └── ProjectcreateApplication.java
│   │   └── resources
│   │       ├── application.yaml
│   │       └── static
│   └── test
│       └── java
│           └── dev
│               └── mikoto2000
│                   └── workshop
│                       └── projectcreate
│                           └── ProjectcreateApplicationTests.java
├── .gitignore
├── mvnw
├── mvnw.cmd
└── pom.xml

各ファイル・ディレクトリの説明

  • 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 の作成

  1. src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/dto ディレクトリに CalcAgeResponse.java ファイルを作成
  2. 次のコードを CalcAgeResponse.java に追加
    package dev.mikoto2000.workshop.projectcreate.calcage.dto;
    
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    
    @AllArgsConstructor
    @Data
    @NoArgsConstructor
    public class CalcAgeResponse {
      private int age;
    }

2. Service クラスの作成

  1. src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/service に CalcAgeService.java を作成
  2. 次のコードを CalcAgeService.java に追加
    package dev.mikoto2000.workshop.projectcreate.calcage.service;
    
    import org.springframework.stereotype.Service;
    import java.time.LocalDate;
    import java.time.Period;
    
    /**
     * 年齢計算サービスクラス
     */
    @Service
    public class CalcAgeService {
    
      /**
       * 指定された生年月日から現在の年齢を計算します。
       *
       * @param birthDate 生年月日
       * @return 年齢
       * @throws IllegalArgumentException 無効な生年月日が指定された場合
       */
      public int calculateAge(LocalDate birthDate) {
        LocalDate currentDate = LocalDate.now();
        if (birthDate == null || birthDate.isAfter(currentDate)) {
          throw new IllegalArgumentException("Invalid birth date");
        }
        return Period.between(birthDate, currentDate).getYears();
      }
    }
Note

今回は簡単な例にするため、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. コントローラークラスの作成

  1. src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/controller に CalcAgeController.java を作成
  2. 次のコードを CalcAgeController.java に追加
    package dev.mikoto2000.workshop.projectcreate.calcage.controller;
    
    import dev.mikoto2000.workshop.projectcreate.calcage.dto.CalcAgeResponse;
    import dev.mikoto2000.workshop.projectcreate.calcage.service.CalcAgeService;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestParam;
    import org.springframework.web.bind.annotation.RestController;
    
    import java.time.LocalDate;
    import org.springframework.format.annotation.DateTimeFormat;
    
    @RestController
    @RequestMapping("/api/calc-age")
    public class CalcAgeController {
    
      private final CalcAgeService calcAgeService;
    
      public CalcAgeController(CalcAgeService calcAgeService) {
        this.calcAgeService = calcAgeService;
      }
    
      @GetMapping
      public CalcAgeResponse calculateAge(@RequestParam("birthDate") @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate birthDate) {
        int age = calcAgeService.calculateAge(birthDate);
        return new CalcAgeResponse(age);
      }
    }
@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 になります。 入力検証とエラー応答は、次のバリデーション入門で学びます。

プロジェクトの実行

  1. ターミナルを開き、プロジェクトのルートディレクトリに移動

  2. 次のコマンドを実行してアプリケーションを起動

    ./mvnw spring-boot:run
  3. ブラウザまたは curl コマンドでエンドポイントにアクセス

    curl "http://localhost:8080/api/calc-age?birthDate=1990-01-01"

    応答例(年齢は実行日によって変わります):

    {"age":36}

出力例の 36 は、2026 年に実行した場合の値です。実際には実行日の年齢が返れば成功です。

未来の日付を送ると、サービスが IllegalArgumentException を投げ、この段階では HTTP 500 が返ります。業務上の入力エラーを適切な HTTP 応答に変換する方法は 例外処理・エラー応答入門 で扱います。

アプリケーションの設定

これからアプリケーションの設定を進めます。 次の挙動ができるように設定ファイルを記述します。

  • 待ち受けポートはデフォルト 8080, 環境変数があればその値で上書き
  • ローカル環境ではログレベル DEBUG
  • プロダクション環境ではログレベル INFO

application.yaml の作成

  1. src/main/resources/application.yaml ファイルを開く
  2. application.yaml を次のコードに置き換え
    server:
      port: ${CREATEPROJECT_SERVER_PORT:8080}
    spring:
      profiles:
        active: local
        group:
          local:
            - local-logging
          prod:
            - prod-logging
  3. src/main/resources/application-local-logging.yaml を作成し、次のコードを追加
    logging:
      level:
         root: DEBUG
  4. src/main/resources/application-prod-logging.yaml を作成し、次のコードを追加
    logging:
      level:
         root: INFO

これにより、 src/main/resources ディレクトリの構成は次のようになります。

src
 └── main
     └── resources
         ├── application.yaml
         ├── application-local-logging.yaml
         └── application-prod-logging.yaml

プロファイルの切り替えについて

起動時に指定を追加しない場合、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 やクラウドのエンドポイントなど、環境ごとに異なる設定が必要な場合に特に有用です。

例えば、次のように環境依存の要素ごとにファイルを分けることもできる。

src
 └── main
     └── resources
         ├── application.yaml
         ├── application-local-logging.yaml
         ├── application-prod-logging.yaml
         ├── application-local-db.yaml
         └── application-prod-db.yaml

追加例の DB 設定ファイルも使う場合は、対応するプロファイルグループに local-db / prod-db を追加します。 ファイルを作るだけではグループに含まれません。

アプリケーションのビルドとデプロイ

ここでは、jar を作ってローカルで起動するところまでを体験します。 サーバーへ配置する場合も jar と JDK が必要ですが、常駐化やネットワークの設定は別途行います。 先ほど spring-boot:run で起動したアプリは Ctrl+C で停止してください。

  1. ターミナルを開き、プロジェクトのルートディレクトリに移動

  2. 次のコマンドを実行してアプリケーションをビルド

    ./mvnw clean package
  3. ビルドが成功すると、 target ディレクトリに projectcreate-0.0.1-SNAPSHOT.jar ファイルが生成される

  4. 次のコマンドを実行してアプリケーションを起動(デフォルトプロファイル(local))

    java -jar target/projectcreate-0.0.1-SNAPSHOT.jar
  5. ブラウザまたは curl コマンドでエンドポイントにアクセス

    curl "http://localhost:8080/api/calc-age?birthDate=1990-01-01"

    応答例(年齢は実行日によって変わります):

    {"age":36}

local で起動したアプリを Ctrl+C で停止します。 続けて、--spring.profiles.active オプションを使って prod で起動します。

java -jar target/projectcreate-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

これにより、 prod プロファイルが有効になり、 application-prod-logging.yaml の設定が適用される。

local で起動した場合と、 prod で起動した場合で、ログレベルが異なることを確認できる。

まとめ

このハンズオンでは、Spring Boot を使用してシンプルな JSON API を作成する方法を学びました。 最後に、API が年齢を返すこと、jar で起動できること、local / prod でログの量が変わることを確認してください。 これらの基本的な知識を活用して、より複雑なアプリケーションの開発に挑戦してみてください。

参考資料