Spring Boot REST API
開発完全マスターガイド

1. クラスとファイルの関係

1.1 物理的な構成ルール

Javaでは、一つの .java ファイルの中に含めることができる要素に厳格なルールがあります。

• public要素の制限: 1つのファイルに public 修飾子がついた要素（class, interface, enum）は最大1つだけです。
• ファイル名の一致: ファイル名は、その中にある public 要素の名前と完全に一致（大文字小文字も含む）させる必要があります。
• 非public要素: public を付けない要素であれば、1つのファイルに何個でも書けます。これらは同一パッケージ内でのみ使用される補助的な役割を果たします。

// ItemService.java というファイル名の場合

public interface ItemService { 
    // publicなインターフェース。ファイル名と一致必須。
    void process();
}

abstract class BaseProcessor {
    // 非publicな抽象クラス。同一ファイル内に記述可能。
}

class HelperTool {
    // 非publicな普通のクラス。何個でも追加可能。
}

2. 命名規則の完全ルール

Javaには「誰が書いても同じように見える」ための強力な慣習があります。これに背くと非常に読みにくいコードになります。

インターフェースに "I" を付けない理由

3. 型・アクセス修飾子

3.1 変数の基本型（全プリミティブ型）

Javaには8つのプリミティブ型があります。C++と異なり、long double は存在しませんが、代わりに BigDecimal という高精度な参照型を多用します。

4. 文字列操作・比較・型変換

4.1 主要なStringメソッド

String s = "Spring Boot";

s.toUpperCase();                 // "SPRING BOOT"
s.toLowerCase();                 // "spring boot"
s.startsWith("Spring");      // true
s.contains(" ");             // true
s.substring(0, 6);               // "Spring"

// ===== よく使う基本メソッド =====

s.equals("Spring Boot");      // true（文字列の内容比較）
s.equalsIgnoreCase("spring boot"); // true（大文字小文字を無視）
s.replace("Boot", "Framework"); // "Spring Framework"
s.replaceAll(" ", "_");        // "Spring_Boot"（正規表現対応）
s.length();                       // 11（文字数）
s.indexOf("Boot");          // 7（見つからない場合は -1）
s.trim();                         // 前後の空白を除去
s.isEmpty();                      // false（長さが0か）

String[] parts = s.split(" "); // {"Spring", "Boot"}

4.2 型の相互変換 (BigDecimal含む)

// --- String -> 各型 ---
int i = Integer.parseInt("10");
double d = Double.parseDouble("3.14");
// BigDecimalへの変換 (文字列を渡すのが最も安全)
BigDecimal bd = new BigDecimal("1234.567"); 

// --- 各型 -> String ---
String s1 = String.valueOf(100);
String s2 = String.valueOf(3.14);
String s3 = bd.toString(); // BigDecimalを文字列へ

4.3 数値操作 (Mathクラス)

Javaの標準 Math クラスには、数学的な計算を行うための静的メソッドが豊富に用意されています。

double val = 3.55;

// 基本の丸め処理
Math.round(val);    // 4 (四捨五入してlongを返す)
Math.ceil(val);     // 4.0 (切り上げ)
Math.floor(val);    // 3.0 (切り捨て)

// その他よく使うもの
Math.abs(-10);      // 10 (絶対値)
Math.max(10, 20);   // 20 (大きい方)
Math.min(10, 20);   // 10 (小さい方)
Math.pow(2, 3);     // 8.0 (2の3乗)
Math.sqrt(16);     // 4.0 (平方根)
Math.random();     // 0.0以上1.0未満の乱数

5. 全演算子（算術・代入・論理・ビット）

5.1 算術演算子 & インクリメント

• +, -, *, /, % (基本演算)
• ++ (インクリメント: 1増やす) / -- (デクリメント: 1減らす)

int n = 10;
n++; // n は 11 になる
System.out.println(++n); // 先に増やしてから表示 (12)
System.out.println(n--); // 表示してから減らす (12を表示後、nは11になる)

5.2 代入演算子

• = (基本代入)
• +=, -=, *=, /=, %= (複合代入)

int x = 5;
x += 10; // x = x + 10 と同じ。結果は 15。
x *= 2;  // x = x * 2 と同じ。結果は 30。

5.3 論理・ビット演算子

Javaでは数値リテラルとして、2進数（0b始まり）や16進数（0x始まり）を直接記述できます。

int a = 0b1010; // 2進数 (10進数で10)
int b = 0b1100; // 2進数 (10進数で12)
int hex = 0xFF; // 16進数 (10進数で255)

// ビット演算の実例
int res1 = a & b;  // AND: 両方1なら1 (1000 = 8)
int res2 = a | b;  // OR : どちらか1なら1 (1110 = 14)
int res3 = a ^ b;  // XOR: 異なれば1 (0110 = 6)
int res4 = ~a;     // NOT: 反転

// 論理演算 (条件分岐で使用)
boolean logic = (a > 5) && (b < 20); // AND (かつ)

5.4 三項演算子

条件によって代入する値を1行で切り替える際に非常に便利です。

// 書式: (条件式) ? 真の場合の値 : 偽の場合の値
int age = 20;
String type = (age >= 18) ? "Adult" : "Minor";

// これは以下のif文と同じ意味です
if (age >= 18) { type = "Adult"; } else { type = "Minor"; }

6. 比較・ループ・Switch構文

6.1 分岐（if-else）

if (score >= 90) {
    System.out.println("Excellent");
} else if (score >= 70) {
    System.out.println("Good");
} else {
    System.out.println("Retry");
}

6.2 Switch文とSwitch式

従来の Switch文 (breakが必要)

break を忘れると、下のケースまで実行（フォールスルー）されてしまうため注意が必要です。

switch (day) {
    case 1:
        System.out.println("Mon");
        break;
    default:
        System.out.println("Other");
        break;
}

最新の Switch式 (Java 14+)

-> を使うことで break が不要になり、値を直接変数に代入できます。

String msg = switch (status) {
    case 200 -> "Success";
    case 404 -> "Not Found";
    default  -> "Unknown";
};

