> 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 分です。終了条件は、同じ商品の 2 回目の取得でデータの読み込みが省かれることをログで確認できることです。
さらに、価格を更新しても古い値が返る状態を再現し、`@CacheEvict` を追加して更新後の価格が返ることを確認します。

## 概要

商品を取得する API と、商品の価格を更新する API を作ります。
取得した商品をキャッシュに保存することで、同じ商品を読み取る処理を省きます。
価格が変わったときは、更新した商品に対応するキャッシュの項目を削除します。

この演習のリクエストは、前の応答を受け取ってから次を送ります。同時実行時の整合性は、後半の「同時実行時の制約」で確認します。

演習では、商品の保管場所とキャッシュの両方に、それぞれ独立したメモリ上の領域を使います。アプリを再起動すると、商品は初期価格に戻り、キャッシュは空になります。

## 事前準備

- JDK 21
- Controller と Service を使った API の作成経験
- 空きポート 8080

[Spring Initializr](https://start.spring.io/) で新しいプロジェクトを作成します。
Maven / Java / Jar / YAML を選び、Spring Boot は 4.0 系、Java は 21 にします。
Group は `dev.mikoto2000.springboot`、Artifact は `cache`、Package name は `dev.mikoto2000.springboot.cache` です。
依存関係に Spring Web を選び、生成した `pom.xml` の `dependencies` に次の依存関係を追加します。

```xml title="キャッシュの依存関係"
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-cache</artifactId>
</dependency>
```

## 触って学ぶキャッシュ

### 商品を取得・更新する API を作る

次のファイルは `src/main/java/dev/mikoto2000/springboot/cache` の下に配置します。
まず、API が返す商品を record で定義します。

```java title="Product.java"
package dev.mikoto2000.springboot.cache;

public record Product(long id, String name, int priceYen) {}
```

次に、商品を保管するクラスを作ります。読み込み時は `READ`、価格の更新時は `UPDATE` をログに出します。
価格変更では新しい `Product` を作り、保管場所の値を置き換えます。

```java title="ProductStore.java"
package dev.mikoto2000.springboot.cache;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Repository;

@Repository
public class ProductStore {

  private static final Logger log = LoggerFactory.getLogger(ProductStore.class);

  private final Map<Long, Product> products = new ConcurrentHashMap<>(Map.of(
      1L, new Product(1L, "Notebook", 1200),
      2L, new Product(2L, "Pen", 800)));

  public Product findById(long id) {
    Product product = products.get(id);
    if (product != null) {
      log.info("READ productId={} priceYen={}", id, product.priceYen());
    }
    return product;
  }

  public boolean updatePrice(long id, int priceYen) {
    Product updated = products.computeIfPresent(id,
        (key, current) -> new Product(key, current.name(), priceYen));
    if (updated == null) {
      return false;
    }
    log.info("UPDATE productId={} priceYen={}", id, updated.priceYen());
    return true;
  }
}
```

Service の `getProduct` は商品を取得し、`updatePrice` は価格を更新します。後でこの 2 つのメソッドにキャッシュのアノテーションを付けます。

```java title="ProductService.java"
package dev.mikoto2000.springboot.cache;

import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;

@Service
public class ProductService {

  private final ProductStore store;

  public ProductService(ProductStore store) {
    this.store = store;
  }

  public Product getProduct(long id) {
    Product product = store.findById(id);
    if (product == null) {
      throw new ResponseStatusException(HttpStatus.NOT_FOUND, "商品が見つかりません。");
    }
    return product;
  }

  public void updatePrice(long id, int priceYen) {
    if (priceYen < 0) {
      throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "価格は 0 円以上にしてください。");
    }
    if (!store.updatePrice(id, priceYen)) {
      throw new ResponseStatusException(HttpStatus.NOT_FOUND, "商品が見つかりません。");
    }
  }
}
```

Controller を作ります。商品取得は `GET /products/{id}`、価格の更新は `PUT /products/{id}/price?priceYen=1500` です。

```java title="ProductController.java"
package dev.mikoto2000.springboot.cache;

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ProductController {

  private final ProductService service;

  public ProductController(ProductService service) {
    this.service = service;
  }

  @GetMapping("/products/{id}")
  public Product getProduct(@PathVariable("id") long id) {
    return service.getProduct(id);
  }

  @PutMapping("/products/{id}/price")
  @ResponseStatus(HttpStatus.NO_CONTENT)
  public void updatePrice(@PathVariable("id") long id, @RequestParam("priceYen") int priceYen) {
    service.updatePrice(id, priceYen);
  }
}
```

プロジェクトのルート（`pom.xml` と同じ場所）でアプリを起動します。
PowerShell では `.\mvnw.cmd spring-boot:run` を使います。

```bash
./mvnw spring-boot:run
```

別のターミナルから同じ商品を 2 回取得します。PowerShell では、以下の `curl` を `curl.exe` に読み替えてください。

```bash
curl -i http://localhost:8080/products/1
curl -i http://localhost:8080/products/1
```

どちらも 200 と `{"id":1,"name":"Notebook","priceYen":1200}` を返し、アプリのターミナルには `READ productId=1 priceYen=1200` が 2 行出ます。

### @Cacheable で再取得を省く

アプリを Ctrl+C で停止します。`src/main/resources/application.yaml` の既存の `spring` に、次の `cache` 設定を追加します。
`spring.application` がある場合は、同じ `spring` の下で `application` と `cache` を並べます。

```yaml title="キャッシュの設定"
spring:
  cache:
    type: simple
    cache-names: products
```

`type: simple` はアプリ内のメモリを使い、`cache-names` は利用するキャッシュの名前を指定します。
生成された `CacheApplication.java` に `EnableCaching` の import と `@EnableCaching` を追加します。

```java title="CacheApplication.java"
package dev.mikoto2000.springboot.cache;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cache.annotation.EnableCaching;

@SpringBootApplication
@EnableCaching
public class CacheApplication {

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

`ProductService.java` に `org.springframework.cache.annotation.Cacheable` を import し、既存の `getProduct` メソッドに次のアノテーションを追加します。

```java title="取得時のキャッシュ設定"
@Cacheable(cacheNames = "products", key = "#p0")
```

`#p0` はメソッドの第 1 引数です。このメソッドでは商品 ID の `id` がキーになります。
アプリを起動し直し、先ほどと同じ GET を 2 回実行します。両方の応答は 1200 円ですが、`READ productId=1 priceYen=1200` は 1 行だけ出ます。

### 更新後に古い価格が残ることを確認する

アプリを動かしたまま、商品 1 の価格を 1500 円に更新してから、もう一度取得します。

```bash
curl -i -X PUT 'http://localhost:8080/products/1/price?priceYen=1500'
curl -i http://localhost:8080/products/1
```

PUT は 204 を返し、ログに `UPDATE productId=1 priceYen=1500` が出ます。一方、直後の GET の本文は `priceYen: 1200` のままです。
GET で新たな `READ` が出ないことも確認します。保管場所には 1500 円が保存され、キャッシュには取得時の 1200 円が残っています。

### @CacheEvict で更新した商品のキャッシュを削除する

アプリを停止します。`ProductService.java` に `org.springframework.cache.annotation.CacheEvict` を import し、既存の `updatePrice` メソッドに次のアノテーションを追加します。

```java title="更新時のキャッシュ設定"
@CacheEvict(cacheNames = "products", key = "#p0")
```

`updatePrice(long id, int priceYen)` の第 1 引数は商品 ID です。取得時と同じキャッシュ名とキーを指定します。更新が成功すると、該当する項目が削除されます。
アプリを起動し直したら、**更新前の GET から**やり直します。最初の GET で 1200 円をキャッシュに入れてから価格を更新してください。

```bash
curl -i http://localhost:8080/products/1
curl -i -X PUT 'http://localhost:8080/products/1/price?priceYen=1500'
curl -i http://localhost:8080/products/1
curl -i http://localhost:8080/products/1
```

| 操作        | HTTP 応答    | 新たに出るログ                            |
| --------- | ---------- | ---------------------------------- |
| 更新前の GET  | 200、1200 円 | `READ productId=1 priceYen=1200`   |
| PUT       | 204        | `UPDATE productId=1 priceYen=1500` |
| 更新直後の GET | 200、1500 円 | `READ productId=1 priceYen=1500`   |
| 次の GET    | 200、1500 円 | 追加の `READ` なし                      |

発展として、商品 2 も更新前に GET してから商品 1 を更新し、商品 2 を再び GET します。商品 2 の `READ` が増えなければ、商品 2 のキャッシュは残っています。

### 後片付け

アプリを起動したターミナルで Ctrl+C を押して停止します。

## 座学で学ぶキャッシュ

### キャッシュヒットとキャッシュミス

同じキャッシュ名とキーで値が見つかると、キャッシュヒットです。`getProduct` の本体を実行せず、保存済みの値を返します。
値が見つからないキャッシュミスでは、メソッドが保管場所から商品を読み込み、その戻り値をキャッシュに保存します。
この演習では、Controller から Spring が管理する Service を呼び出すときに、アノテーションの処理が適用されます。
同じ Service 内から自分自身のメソッドを直接呼ぶ場合、既定のプロキシ方式ではアノテーションの処理が適用されません。

### 更新したキーを無効化する

`@CacheEvict` は指定したキーの項目を削除します。この演習のようにリクエストを順番に送る場合、次の GET が保管場所から新しい値を取り直し、その値をキャッシュに保存します。
取得と更新でキーがずれていると、古い項目が残ります。この演習では、両方で商品 ID をキーにしました。
ほかの処理から同じデータを書き換える設計では、その更新経路でもキャッシュの扱いを決める必要があります。

### 同時実行時の制約

`@Cacheable` と `@CacheEvict` は、保管場所の読み書きとキャッシュ操作の全体を排他制御しません。
同じ商品の GET と PUT が重なると、次の順序になる場合があります。

1. GET がキャッシュミスになり、保管場所から旧価格の 1200 円を読み取る。
2. PUT が保管場所を 1500 円に更新し、キャッシュを削除して 204 を返す。
3. 先ほどの GET が、読み取り済みの 1200 円をキャッシュへ保存する。

この後の GET は、保管場所が 1500 円でも 1200 円を返します。
この章のメモリキャッシュには TTL を設定していません。再更新による削除やアプリの再起動まで、古い値を返し続ける場合があります。
`@Cacheable(sync = true)` は同じキーの読み込み同士を調整する設定で、PUT との排他を保証するものではありません。

更新後の取得で必ず新しい値を返す必要がある場合は、キャッシュを使わない方法や、読み込み・更新・キャッシュ操作を含む単位で排他制御する方法を検討します。
アプリが複数ある場合は、各アプリ内のロックだけでは足りません。保存先のバージョンを使うなど、全インスタンスで整合性を保つ設計が必要です。
TTL は古い値が残る期間を制限する手段で、更新直後の整合性を保証するものではありません。

### 理解を確かめる

1. 同じ商品への 2 回目の GET で `READ` が増えない理由を説明する。
2. 価格更新の PUT が 204 を返したあとも、取得結果に古い価格が残った理由を説明する。
3. `@CacheEvict` を付けたあと、更新直後の GET とその次の GET で、`READ` の有無が異なる理由を説明する。

続編の [Redis キャッシュ入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/Redisキャッシュ入門.md) では、同じ商品価格 API を使い、Redis でキャッシュの削除と期限切れを確認します。

## 参考資料

- [Spring Boot 4.0 リファレンス — Caching](https://docs.spring.io/spring-boot/4.0/reference/io/caching.html)
- [Spring Framework リファレンス — Declarative Annotation-based Caching](https://docs.spring.io/spring-framework/reference/integration/cache/annotations.html)
