> 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.

# Spring Boot プロジェクト作成ハンズオン

## 講義の区切り

基本編の目安は 60 分です。終了条件は「API 起動・設定変更・jar 実行」です。
発展内容・次回の目安: デプロイ環境の比較。基本の確認後に取り組んでください。
準備と前後の章は [学習ガイド](/Practical-Introduction-to-Spring-Boot/introduction.md) で確認できます。

## この教材について

### 対象者と到達目標

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](https://start.spring.io/) にアクセス
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、コンストラクタなど）を自動生成するためのライブラリ。コードの可読性と保守性を向上させる

### プロジェクトの構成

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

```text
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` に追加
   ```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 クラスの作成

<!-- textlint-disable -->

1. `src/main/java/dev/mikoto2000/workshop/projectcreate/calcage/service` に `CalcAgeService.java` を作成
2. 次のコードを `CalcAgeService.java` に追加
   ```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();
     }
   }
   ```

<!-- textlint-enable -->

:::note
今回は簡単な例にするため、`LocalDate.now()` で実行日の年齢を計算します。
日付によって結果が変わる処理をテストする場合は、基準日を引数で渡すなど、日付を固定できる設計が役立ちます。
（詳細は「[Spring Boot テスト入門](/Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/テスト入門.md)」参照。）
:::

##### `@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` に追加
   ```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. 次のコマンドを実行してアプリケーションを起動
   ```bash
   ./mvnw spring-boot:run
   ```
3. ブラウザまたは curl コマンドでエンドポイントにアクセス

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

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

   ```json
   {"age":36}
   ```

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

未来の日付を送ると、サービスが `IllegalArgumentException` を投げ、この段階では HTTP 500 が返ります。業務上の入力エラーを適切な HTTP 応答に変換する方法は [例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) で扱います。

## アプリケーションの設定

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

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

### `application.yaml` の作成

1. `src/main/resources/application.yaml` ファイルを開く
2. `application.yaml` を次のコードに置き換え
   ```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` を作成し、次のコードを追加
   ```yaml
   logging:
     level:
        root: DEBUG
   ```
4. `src/main/resources/application-prod-logging.yaml` を作成し、次のコードを追加
   ```yaml
   logging:
     level:
        root: INFO
   ```

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

```text
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` が適用されます。

実際に切り替える方法は、この後の「アプリケーションのビルドとデプロイ」で説明します。

### 環境変数の利用

<!-- textlint-disable -->

`application.yaml` で `server.port` が `${CREATEPROJECT_SERVER_PORT:8080}` と設定されているため、環境変数 `CREATEPROJECT_SERVER_PORT` が設定されていればその値がポート番号として使用され、設定されていなければデフォルトで `8080` が使用される。

<!-- textlint-enable -->

### アプリケーション設定のまとめ

このように、Spring Boot では `application.yaml` を使用してアプリケーションの設定を柔軟に管理できる。
プロファイルを活用することで、開発環境と本番環境で異なる設定を簡単に切り替えることができる。
また、環境変数を利用することで、デプロイ先の環境に応じた設定を動的に変更することが可能となる。

DB やクラウドのエンドポイントなど、環境ごとに異なる設定が必要な場合に特に有用です。

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

```text
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. 次のコマンドを実行してアプリケーションをビルド
   ```bash
   ./mvnw clean package
   ```
3. ビルドが成功すると、 `target` ディレクトリに `projectcreate-0.0.1-SNAPSHOT.jar` ファイルが生成される
4. 次のコマンドを実行してアプリケーションを起動(デフォルトプロファイル(local))
   ```bash
   java -jar target/projectcreate-0.0.1-SNAPSHOT.jar
   ```
5. ブラウザまたは curl コマンドでエンドポイントにアクセス

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

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

   ```json
   {"age":36}
   ```

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

```bash
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` でログの量が変わることを確認してください。
これらの基本的な知識を活用して、より複雑なアプリケーションの開発に挑戦してみてください。

## 参考資料

- [依存性注入 :: Spring Framework - リファレンス](https://spring.pleiades.io/spring-framework/reference/core/beans/dependencies/factory-collaborators.html)
- [プロファイル :: Spring Boot - リファレンスドキュメント](https://spring.pleiades.io/spring-boot/reference/features/profiles.html)
- [環境別の設定切り替え :: Spring Boot - リファレンス](https://spring.pleiades.io/spring-boot/reference/features/external-config.html)
- [基本概念: @Bean および @Configuration :: Spring Framework - リファレンス](https://spring.pleiades.io/spring-framework/reference/core/beans/java/basic-concepts.html)
