この記事でわかること
Spring Bootで配送メモの編集画面を2つ開くと、@Version が付いていても、保存時に画面の版を確認しなければ先に保存した内容を上書きできます。版を比較してHTTP 409を返す修正と、比較後に別の処理が割り込んだときのJPAの動作を確かめます。


注文システムの配送メモを例にします。担当AとBが同じ配送メモを開いたとき、両方の画面は「指定なし・版0」です。Aが「午前に配達」を保存してから、Bが古い画面で「置き配」を送ります。開発担当が実装を確認する観点は、Bに何を表示するかと、AのメモがDBに残るかの2つです。
実行サンプル
修正前・修正後のHTTP、入力エラー、DBの競合をJUnit 7件で確認します。JDK 17とMaven 3.9系を用意し、ZIPを展開したフォルダで mvn clean test を実行してください。テスト対象・テストコード・依存設定はZIPと本文に全文があり、外部のDBや起動中のHTTPサーバーは不要です。
再現する。版0の画面からのPUTが200になり、Aのメモが消える
読み取りの GET /shipping-notes/{id} が返すJSONには、id、version、memo が入ります。画面は編集開始時の version を保持します。初期値が版0なら、AもBも保存リクエストには版0を入れます。下の手順では、Aの保存を待ってからBが送るので、再現に同時クリックや待ち時間の調整は要りません。
- 2画面でGET画面A・Bともに「指定なし」
version = 0 - AのPUTが先に完了DBに「午前に配達」
version = 1 - Bが版0のままPUT「置き配」を送信
version = 0
修正前 200DBは「置き配」・版2
修正後 409DBは「午前に配達」・版1
修正前の動きは、テストソースにだけ含めた PUT /before/shipping-notes/{id} で再現します。このハンドラーは入力の version を受け取りますが、保存時の findById() で取得したEntityへメモを設定するだけです。BのPUTが始まる時点でDBは版1なので、Bが持っていた版0は更新の判断に使われず、版1から版2へ更新できます。
package example.shipping;
import jakarta.validation.Valid;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
class BeforeShippingNotesController {
private final ShippingNoteRepository notes;
BeforeShippingNotesController(ShippingNoteRepository notes) {
this.notes = notes;
}
@PutMapping("/before/shipping-notes/{id}")
@Transactional
ShippingNoteService.NoteView update(@PathVariable long id,
@RequestBody @Valid ShippingNotesController.UpdateNote request) {
ShippingNote note = notes.findById(id).orElseThrow();
note.changeMemo(request.memo());
notes.flush();
return ShippingNoteService.NoteView.from(note);
}
}調査で最初に見るのは、失敗した操作を含むPUTのリクエストと応答、その直後の対象行です。今回ならBが送ったJSONに "version":0 があり、応答の版が2で、DBも「置き配」です。リクエストに値があるだけでは版チェックをしている証拠になりません。逆に版が送られていないなら、先にGETの応答、画面での保持、PUTのリクエスト作成を追います。画面の不具合とサーバーの比較漏れを分けると修正する担当も決まります。
画面の版とJPAの版は、比較する時点が違う
@Version が更新時に確認するのは、JPAがEntityを読み込んだときの版です。サンプルの修正前では、Bが編集を始めたのは版0ですが、BのPUTでJPAが読み直したEntityは版1です。Hibernateは概念上 WHERE id = ? AND version = ? の版条件に版1を使います。DBも版1なので更新できます。JPAに渡していない画面の版0を、Hibernateが推測することはありません。
今回の対策は2か所で別々の値を確認します。Serviceが画面の版と読み直したEntityの版を照合すれば、Aの保存が先に完了している場合にBを止められます。その比較が通った直後に別の処理が先にコミットした場合は、JPAが読んだ版とSQL実行時のDBの版が違います。今度は @Version による更新条件で衝突を検出します。どちらも「先に入った変更を保護する」という結果に結びつきます。
運用ログで「上書きされた」相談を受けたら、注文IDと操作順、両方が送った版、保存後の版を揃えます。配送メモ全文をログへ書くと住所や電話番号が含まれる可能性があるため、調査用に残すならID・版・結果コードを先に検討します。障害調査で応答が成功していることだけを確認すると、先に保存した内容が失われた点を見逃します。
GETで読んだ版をPUTに渡し、Serviceで一致を確かめる
Controllerの UpdateNote は版を Long で受け取り、@NotNull と @PositiveOrZero を付けます。このサンプルは版0から始まるため、0は有効です。プリミティブの long で受けて欠落と0を区別できない設定だと、未指定の保存が初版の照合を通るおそれがあります。Long にして欠落や null が @Valid でHTTP 400になることを、本文のテストで確認します。
package example.shipping;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.PositiveOrZero;
import jakarta.validation.constraints.Size;
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.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/shipping-notes")
class ShippingNotesController {
private final ShippingNoteService service;
ShippingNotesController(ShippingNoteService service) {
this.service = service;
}
@GetMapping("/{id}")
ShippingNoteService.NoteView get(@PathVariable long id) {
return service.get(id);
}
@PutMapping("/{id}")
ShippingNoteService.NoteView update(@PathVariable long id, @RequestBody @Valid UpdateNote request) {
return service.update(id, request.version(), request.memo());
}
record UpdateNote(
@NotNull @PositiveOrZero Long version,
@NotBlank @Size(max = 200) String memo) {
}
}Serviceの update() は、一つのトランザクションでEntityを検索し、Objects.equals() で版を比較し、一致した場合だけ changeMemo() を呼びます。リクエストの版は比較に使います。Entityの版の設定と更新はJPAに任せるため、ShippingNote に版のsetterはありません。
package example.shipping;
import java.util.Objects;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.server.ResponseStatusException;
@Service
class ShippingNoteService {
private final ShippingNoteRepository notes;
ShippingNoteService(ShippingNoteRepository notes) {
this.notes = notes;
}
@Transactional(readOnly = true)
NoteView get(long id) {
return NoteView.from(find(id));
}
@Transactional
NoteView update(long id, Long expectedVersion, String memo) {
ShippingNote note = find(id);
if (!Objects.equals(note.getVersion(), expectedVersion)) {
throw new StaleShippingNoteException();
}
note.changeMemo(memo);
notes.flush();
return NoteView.from(note);
}
private ShippingNote find(long id) {
return notes.findById(id)
.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
}
record NoteView(Long id, Long version, String memo) {
static NoteView from(ShippingNote note) {
return new NoteView(note.getId(), note.getVersion(), note.getMemo());
}
}
static class StaleShippingNoteException extends RuntimeException {
}
}変更した後に notes.flush() するのは、SQLを発行してからレスポンス用の NoteView を作り、実際に更新された版を返すためです。flushはトランザクションの確定とは別の段階です。ここではServiceメソッドを抜けるときにSpringがコミットし、Controllerはその完了後に結果を返します。メモが同じでEntityに変更がないケースは、H2のこのサンプルで200と版0のままになることも確かめています。画面は「保存するたび1増える」と計算せず、APIの応答に含まれる版を採用します。
既存のAPIに版を後から導入するときは、GETのレスポンスだけ先に拡張できても、版を必須にしたPUTへ既存クライアントが追随するとは限りません。社内画面と外部の連携を同じURLで受けている場合は、どのクライアントが版を返せるかを確認し、切り替え方法を決めます。「旧画面だけ版なしで通す」とした場合は、上書きが起こり得る経路が残ります。
版の衝突は409。入力の欠落は400
Serviceが版の不一致で投げる StaleShippingNoteException と、JPAの更新競合をSpringが変換した OptimisticLockingFailureException は、ShippingNoteErrorHandler で同じHTTP 409と {"code":"STALE_SHIPPING_NOTE"} に変換します。メモを再読込して編集し直せるというAPI契約を共通にしつつ、サーバーではどちらの例外が起きたか追跡できます。Adviceはこのサンプルの ShippingNotesController に範囲を限定します。
package example.shipping;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice(assignableTypes = ShippingNotesController.class)
class ShippingNoteErrorHandler {
@ExceptionHandler({
ShippingNoteService.StaleShippingNoteException.class,
OptimisticLockingFailureException.class
})
@ResponseStatus(HttpStatus.CONFLICT)
ConflictResponse conflict() {
return new ConflictResponse("STALE_SHIPPING_NOTE");
}
record ConflictResponse(String code) {
}
}409を受けた画面では、自分が入力した「置き配」を保持したままGETで最新の「午前に配達」を取得し、どちらを反映するか利用者が決められる設計にします。取得した版1だけを差し替えて自動再送すると、Bの古い入力でAのメモを上書きするため、今回の要件と矛盾します。画面側のこの処理はサンプルに含まれず、テストはAPIの応答とDBに残った内容を確認します。
400の利用者対応は異なります。version が欠落、null、負数なら更新処理へ進まず、送信形式を直してから再試行します。DBに対象がなければServiceは404を返す実装です。更新版をJSONで送る今回の契約では、現在の状態と衝突したときに409を返します。If-Match を用いた別の契約では、前提条件を満たさないときの412を設計してください。HTTP 409の仕様 · HTTP 412の仕様
テストはHTTPと、更新後のDBを両方確かめる
ShippingNoteUpdateTest は、MockMvcでGETとPUTを呼び、各ケースで一時DBに残ったメモと版を assertSaved() で確認します。たとえば409だけを検証すると、誤った例外ハンドリングで応答を409にしながらDBを変更した実装が見逃されます。修正前・修正後で初期メモもAとBの入力も同じにし、違うのは版を照合するかどうかに絞りました。
| 操作 | 確認する結果 | DBに残るメモ・版 |
|---|---|---|
| 版0のBを受け入れる旧実装 | HTTP 200 | 置き配・版2 |
| 版0のBを拒否する修正版 | HTTP 409とエラーコード | 午前に配達・版1 |
| 版の欠落・null・負数 | 3入力ともHTTP 400 | 指定なし・版0 |
| 同じメモを保存 | HTTP 200 | 指定なし・版0 |
| 版0を読んだ2トランザクション | Bのflushで競合例外 | 午前に配達・版1 |
最後のケースは、二つのトランザクションがどちらも版0を読み取ってから競合する検証です。先にB側でEntityを読みます。内側のA側は REQUIRES_NEW で別トランザクションを開始し、版0を読んで版1へ更新し、そのトランザクションをコミットします。Bが元のトランザクションに戻ってからflushすると、BのEntityは版0のままで、Springの OptimisticLockingFailureException が出ます。ここではControllerを通さず、Repository経由のflushとDBに残る状態を確かめます。SpringのTransactionTemplate · Hibernateの楽観ロック
ShippingNoteUpdateTest.javaの全文を見る
package example.shipping;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.util.Map;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.TransactionDefinition;
import org.springframework.transaction.support.TransactionTemplate;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.put;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@SpringBootTest(properties = {
"spring.jpa.hibernate.ddl-auto=create-drop",
"spring.jpa.open-in-view=false"
})
@AutoConfigureMockMvc
@Import(BeforeShippingNotesController.class)
class ShippingNoteUpdateTest {
@Autowired
private MockMvc mvc;
@Autowired
private ObjectMapper json;
@Autowired
private ShippingNoteRepository notes;
@Autowired
private PlatformTransactionManager transactions;
private long id;
@BeforeEach
void newShippingNote() {
id = notes.saveAndFlush(new ShippingNote("指定なし")).getId();
}
@Test
void ignoringRequestVersionOverwritesTheFirstEdit() throws Exception {
long screenA = openScreen();
long screenB = openScreen();
save("/before", screenA, "午前に配達")
.andExpect(status().isOk())
.andExpect(jsonPath("$.version").value(1))
.andExpect(jsonPath("$.memo").value("午前に配達"));
save("/before", screenB, "置き配")
.andExpect(status().isOk())
.andExpect(jsonPath("$.version").value(2))
.andExpect(jsonPath("$.memo").value("置き配"));
assertSaved("置き配", 2);
System.out.println("before B=200 savedMemo=置き配 savedVersion=2");
}
@Test
void checkingRequestVersionRejectsTheStaleEdit() throws Exception {
long screenA = openScreen();
long screenB = openScreen();
save("", screenA, "午前に配達")
.andExpect(status().isOk())
.andExpect(jsonPath("$.version").value(1))
.andExpect(jsonPath("$.memo").value("午前に配達"));
save("", screenB, "置き配")
.andExpect(status().isConflict())
.andExpect(jsonPath("$.code").value("STALE_SHIPPING_NOTE"));
assertSaved("午前に配達", 1);
System.out.println("after B=409 savedMemo=午前に配達 savedVersion=1");
}
@ParameterizedTest
@ValueSource(strings = {
"{\"memo\":\"置き配\"}",
"{\"memo\":\"置き配\",\"version\":null}",
"{\"memo\":\"置き配\",\"version\":-1}"
})
void rejectingAnInvalidVersionLeavesTheInitialMemo(String body) throws Exception {
mvc.perform(put("/shipping-notes/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.content(body.getBytes(StandardCharsets.UTF_8)))
.andExpect(status().isBadRequest());
assertSaved("指定なし", 0);
System.out.println("invalid version=400 savedMemo=指定なし savedVersion=0");
}
@Test
void anUnchangedMemoKeepsTheCurrentVersion() throws Exception {
save("", 0, "指定なし")
.andExpect(status().isOk())
.andExpect(jsonPath("$.version").value(0));
assertSaved("指定なし", 0);
}
@Test
void jpaRejectsAnUpdateAfterAnotherTransactionHasCommitted() {
TransactionTemplate screenB = new TransactionTemplate(transactions);
TransactionTemplate screenA = new TransactionTemplate(transactions);
screenA.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
assertThrows(OptimisticLockingFailureException.class, () ->
screenB.executeWithoutResult(b -> {
ShippingNote stale = notes.findById(id).orElseThrow();
assertEquals(0L, stale.getVersion());
screenA.executeWithoutResult(a -> {
ShippingNote fresh = notes.findById(id).orElseThrow();
assertEquals(0L, fresh.getVersion());
fresh.changeMemo("午前に配達");
notes.flush();
assertEquals(1L, fresh.getVersion());
});
stale.changeMemo("置き配");
notes.flush();
}));
assertSaved("午前に配達", 1);
System.out.println("flush conflict=OptimisticLockingFailureException savedMemo=午前に配達 savedVersion=1");
}
private long openScreen() throws Exception {
byte[] body = mvc.perform(get("/shipping-notes/{id}", id))
.andExpect(status().isOk())
.andExpect(jsonPath("$.version").value(0))
.andReturn().getResponse().getContentAsByteArray();
return json.readTree(body).get("version").asLong();
}
private ResultActions save(String prefix, long version, String memo) throws Exception {
return mvc.perform(put(prefix + "/shipping-notes/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.content(json.writeValueAsBytes(Map.of("version", version, "memo", memo))));
}
private void assertSaved(String memo, long version) {
ShippingNote saved = notes.findById(id).orElseThrow();
assertEquals(memo, saved.getMemo());
assertEquals(version, saved.getVersion());
}
}ZIPを展開して mvn clean test を実行します。次は成功したテストが出す観察値の抜粋です。版不正の行は3件同じ結果なので、1行にまとめています。テストの実行順には依存しません。
before B=200 savedMemo=置き配 savedVersion=2
after B=409 savedMemo=午前に配達 savedVersion=1
invalid version=400 savedMemo=指定なし savedVersion=0
flush conflict=OptimisticLockingFailureException savedMemo=午前に配達 savedVersion=1修正が効いているか確認するには、コピーしたサンプルで ShippingNoteService.update() の版の条件を外し、mvn -Dtest=ShippingNoteUpdateTest#checkingRequestVersionRejectsTheStaleEdit test を実行します。Bの応答は409から200になり、テストが失敗します。DBの競合テストは独立しているので、API側で比較を外した影響とJPAの更新条件を分けて見られます。
レビューでは「どの版を比べ、失敗後に何が残るか」を説明する
管理画面の改修で、別々のチームが画面とAPIを実装することがあります。レビュー時に「楽観ロック対応済み」とだけ書くと、誰が編集開始時の版を保持するのか、同じ版で競合したときにどこで検出されるかが分かりません。対象の行とリクエスト名を使って、次のように確認できます。
GETの
versionは、画面を開いた時点の値をPUTへ渡していますか。版0を持つBが、Aの保存後にPUTしたとき、409とSTALE_SHIPPING_NOTEが返り、DBに「午前に配達」と版1が残るテストを見せてください。
一方、更新する行を業務ごとに分離できる場合は、同じ行へ全項目を保存する設計自体も見直せます。この例は同じ配送メモ1件の上書きを止める要件です。別々の項目なら利用者の入力をどうマージするか、複数行で在庫数を守るなら何を一つのトランザクションにまとめるか、対象ごとに判断します。JPQLの一括更新やSQLを直接使う経路があれば、Entityをロードする今回の処理と同じ版条件になると仮定せず、SQLの条件・版更新・更新件数を個別にレビューします。Jakarta Persistenceの版と一括更新の仕様
- GETの版とPUTで送る版を、2画面を開いた状態で確認した。
- 同じ版でメモが変わると更新でき、古い版のPUTではHTTP 409の後も先に保存したメモと版が残る。
- 版の欠落・null・負数を400にし、エラー後の行が変わっていないことを確かめた。
- HTTPの再現とは別に、同じ版を読んだ2トランザクションで後からflushした側が失敗することを確かめた。
- 競合後に古い入力を無条件に再送しないよう、画面の担当と409の扱いを共有した。
サンプルの残りのファイル
配送メモのEntity、Repository、テスト用のSpring Boot設定、Mavenの依存定義を以下で開けます。修正前のController、修正後の実装、テストクラスは対応する章に全文を置きました。すべてをまとめて動かす場合は、冒頭の配布枠のZIPを使ってください。
ShippingNote.javaの全文を見る
package example.shipping;
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.Version;
@Entity
class ShippingNote {
@Id
@GeneratedValue
private Long id;
@Version
private Long version;
@Column(nullable = false, length = 200)
private String memo;
protected ShippingNote() {
}
ShippingNote(String memo) {
this.memo = memo;
}
Long getId() {
return id;
}
Long getVersion() {
return version;
}
String getMemo() {
return memo;
}
void changeMemo(String newMemo) {
memo = newMemo;
}
}ShippingNoteRepository.javaの全文を見る
package example.shipping;
import org.springframework.data.jpa.repository.JpaRepository;
interface ShippingNoteRepository extends JpaRepository<ShippingNote, Long> {
}ShippingNoteApplication.javaの全文を見る
package example.shipping;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
class ShippingNoteApplication {
}pom.xmlの全文を見る
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>example</groupId>
<artifactId>spring-jpa-optimistic-lock</artifactId>
<version>1.0.0</version>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
</exclusion>
<exclusion>
<groupId>org.mockito</groupId>
<artifactId>mockito-junit-jupiter</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
</project>Spring Data JPAでEntityをいつ読み、トランザクション内でどこまで変更を確定するかを整理したいときは、『Spring徹底入門 第2版』のデータアクセス・トランザクションの説明が役立ちます。配送メモのAPIとテストはこの記事のサンプルで試せます。
Spring徹底入門 第2版
アプリを作った後に、DIやDB更新の仕組みを調べる。
DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。
- Springで小さなWebアプリを作ったことがある
- DIやトランザクションの仕組みを確認したい
Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ。画面の版を比較し、DBに先の編集を残す
画面のGETで取得した版をPUTまで持ち、Serviceが保存時の版と一致するかを判定します。一致した後の競合は @Version が検出します。まず同じ配送メモを2画面で開き、Aの保存後にBの古い版を送ってください。409だけで終わらせず、DBにAのメモと版1が残っていれば、上書きを防げたことまで説明できます。