6.3 ループ（for / while）

標準的な for ループ

回数が決まっている処理に適しています。

for (int i = 0; i < 5; i++) {
    System.out.println("Count: " + i);
}

拡張 for 文 (foreach)

配列やリストの全要素を順番に処理する、最も安全で推奨される方法です。

List<String> list = List.of("A", "B", "C");
for (String s : list) {
    System.out.println(s);
}

while と do-while

do-while は条件に関わらず最低1回は必ず実行されるのが最大の特徴です。

// while: 最初から条件判定（1回も動かない可能性あり）
while (count < 0) { ... }

// do-while: 実行してから判定（必ず1回は動く）
do {
    System.out.println("必ず1回は表示されます");
} while (false);

6.4 ループの制御（break / continue）

for (int i = 0; i < 10; i++) {
    if (i == 3) continue; // 3の時だけスキップして次へ
    if (i == 7) break;    // 7になったらループ自体を即終了
    System.out.println(i);
}

7. 配列・リスト・セット・辞書(Map) の全メソッド

7.1 Array (配列)

サイズが固定されている最も基本的なコンテナです。

String[] fruits = {"Apple", "Banana"};

// --- 要素へのアクセス ---
String first = fruits[0]; // 0番目を取得
fruits[1] = "Orange";    // 書き換え

// --- 要素数 (sizeではありません) ---
int len = fruits.length; // 2 (フィールドなので括弧なし)

// --- できないこと ---
// fruits.indexOf("Apple"); // 配列にこのメソッドはありません
// fruits.add("Cherry");    // サイズ変更は不可能です

7.2 List (動的リスト)

順序を保持し、重複を許容します。API開発で最も使われます。

List<String> list = new ArrayList<>();

// --- 追加・挿入 ---
list.add("A");                // 末尾に追加
list.add(0, "Insert");        // 指定位置への挿入(Insert)

// --- 検索・取得 ---
list.get(0);                  // 指定位置の要素取得
list.contains("A");           // true (存在確認)
list.indexOf("A");            // 1 (位置取得。なければ-1)
list.size();                  // 要素数 (メソッドなので括弧あり)
list.isEmpty();               // 空かどうか

// --- 削除の仕様 (要注意) ---
boolean b = list.remove("Z"); // 値指定: 消せたらtrue。対象がなくても例外は出ない
String s = list.remove(0);    // index指定: 削除した要素を返す。範囲外は例外発生

// --- ソート ---
list.sort(Comparator.naturalOrder());

// --- ループ (拡張for文) ---
for (String item : list) {
    System.out.println(item);
}

// 同じ内容でも別インスタンスなら false
users.contains(new User("たかお", 24));  // false
users.indexOf(new User("たかお", 24));   // -1

public class User {
    public String name;
    public int age;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User)) return false;
        User user = (User) o;
        return age == user.age &&
               name.equals(user.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }
}

@Data
public class User {
    private String name;
    private int age;
}

7.3 Set (重複不可の集合)

同じ値は2つ以上入りません。順序の概念がないため、「○番目に挿入（insert）」はできません。

Set<String> set = new HashSet<>();
set.add("A");
set.add("A"); // 2回目は無視される。エラーにはならない。

// --- 主要メソッド ---
set.size();            // 1 (Setもsize()を使用)
set.contains("A");    // true (Listより圧倒的に高速)
set.remove("A");      // 削除

// --- ループ ---
for (String s : set) {
    System.out.println(s); // 取り出される順番は不定
}

7.4 Map (キー・バリュー型辞書)

Keyを元にValueを高速に引き出します。JSONとの相性が抜群です。

Map<String, Integer> map = new HashMap<>();
map.put("Apple", 100);
map.put("Orange", 80);

// --- 取得・確認 ---
map.get("Apple");       // 100 (キーがなければ null)
map.containsKey("Apple"); // true (キー存在確認)
map.containsValue(80);  // true (値存在確認)
map.size();             // 2
map.remove("Apple");             //100（削除した値。なければ null）
map.remove("Apple", 100);        // true（key と value が一致したら削除）
// --- 全要素ループ (3パターン) ---

// Pattern A: キーで回す
for (String key : map.keySet()) {
    System.out.println(key + " -> " + map.get(key));
}

// Pattern B: キーと値を同時に回す (推奨: 高速)
for (Map.Entry<String, Integer> entry : map.entrySet()) {
    System.out.println(entry.getKey() + ":" + entry.getValue());
}

// Pattern C: 値だけで回す
for (Integer val : map.values()) {
    System.out.println(val);
}

// hashCode が違うと equals は呼ばれない
set.contains(user);   // hashCode → equals の順

@Data
public class User {
    private String name;
    private int age;
}

Set<User> set = new HashSet<>();
User u = new User("たかお", 24);

set.add(u);
u.setAge(25);

set.contains(u); // false（要注意）

@Data
@EqualsAndHashCode(of = "id")
public class User {
    private Long id;
    private String name;
    private int age;
}

7.5 型の相互変換テクニック

// Array -> List
List<String> list = new ArrayList<>(Arrays.asList(array));
// List -> Array
String[] array = list.toArray(new String[0]);

// Set -> List (重複を除去してからソートしたい時などに)
List<String> listFromSet = new ArrayList<>(set);

// 全キーをリスト化
List<String> keyList = new ArrayList<>(map.keySet());
// 全値をリスト化
List<Integer> valList = new ArrayList<>(map.values());

8. インターフェース (Interface)

public interface UserLoader {
    // 1. 変数は自動的に public static final (定数) になる
    int MAX_RETRY = 3; 

    // 2. メソッドは自動的に public abstract になる
    User load(Long id); 

    // 3. 多重継承：implements A, B のように複数を同時に実装可能
}

9. 抽象クラス (Abstract Class)

抽象クラスは「共通部品」の宝庫です。親で共通の仕組みを作り、子で細部を仕上げます。

public abstract class AbstractService {
    // 1. インスタンス変数（状態）を持てる
    protected final String serviceId; 
    // 2. final でない（書き換え可能な）変数も持てる
    protected int accessCount = 0; 

