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

概要

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

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

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

事前準備

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

Spring Initializr で新しいプロジェクトを作成します。 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 に次の依存関係を追加します。

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

触って学ぶキャッシュ

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

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

Product.java
package dev.mikoto2000.springboot.cache;

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

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

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 つのメソッドにキャッシュのアノテーションを付けます。

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 です。

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 を使います。

./mvnw spring-boot:run

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

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 を並べます。

キャッシュの設定
spring:
  cache:
    type: simple
    cache-names: products

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

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 メソッドに次のアノテーションを追加します。

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

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

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

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

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 メソッドに次のアノテーションを追加します。

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

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

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 応答新たに出るログ
更新前の GET200、1200 円READ productId=1 priceYen=1200
PUT204UPDATE productId=1 priceYen=1500
更新直後の GET200、1500 円READ productId=1 priceYen=1500
次の GET200、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 キャッシュ入門 では、同じ商品価格 API を使い、Redis でキャッシュの削除と期限切れを確認します。

参考資料