    // コンストラクタ：親が変数を持つなら、子からデータを受け取る必要がある
    public AbstractService(String id) { this.serviceId = id; }

    // 実装済みメソッド：子クラスからそのまま呼び出して再利用できる
    public void log(String msg) { 
        this.accessCount++; // 変数を更新する共通処理
        System.out.println("[" + serviceId + "] count:" + accessCount + " " + msg); 
    }

    // 抽象メソッド：ここだけ子クラスで個別に実装させる
    // インターフェースと違い、public 修飾子の明示が必要
    public abstract void execute(); 
}

10. クラス (Class) の全実装パターン

「親の部品を使いつつ、外部との契約（IF）も守り、さらに自分独自の機能を追加する」最強の形です。

public class DatabaseUserService extends AbstractService implements UserLoader {
    
    // 1. 独自のプロパティ（親にはないもの）を自由に追加可能
    private int queryCount = 0;

    public DatabaseUserService() {
        // super() で親クラスのコンストラクタを動かし、共通変数を初期化する
        super("DB_USER_SRV"); 
    }

    // 2. --- IF(UserLoader)の契約を果たす ---
    @Override
    public User load(Long id) {
        log("データ取得中..."); // 親の部品(log)をそのまま再利用！
        this.queryCount++;
        return new User(id, "Database Taro");
    }

    @Override
    public void execute() { /* 独自処理 */ }

    // 3. --- 親にもIFにもない「自分だけの新機能」を自由に追加できる ---
    public int getQueryCount() { return this.queryCount; }
}

11. Record：不変のデータキャリアとボイラープレートの排除

Recordは、一度作成したら中身を書き換えられない「不変性（Immutable）」に特化した型です。

11.1 ボイラープレート（定型コード）との比較

public final class User {
    private final String name;
    private final int age;

    public User(String name, int age) {
        this.name = name; this.age = age;
    }
    public String getName() { return name; }
    public int getAge() { return age; }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof User user)) return false;
        return age == user.age && Objects.equals(name, user.name);
    }
    @Override public int hashCode() { return Objects.hash(name, age); }
    @Override public String toString() { return "User[name="+name+",age="+age+"]"; }
}

public record User(String name, int age) { }

// これだけで、左側のコンストラクタ、Getter、
// equals、hashCode、toString がすべて
// 内部的に自動生成されます。

11.2 Record の具体的な使用方法

// 1. インスタンスの作成 (new)
var user = new User("Taro", 25);

// 2. 値の取得 (メソッド名は「フィールド名()」)
String name = user.name(); // getName() ではない点に注意

// 3. 不変性（Immutable）：Setterは存在しない
// user.name = "Jiro"; // エラー！フィールドは final です。

// 4. 内容を「変更」したい時は、新しく作り直すのがルール
var updatedUser = new User("Jiro", user.age());

12. Enum：実務でのデータ連携フローと変換の自動化

Enumに ("日本語", 10) と持たせるのは、外部システム（DBやAPI）との連携のためです。

例えば、DBには数値 10 として保存されている「準備中」という状態を、プログラム内では OrderStatus.PREPARING として扱い、さらにAPIレスポンスでは「準備中」という日本語を返す、といった具合です。

このような「数値 ⇔ Enumインスタンス ⇔ 日本語」の変換をEnum自身に持たせることで、コード全体で一貫したデータの扱いが可能になります。

Java の Enum において、PREPARING("準備中", 10) という定義は、内部的には new OrderStatus("準備中", 10) というインスタンス化 を行っているのと同義です。そのため、カッコ内の引数を受け取って内部のフィールド（label や code）に保存するためのコンストラクタが必須となります。

public enum OrderStatus {
    PREPARING("準備中", 10),
    SHIPPED("発送済み", 20);

    private final String label;
    private final int code;

    // コンストラクタ：外部からは絶対に new できない (暗黙的に private)
    OrderStatus(String label, int code) {
        this.label = label;
        this.code = code;
    }

    public String getLabel() { return label; }
    public int getCode() { return code; }

    // DBの数値(10)からEnumインスタンスを特定する「変換メソッド」
    public static OrderStatus of(int code) {
        for (OrderStatus s : values()) {
            if (s.code == code) return s;
        }
        throw new IllegalArgumentException("不正なコード: " + code);
    }
}

実務での具体的なサンプル例

// DBから数値 10 が返ってきたと仮定
int dbValue = 10;

// ofメソッドで Enum インスタンスを取得
OrderStatus status = OrderStatus.of(dbValue); 

System.out.println(status); // PREPARING

// if文を羅列せずに、Enum自身から日本語名を取得する
String displayLabel = status.getLabel(); 

// APIの戻り値(JSON)のフィールドとして使用
return new OrderResponse(displayLabel); // 結果: { "status": "準備中" }

12. Enum：実務でのデータ連携フロー

特定の言語に依存しないよう、Enumには外部ファイルの「キー」だけを持たせます。

public enum OrderStatus {
    PREPARING("status.order.preparing", 10),
    SHIPPED("status.order.shipped", 20);

    private final String messageKey;
    private final int code;

    OrderStatus(String key, int code) {
        this.messageKey = key;
        this.code = code;
    }

    public String getMessageKey() { return messageKey; }
    public int getCode() { return code; }
}

15. 動的多言語化 (i18n) と LocaleContextHolder

Locale.JAPANESE などをソースに書くと、多言語対応は失敗します。 Spring Boot が提供する LocaleContextHolder を使い、実行時のリクエスト情報を取得します。

15.1 メッセージファイルの準備

status.order.preparing=準備中

status.order.preparing=Preparing

15.2 LocaleContextHolder を用いた「真」の多言語対応

LocaleContextHolder.getLocale() を呼ぶだけで、HTTPリクエストの Accept-Language ヘッダーに基づいた最適な言語が自動で選択されます。

@Service
@RequiredArgsConstructor
public class OrderService {

    private final MessageSource messageSource;

    public String getStatusLabel(OrderStatus status) {
        // ソースコードに Locale.JAPANESE などを書いてはいけない！
        // LocaleContextHolder を使って、リクエストごとの言語設定を動的に取得する。
        return messageSource.getMessage(
            status.getMessageKey(), 
            null, 
            LocaleContextHolder.getLocale() 
        );
    }
}

16. 関数の定義方法（メソッド）と全戻り値

16.1 戻り値の全バリエーション（完全復元）

// 1. void：値を返さない（処理のみ）
public void saveUser(User user) { /* ロジック */ }

// 2. 普通のクラスを返す（単一オブジェクト）
public User findById(Long id) { return new User("Taro", 25); }

// 3. Record を返す（複数の値をセットで返す、現代の標準）
public record UserResult(User user, String message) {}
public UserResult process() {
    return new UserResult(new User("Taro", 20), "成功");
}

16.2 Pair vs Record の選択（重要）

public Pair<String, Integer> getCoordinate() {
    return Pair.of("X軸", 100);
}
// 利用時：何が first で何が second か分かりにくい...
var p = getCoordinate();
System.out.println(p.getFirst()); 

public record Coordinate(String axis, int value) {}

public Coordinate getCoordinate() {
    return new Coordinate("X軸", 100);
}
// 利用時：axis, value という名前でアクセスできるため明確！
var c = getCoordinate();
System.out.println(c.axis()); 

17. ラムダ式と高階関数（関数を引数に取る関数）

17.1 基本的な使い方（変数への代入）

Function<String, Integer> stringLength = s -> s.length();
int len = stringLength.apply("Hello"); // 5

17.2 【詳説】高階関数の定義と実行メカニズム

メソッドの引数に関数型インターフェースを指定することで、呼び出し側から自由にロジックを注入できます。

// 文字列(input)と加工ロジック(logic)をセットで受け取る
public void displayProcessedMessage(String input, Function<String, String> logic) {
    
    // 注入されたロジック(関数)を内部で実行する命令。
    // 実行するまで、大文字になるか記号が付くかは不明（動的）。
    String result = logic.apply(input); 

    System.out.println("最終出力: " + result);
}

// 呼び出し例1：大文字にするロジックを渡す
displayProcessedMessage("hello", s -> s.toUpperCase()); 

// 呼び出し例2：アスタリスクで囲む別のロジックを渡す
displayProcessedMessage("hello", s -> "*** " + s + " ***"); 

17.3 代表的な関数型インターフェース一覧

18. 引数の仕様と解決策（Builderパターン）

18.2 Builderパターンの完全実装（Lombok使用）

① 【定義側】 クラスの設計

@Builder アノテーションにより、Javaがビルダークラスを自動生成します。

@Builder @Getter
public class UserProfile {
    private final String name;
    private final int age;
    private final String email;
    private final String address;
}

② 【利用側】 メソッドチェーンによる生成（名前指定と同等）

引数の順番に関わらず、フィールド名で値を指定できます。

UserProfile user = UserProfile.builder()
                        .name("Taro")
                        .age(25)
                        .email("taro@example.com")
                        .address("Tokyo")
                        .build(); // 最後にbuildを呼んで完成

18.3 可変長引数 (Varargs) の取り扱い

引数の個数を固定せず、任意の数を受け取りたい場合に 型... 引数名 の形式で使用します。

// 定義側：引数の最後に一つだけ定義可能
public void printAll(String... messages) {
    // messages は String[] 型として扱える
    for (String msg : messages) {
        System.out.println(msg);
    }
}

// 呼び出し側
printAll("A");               // 1個
printAll("A", "B", "C");     // 3個
printAll();                  // 0個（空の配列として渡る）

② 実務テクニック：Lombok の @Singular との連携

Builderパターンで「List」を扱う際、一個ずつ値を追加したい場合に非常に強力です。

@Builder
public class Group {
    @Singular // これを付けると、複数形フィールドに「単数形」のメソッドが追加される
    private final List<String> members;
}

// 利用側：一個ずつ追加できる（内部で可変長引数的な柔軟さを提供）
Group g = Group.builder()
               .member("Taro")
               .member("Jiro")
               .build();

13. REST API 開発に必須のアノテーション詳説

Spring Boot で RESTful な API を構築する際、リクエストの受け口となる Controller クラスで使用する主要なアノテーションを、実例とともに解説します。

13.1 クラスレベルの基本定義

@RestController
public class UserApiController { ... }

@RestController
@RequestMapping("/api/v1/users")
public class UserApiController {
    // 全てのメソッドが /api/v1/users から始まるパスになります
}

13.2 HTTP メソッドとパス変数

@GetMapping("/list")
public List<User> getAll() { ... }

@PostMapping("/create")
public User create() { ... }

// URLが /api/v1/users/123 の場合、id に 123 が入る
@GetMapping("/{id}")
public User getOne(@PathVariable Long id) {
    return userService.findById(id);
}

13.3 リクエストデータのバインド

// クライアントが送った JSON { "name": "Taro", "age": 20 } が User オブジェクトに変換される
@PostMapping
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

// URL: /api/v1/users/search?keyword=Java
@GetMapping("/search")
public List<User> search(@RequestParam String keyword) {
    return userService.search(keyword);
}

// 必須でない場合は defaultValue を指定可能
@GetMapping("/list")
public List<User> list(@RequestParam(defaultValue = "1") int page) { ... }

14. DI (依存性の注入) と Profile 戦略

14.1 DI (Dependency Injection) とは？

DIは「自分で使う道具を自分で用意（new）せず、外部（Spring Container）に用意してもらう」設計手法です。 これにより、利用側（ControllerやService）は具体的な実装クラスを意識せず、インターフェースに対してプログラミングできるようになります。

14.3 実務での呼び出し例（コンストラクタ注入の正体）

@RestController
@RequiredArgsConstructor
public class OrderController {
    private final NotificationService service;
}

@RestController
public class OrderController {
    private final NotificationService service;

    public OrderController(NotificationService service) {
        this.service = service;
    }
}

@Service
@RequiredArgsConstructor
public class UserProfileService {
    private final UserRepository userRepository;

    // このメソッドはシングルトン（1台）だが、引数が違うので100万人同時にさばける
    public User updateBio(Long userId, String newBio) {
        // 1. 「以前の状態」を外部（DB）から呼び出す
        User user = userRepository.findById(userId);

        // 2. 「渡されたデータ」で加工する（Service自身は何も記憶しない）
        user.setBio(newBio);

        // 3. 「新しい状態」を外部（DB）へ預け直す
        return userRepository.save(user);
    }
}

@RestController
public class UserController {
    private final UserProfileService service;

    @PatchMapping("/me/bio")
    public User updateBio(
        // クライアントから送られた「自分は誰か」というID（状態）を受け取る
        @AuthenticationPrincipal UserPrincipal principal, 
        @RequestBody String bio
    ) {
        // バケツリレーのように、引数としてデータを流し込む
        return service.updateBio(principal.getId(), bio);
    }
}

21. Java ファイル操作 (NIO.2) 完全ガイド

Java 11 以降の実務標準である java.nio.file.Files を活用し、Path結合、Open、書き込み/読み込み、例外処理、自動Closeまでを関数として完結させた実例です。

import java.nio.file.*;
import java.io.IOException;

public class BinaryFileHandler {

    // バイナリ書き込み関数の例 (Pathの結合を含む)
    public void saveBinary(String dir, String fileName, byte[] data) {
        // 1. Path.of でディレクトリとファイル名を安全に結合
        Path path = Path.of(dir, fileName);

        try {
            // 2. 書き込み実行 (Open -> Write -> Close が内部で完結)
            Files.write(path, data);
            System.out.println("バイナリ保存完了: " + path.toAbsolutePath());
        } catch (IOException e) {
            // 3. エラーハンドリング
            System.err.println("保存失敗: " + e.getMessage());
        }
    }

    // バイナリ読み込み関数の例
    public byte[] loadBinary(String dir, String fileName) {
        Path path = Path.of(dir).resolve(fileName); // resolveを使った結合例

        try {
            // ファイルを一気にバイト配列として取得
            return Files.readAllBytes(path);
        } catch (IOException e) {
            System.err.println("読み込み失敗: " + e.getMessage());
            return null;
        }
    }
}

// --- 読み込み (readLine) ---
try (BufferedReader reader = Files.newBufferedReader(path)) {
    String line;
    while ((line = reader.readLine()) != null) { // 1行ずつ読み込む
        System.out.println(line);
    }
}

// --- 書き出し (newLine) ---
try (BufferedWriter writer = Files.newBufferedWriter(path)) {
    writer.write("Hello World");
    writer.newLine(); // これが writeLine の役割（OSに応じた改行を挿入）
}

import java.nio.file.*;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.List;

public class TextFileHandler {

    // テキスト全行読み込み関数の例
    public void readAllText(String dir, String file) {
        Path path = Path.of(dir, file);

        try {
            // 全行を List<String> として取得 (UTF-8)
            List<String> lines = Files.readAllLines(path, StandardCharsets.UTF_8);
            
            // 拡張 for 文での処理
            for (String line : lines) {
                System.out.println("内容: " + line);
            }
        } catch (IOException e) {
            System.err.println("テキスト読み込み失敗: " + e.getMessage());
        }
    }

    // テキスト一括書き込み関数の例
    public void writeAllText(String dir, String file, String content) {
        Path path = Path.of(dir, file);
        try {
            // 文字列を一気に書き込む
            Files.writeString(path, content);
        } catch (IOException e) {
            System.err.println("テキスト書き込み失敗: " + e.getMessage());
        }
    }
}

import java.nio.file.*;
import java.io.*;

public class LargeFileHandler {

    // 1行ずつ読み込む関数の例 (try-with-resources を使用)
    public void processFileLineByLine(String dir, String file) {
        Path path = Path.of(dir, file);

        // try () の中でリソースを Open。ブロックを抜ける際自動で Close される。
        try (BufferedReader br = Files.newBufferedReader(path)) {
            String line;
            // readLine() は 1 行ずつ読み込み、末尾に達すると null を返す
            while ((line = br.readLine()) != null) {
                // ここで一行ずつの処理（メモリに優しい）
                System.out.println("読み込み行: " + line);
            }
        } catch (IOException e) {
            // Open失敗や読み込みエラーをキャッチ
            System.err.println("バッファ読み込みエラー: " + e.getMessage());
        }
    }

    // 少しずつ書き込む関数の例
    public void logLineByLine(String dir, String file, String msg) {
        Path path = Path.of(dir, file);

        try (BufferedWriter bw = Files.newBufferedWriter(path, StandardOpenOption.APPEND)) {
            bw.write(msg);
            bw.newLine(); // 改行コードを挿入
        } catch (IOException e) {
            System.err.println("追記書き込み失敗: " + e.getMessage());
        }
    }
}

catch (IOException e) {
    // 実行時例外に包み直すことで、呼び出し側での try-catch 強制を回避する
    throw new UncheckedIOException("致命的なファイルエラー", e);
}

import java.nio.file.*;
import java.io.*;
import java.util.UUID;

public class TempFileHandler {

    // テンポラリーファイルの一連の操作メソッド
    public void handleTemporaryProcess() {
        Path tempFilePath = null;
        try {
            // 1. 生成: 接頭辞と接尾辞(拡張子)を指定して一時ファイルを生成
            // (デフォルトの一時ディレクトリに作成される)
            tempFilePath = Files.createTempFile("work_", ".tmp");
            System.out.println("作成場所: " + tempFilePath);

            // 2. 書き込み: テキストを保存
            String secretData = "一時的な重要データ: " + UUID.randomUUID();
            Files.writeString(tempFilePath, secretData);

            // 3. 読み込み: 保存したデータを確認
            String readData = Files.readString(tempFilePath);
            System.out.println("読み込み結果: " + readData);

        } catch (IOException e) {
            throw new UncheckedIOException("一時ファイル操作エラー", e);
        } finally {
            // 4. 削除: 正常・異常問わず最後に必ず削除する
            if (tempFilePath != null) {
                try {
                    // ファイルを物理的に削除
                    Files.deleteIfExists(tempFilePath);
                    System.out.println("一時ファイルを安全に削除しました。");
                } catch (IOException e) {
                    System.err.println("削除に失敗しました: " + e.getMessage());
                }
            }
        }
    }

    // 補足: deleteOnExit() を使う方法
    public void createAutoDeleteTempFile() throws IOException {
        File temp = File.createTempFile("auto_", ".tmp");
        // JVMが終了したときに自動で削除されるように予約する
        temp.deleteOnExit();
    }
}

ウェブから送られてくるフォームデータ（key=value）やアップロードファイルを、サーバー側のファイルシステムに安全に保存する仕組みを解説します。

<!-- application/x-www-form-urlencoded 形式で送信 -->
<form action="/api/users/update-address" method="post">
    <!-- name属性が Java 引数の @RequestParam("...") に対応する -->
    <input type="hidden" name="userId" value="123">
    <input type="text" name="address" placeholder="新住所を入力">
    <button type="submit">住所を更新する</button>
</form>

import org.springframework.web.bind.annotation.*;
import lombok.RequiredArgsConstructor;

@RestController
@RequiredArgsConstructor
public class UserProfileController {
    private final UserService userService;

    @PostMapping("/api/users/update-address")
    public String updateAddress(
        @RequestParam("userId") Long id,
        @RequestParam("address") String addr
    ) {
        // 1. 実務に必須のバリデーション処理
        if (addr == null || addr.isBlank()) {
            return "住所が空です";
        }
        if (addr.length() > 100) {
            return "住所が長すぎます(100文字以内)";
        }

        // 2. ビジネスロジック(Service)を呼び出す
        userService.updateUserAddress(id, addr);
        return "住所を更新しました";
    }
}

import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;

@Service
@RequiredArgsConstructor
public class UserService {
    // 16章で詳説した DB 操作用 Bean (DI)
    private final NamedParameterJdbcTemplate db;

    @Transactional
    public void updateUserAddress(Long id, String newAddr) {
        String sql = "UPDATE users SET address = :addr WHERE id = :id";
        
        // パラメータのバインド (SQLインジェクション対策)
        var params = new MapSqlParameterSource()
            .addValue("id", id)
            .addValue("addr", newAddr);

        // DBのテーブルを物理的に更新
        db.update(sql, params);
    }
}

<!-- enctype="multipart/form-data" が必須 -->
<form action="/api/files/upload" method="post" enctype="multipart/form-data">
    <input type="file" name="targetFile">
    <button type="submit">アップロード</button>
</form>

import org.springframework.web.multipart.MultipartFile;
import java.nio.file.*;
import java.io.*;

@RestController
public class UploadController {

    // 1. MultipartFile でファイルの実体を受け取る
    @PostMapping("/api/files/upload")
    public String upload(@RequestParam("targetFile") MultipartFile file) {
        
        // 2. ファイルが空でないかチェック
        if (file.isEmpty()) return "ファイルがありません";

        // 3. 保存先の決定 (Path結合)
        Path savePath = Path.of("uploads").resolve(file.getOriginalFilename());

        try {
            // 4. 保存先ディレクトリがなければ作成
            Files.createDirectories(savePath.getParent());

            // 5. ファイルを保存先に書き出す (自動で Close される)
            file.transferTo(savePath);

            return "アップロード完了: " + savePath;
        } catch (IOException e) {
            throw new UncheckedIOException(e);
        }
    }
}

22. 外部サーバーとのHTTP通信 (WebClient)

22. 外部サーバーとのHTTP通信 (WebClient)

非同期通信を駆使し、外部APIからデータを取得・送信する方法を解説します。エラー発生時に特定のステータスコードを返す実務的な実装も含みます。

import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.web.server.ResponseStatusException;
import reactor.core.publisher.Mono;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Service
@RequiredArgsConstructor
public class ExternalApiService {
    private final WebClient.Builder webClientBuilder;

    // GET: エラーを能動的に例外へ変換する
    public Mono<String> fetchWithDetailedError(String url) {
        return webClientBuilder.build()
            .get()
            .uri(url)
            .retrieve()
            // 4xx, 5xx のステータスを検知して特定の例外を投げる
            .onStatus(HttpStatusCode::isError, response -> {
                HttpStatus status = (HttpStatus) response.statusCode();
                return Mono.error(new ResponseStatusException(status, "外部サーバーがエラーを返しました"));
            })
            .bodyToMono(String.class);
    }

    // POST: JSONを送信し、登録結果(JSON)を期待する
    public Mono<User> postToExternal(String url, User body) {
        return webClientBuilder.build()
            .post()
            .uri(url)
            // bodyValue: Userオブジェクトを自動的に JSON 変換
            .bodyValue(body) 
            .retrieve()
            // 期待: 外部サーバーが登録後の User 情報を JSON で返してくること
            .bodyToMono(User.class);
    }
}

import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.reactive.function.client.WebClientResponseException;
import reactor.core.publisher.Mono;
import lombok.extern.slf4j.Slf4j;
import java.util.Map;

@Slf4j
@RestController
@RequiredArgsConstructor
public class ExternalProxyController {
    private final ExternalApiService apiService;

    // --- GET の堅牢なハンドリング ---
    @GetMapping("/api/proxy/data")
    public Mono<ResponseEntity<Object>> getProxyData() {
        return apiService.fetchWithDetailedError("https://api.example.com/data")
            .map(data -> ResponseEntity.ok((Object) data))
            // 例外種類に応じたきめ細やかな対応
            .onErrorResume(e -> {
                if (e instanceof ResponseStatusException rse) {
                    // Service層で投げた意図的なエラー
                    log.error("外部サーバー起因のエラー: {}", rse.getReason());
                    return Mono.just(ResponseEntity.status(rse.getStatusCode())
                        .body(Map.of("error", rse.getReason())));
                } else if (e instanceof WebClientResponseException wce) {
                    // 通信そのものの失敗（タイムアウト等）
                    log.error("ネットワークエラー: {}", wce.getMessage());
                    return Mono.just(ResponseEntity.status(HttpStatus.BAD_GATEWAY).build());
                }
                // 未知のエラー
                log.error("予期せぬエラーが発生しました", e);
                return Mono.just(ResponseEntity.internalServerError().build());
            });
    }

    // --- POST の堅牢なハンドリング ---
    @PostMapping("/api/proxy/users")
    public Mono<ResponseEntity<Object>> postProxyUser(@RequestBody User user) {
        return apiService.postToExternal("https://api.example.com/users", user)
            .map(res -> ResponseEntity.status(HttpStatus.CREATED).body((Object) res))
            .onErrorResume(e -> {
                log.error("POST通信失敗: {}", e.getMessage());
                // クライアントに原因（Map）を添えて 502 を返す
                return Mono.just(ResponseEntity.status(HttpStatus.BAD_GATEWAY)
                    .body(Map.of("message", "外部サーバーへの登録に失敗しました", "detail", e.getMessage())));
            });
    }
}

23. VS Code での Spring Boot 開発完全ガイド

VS Code を最強の Java 開発環境にするための設定と、プロジェクトの作成、ビルド、デバッグのフローを解説します。

# プロジェクト直下の Maven Wrapper を使用
./mvnw spring-boot:run

24. JAR から WAR への変更手順

Spring Boot の標準は実行可能 JAR (Embedded Tomcat) ですが、外部の Web サーバー（Tomcat 等）へデプロイする場合は WAR (Web Application Archive) 形式にする必要があります。

<!-- 変更前: <packaging>jar</packaging> -->
<packaging>war</packaging>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
    <!-- provided を指定することで、外部サーバーの Tomcat を利用するようになります -->
    <scope>provided</scope>
</dependency>

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;

@SpringBootApplication
// 1. SpringBootServletInitializer を継承する
public class DemoApplication extends SpringBootServletInitializer {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    // 2. configure メソッドをオーバーライドする
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(DemoApplication.class);
    }
}

# クリーンアップとビルドの実行
./mvnw clean package

25. 設定ファイル (resources) の完全管理

Spring Boot の挙動を制御する各種ファイルは、すべて src/main/resources フォルダに配置します。

# --- サーバー設定 ---
server.port=8080

# --- データベース接続設定 (Connection Info) ---
# ここで指定した接続先に対して、後述の schema.sql 等が実行されます
spring.datasource.url=jdbc:sqlite:mydata.db
spring.datasource.driver-class-name=org.sqlite.JDBC
# 初期化スクリプト(schema.sql等)を常に実行する設定 (Spring Boot 3.x以降で推奨)
spring.sql.init.mode=always

# --- 【重要】アプリ独自のカスタム設定 ---
# グラフの種類や背景色など、プログラム内で使いたい定数を定義できます
app.ui.default-chart-type=bar
app.ui.background-color=lightgray
app.system.max-upload-size=10MB

import java.nio.file.*;
import java.io.IOException;

@Service
public class UserConfigService {

    // 保存場所: C:/Users/ユーザー名/.myapp/config.json など
    private final Path configPath = Path.of(System.getProperty("user.home"), ".myapp", "config.json");

    public void saveUserPreference(String jsonContent) throws IOException {
        // 1. 親ディレクトリがなければ作成
        Files.createDirectories(configPath.getParent());
        
        // 2. JARの外にあるファイルなので、Files.writeString で書き込み可能！
        Files.writeString(configPath, jsonContent);
    }

    public String loadUserPreference() throws IOException {
        if (!Files.exists(configPath)) return "{}";
        return Files.readString(configPath);
    }
}

error.notfound=User not found.

error.notfound=ユーザーが見つかりませんでした。

error.notfound=未找到用户。

CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
);

INSERT OR IGNORE INTO users (id, name) VALUES (1, 'テスト太郎');

その他のアノテーション（Lombok / Spring）

このセクションでは、本文で登場しきれなかった「よく見るけど意味が分かりにくい」アノテーションをまとめます。読者想定は Spring Boot 初心者です。

A. @Data（全部盛り：Getter/Setter/toString/equals/hashCode）

@Data は、Lombok の「全部入り」です。次を自動生成します： Getter / Setter / toString / equals / hashCode /（final以外の）RequiredArgsConstructor。 便利ですが、Entity などでは乱用しない方が安全です（理由は下で説明）。

// build.gradle / pom.xml で Lombok を追加した前提
@Data
public class UserDto {
    private Long id;
    private String name;
}

@Entity
public class User {
  @Id
  @GeneratedValue
  private Long id;
  private String name;
}

// 例：APIレスポンス用の箱（DTO）
public record UserDto(String name, int age) {}

// イメージ：途中でフィールド変更すると Set の中で行方不明になり得る
Set<User> set = new HashSet<>();
User u = new User();
u.setName("たかお");
set.add(u);

u.setName("たろう");     // hashCodeに使われる値が変わると危険
set.contains(u);         // false になることがある

// Entityの例（安全寄りの定番）
@Entity
@Getter
@Setter // 本当に必要なものだけにしたい場合は個別にsetterを書く
@EqualsAndHashCode(of = "id")
public class User {
  @Id
  @GeneratedValue
  private Long id;

  private String name;
}

@Entity
@Getter
@Setter
@EqualsAndHashCode(of = "id")
public class User {
  @Id
  @GeneratedValue
  private Long id;

  private String name;
}

@Entity
public class User {

  @Id
  @GeneratedValue
  private Long id;

  private String name;
}

// Repository を使ったDB操作（SQL不要）
User user = new User();
user.setName("たかお");

userRepository.save(user);     // INSERT
userRepository.findById(1L);   // SELECT
userRepository.delete(user);  // DELETE

// 全件取得
userRepository.findAll();

// 条件検索（メソッド名から自動生成）
userRepository.findByName("たかお");
userRepository.findByAge(24);

// 複数条件
userRepository.findByNameAndAge("たかお", 24);

// 部分一致
userRepository.findByNameContaining("たか");

// 存在チェック
userRepository.existsByName("たかお");

// 件数取得
userRepository.count();

// ソート付き全件取得
userRepository.findAll(Sort.by("name").descending());

// ページング付き全件取得（0ページ目、10件）
userRepository.findAll(PageRequest.of(0, 10));

// 部分一致（LIKE %たか%）
userRepository.findByNameContaining("たか");

// 比較
userRepository.findByAgeGreaterThan(20);
userRepository.findByAgeBetween(20, 30);

// null 判定
userRepository.findByNameIsNull();
userRepository.findByNameIsNotNull();

// AND / OR
userRepository.findByNameAndAge("たかお", 24);
userRepository.findByNameOrAge("たかお", 24);

// 組み合わせ
userRepository.findByNameContainingAndAgeGreaterThan("たか", 20);

// IN / NOT IN
userRepository.findByAgeIn(List.of(10, 20));
userRepository.findByNameIn(List.of("たかお", "たろう"));
userRepository.findByAgeNotIn(List.of(10, 20));

public interface UserRepository extends JpaRepository<User, Long> {
  List<User> findByNameContaining(String name);
  List<User> findByAgeGreaterThan(int age);
  List<User> findByAgeBetween(int min, int max);
  List<User> findByNameIsNull();
  List<User> findByNameIsNotNull();
  List<User> findByNameAndAge(String name, int age);
  List<User> findByNameOrAge(String name, int age);
  List<User> findByNameContainingAndAgeGreaterThan(String name, int age);
  List<User> findByAgeIn(List<Integer> ages);
  List<User> findByNameIn(List<String> names);
  List<User> findByAgeNotIn(List<Integer> ages);
}

        @Query("""
  SELECT u FROM User u
  WHERE (u.name = :name OR u.age = :age)
    AND u.email = :email
""")
List findCustom(@Param("name") String name,
                      @Param("age") int age,
                      @Param("email") String email);
    @Query("SELECT u FROM User u WHERE u.age IN :ages")
List userRepository.findByAges(@Param("ages") List ages);
    @Query("SELECT u FROM User u WHERE u.name LIKE %:name%")
List userRepository.findByNameLike(@Param("name") String name);
    @Query("SELECT u FROM User u WHERE u.name = :name AND u.age > :age")
List userRepository.findByNameAndAge(@Param("name") String name, @Param("age") int age);

// ① 取得（SELECT）
User user = userRepository.findById(1L).orElseThrow();

// ② 値を変更
user.setName("たろう");

// ③ 保存（UPDATE）
userRepository.save(user);

@Modifying
@Query("update User u set u.name = :name where u.id = :id")
void updateName(@Param("id") Long id,
                @Param("name") String name);

public class User {
  private Long id;
  private String name;
}

// JPAでは保存できない（エラー or そもそも対象外）
userRepository.save(user); // ❌ Entityではないため使えない

// 例：自分でSQLを書く必要があるイメージ
String sql = "INSERT INTO users(name) VALUES(?)";
PreparedStatement ps = connection.prepareStatement(sql);
ps.setString(1, "たかお");
ps.executeUpdate();

@GeneratedValue(strategy = GenerationType.AUTO)

@Id
@GeneratedValue
private Long id;

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE)
private Long id;

B. @AllArgsConstructor（全フィールド引数のコンストラクタ）

@AllArgsConstructor は、全フィールドを引数に取るコンストラクタを自動生成します。 「new する時に全部渡す」用途や、テストで便利です。

@AllArgsConstructor
public class Point {
    private int x;
    private int y;
}

// 生成されるイメージ：
// public Point(int x, int y) { this.x = x; this.y = y; }

// 利用例
var p = new Point(10, 20);

C. @NoArgsConstructor（引数なしコンストラクタ）

@NoArgsConstructor は 引数なし（デフォルト）コンストラクタを生成します。 JPA(Entity) では「引数なしコンストラクタが必要」なことが多く、よく使われます。

@NoArgsConstructor
@AllArgsConstructor
public class UserDto {
    private Long id;
    private String name;
}

D. @RequiredArgsConstructor（final / @NonNull だけのコンストラクタ）

@RequiredArgsConstructor は、final フィールド（または @NonNull が付いたフィールド）だけを引数に取るコンストラクタを生成します。
Spring Boot では「コンストラクタインジェクション」に直結するので、現場で非常に重要です。

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;

    public UserDto find(Long id) {
        var user = userRepository.findById(id)
                .orElseThrow(() -> new RuntimeException("not found"));
        return new UserDto(user.getId(), user.getName());
    }
}

E. @Builder（引数地獄を避ける：読みやすい生成）

フィールドが多いクラスで new の引数が増えてきたら、@Builder が便利です。 「名前付き引数っぽく」書けるため、初心者でも読み間違いを減らせます。

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class CreateUserRequest {
    private String name;
    private int age;
}

// 利用例（どの値が何か分かりやすい）
var req = CreateUserRequest.builder()
    .name("Taro")
    .age(20)
    .build();

F. @Slf4j（ログ用：System.out.println の卒業）

@Slf4j を付けると、log というロガーが自動生成されます。 REST API では標準出力よりログが基本です。

@Slf4j
@RestController
public class HealthController {

    @GetMapping("/health")
    public String health() {
        log.info("health called");
        return "OK";
    }
}

# ログをファイルに出力する設定
logging.file.name=app.log
logging.file.path=logs

# ログの出力例（app.log）
2024-06-01 12:00:00.000  INFO 12345 --- [           main] c.e.demo.DemoApplication               : Starting DemoApplication using Java 17
2024-06-01 12:00:01.000  INFO 12345 --- [           main] c.e.demo.DemoApplication               : Started DemoApplication in 1.234 seconds (JVM running for 1.567)

# ログのローテーション設定例（app.log.2024-06-01 などに日付ごとに分割）
logging.file.name=app.log
logging.file.path=logs
logging.file.rotation=10MB
logging.file.rotation.strategy=TIME_BASED
logging.file.rotation.time-based.rotation-pattern=app.log.%d{yyyy-MM-dd}

まとめ：初心者のおすすめ使い分け