備品購入申請を送信したら、画面にタイムアウトが出ました。DBには申請が保存されていたのに、利用者には結果が届いていません。そこで同じ申請をもう一度送ると、新しい行が増え、担当者には同じ依頼が2件届きます。
送信前に受付IDを決め、同じ申請を再送するときはIDを使い回します。DBはそのIDの行を1件だけ許可し、サーバーは登録済みの内容を読み直して、同じ申請か別の申請かを判断します。
この記事でわかること
- 同じPOSTが2回来たときに、先に登録した受付を返す方法
- 同じ受付IDで内容が異なる場合に、上書きせず409を返す理由
- 同時に来たPOSTを、DBの主キーとテストで確かめる方法
記事と同じコードを実行する
ZIPを展開し、JDK 17とMaven 3.9系で mvn test を実行します。Spring Boot本体、H2のDDL、テスト、pom.xml、READMEを収録。H2はテスト時にメモリ内で起動します。
送信結果が届かなかったとき、利用者は同じPOSTをもう一度送る
登録が済んでから通信が切れると、利用者はDBに保存されたか判断できません。ボタンを押せなくする工夫は連打を減らせますが、通信をやり直したときに前回の結果を返すにはサーバー側のルールが必要です。画面の再読み込みでPOSTが再実行される問題は、登録後にGETへ移すPRGで扱います。
今回の POST /applications は、受付IDとしてUUID、内容として件名を受け取ります。サーバーに届く前にUUIDを作っておき、結果が分からず同じ操作をやり直すなら、その値を保持して送ります。送信処理のたびにUUIDを作ると、サーバーからは別件に見えます。
同じ受付IDで送るPOSTのJSON例
{
"requestId": "00000000-0000-4000-8000-000000000001",
"title": "備品購入申請"
}同じIDなら件名も比べ、別内容には409を返す
| 受け取ったPOST | HTTP応答 | DBに残る受付 |
|---|---|---|
| 初めてのIDで「備品購入申請」 | 201。登録した受付を返す | 1件増える |
| 同じIDで「備品購入申請」 | 200。先に登録した受付を返す | 増えない |
| 同じIDで「別の申請」 | 409。先の件名は返さない | 増えず、元の件名も維持 |
| 別のIDで「備品購入申請」 | 201。別の受付を返す | 1件増える |
新規登録と再送でステータスは変えますが、同じIDと件名の再送で増える行はありません。200の本文は、要求から組み立て直す代わりに、先に保存した行を使います。409は、同じ受付IDがすでに別の内容に使われていることを呼び出し元へ伝えます。HTTPの409の定義も、現在のリソース状態との衝突を表しています。
件名だけが申請の内容なので、この例では保存済みの文字列と受信した文字列をそのまま比べます。実務で申請者や金額なども受付内容に含めるなら、どの項目が同じときに再送として扱うかを決めます。UUIDがあること自体に、登録済みの申請を読む権限はありません。
SELECTで0件を見ても、同じIDのINSERTを止めるのは主キー
登録前に検索して「見つからなければINSERT」と書くと、要求AとBが両方とも未登録を読んでから書き込みへ進めます。この競合を再現するテストでは、H2の接続IDが異なる二つのトランザクションを使います。両方が0件を確認して待ち合わせ、その後で同じ受付IDをINSERTします。
二つの接続がSELECTを終えてからINSERTへ進む。どちらが成功するかは決めず、DBには1行だけ残る。
受付IDを主キーにしているため、INSERTできるのは片方だけです。どちらが先かは決めず、成功と重複が1回ずつで、DBには1件だけ残ることをテストします。主キーを外すと、二つとも0件を見た後のINSERTが成功します。受付IDの重複を防ぐ判定を、各リクエストが先に読んだ件数へ任せないことがポイントです。
schema.sql(全文)
CREATE TABLE application_receipt (
request_id UUID NOT NULL,
title VARCHAR(120) NOT NULL,
CONSTRAINT pk_application_receipt PRIMARY KEY (request_id)
);このDDLで一意性を制約するのは request_id の主キーだけです。件名を一意にすると、別々の申請者が同じ件名を付けた場合まで衝突します。受付IDをDBで一意にして、同じ操作を再送した場合にだけ既存受付を探します。主キーとテーブルの定義はH2のCREATE TABLE資料にあります。
INSERTを終えてから重複を捕捉し、別トランザクションで読み直す
ReceiptService.java(全文)
package info.syachiku.receipts;
import java.util.Objects;
import java.util.UUID;
import org.springframework.dao.DuplicateKeyException;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.TransactionDefinition;
import org.springframework.transaction.support.TransactionTemplate;
@Service
public class ReceiptService {
private final JdbcTemplate jdbc;
private final TransactionTemplate transactions;
public ReceiptService(JdbcTemplate jdbc, PlatformTransactionManager transactionManager) {
this.jdbc = jdbc;
this.transactions = new TransactionTemplate(transactionManager);
this.transactions.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
}
public Registration register(UUID requestId, String title) {
var incoming = new Receipt(requestId, title);
try {
transactions.executeWithoutResult(status ->
jdbc.update("INSERT INTO application_receipt (request_id, title) VALUES (?, ?)",
requestId, title));
return new Registration(incoming, true);
} catch (DuplicateKeyException ex) {
var existing = Objects.requireNonNull(transactions.execute(status ->
jdbc.queryForObject("SELECT request_id, title FROM application_receipt WHERE request_id = ?",
(row, index) -> new Receipt(row.getObject("request_id", UUID.class),
row.getString("title")), requestId)));
if (!existing.title().equals(title)) {
throw new RequestIdConflict();
}
return new Registration(existing, false);
}
}
public record Receipt(UUID requestId, String title) {
}
public record Registration(Receipt receipt, boolean created) {
}
public static final class RequestIdConflict extends RuntimeException {
}
}register はまず TransactionTemplate 内でINSERTします。成功した場合はトランザクションがコミットされてから新規結果を返します。重複時は、例外をテンプレートの外で受け取ります。その時点で失敗したINSERT側のトランザクションはロールバック済みです。PROPAGATION_REQUIRES_NEW を指定しているので、後続のSELECTは別のトランザクションで実行されます。
読み直した件名が一致すれば、その保存済みの受付を返します。違えば RequestIdConflict を投げます。扱うDB例外は DuplicateKeyException だけです。たとえば接続できない失敗を409へ変換すると、呼び出し元が申請内容の問題だと判断してしまいます。別の一意制約をこのINSERTに追加したら、どの制約に違反したかを区別する必要もあります。Spring FrameworkのTransactionTemplate資料で、処理範囲の指定を確認できます。
Controllerは登録結果を201・200・409に変換する
ReceiptController.java(全文)
package info.syachiku.receipts;
import java.util.UUID;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
@RestController
public class ReceiptController {
private final ReceiptService service;
public ReceiptController(ReceiptService service) {
this.service = service;
}
@PostMapping("/applications")
public ResponseEntity<ReceiptService.Receipt> register(@Valid @RequestBody ApplicationRequest request) {
try {
var result = service.register(request.requestId(), request.title());
var status = result.created() ? HttpStatus.CREATED : HttpStatus.OK;
return ResponseEntity.status(status).body(result.receipt());
} catch (ReceiptService.RequestIdConflict ex) {
throw new ResponseStatusException(HttpStatus.CONFLICT, "受付IDが別の申請に使われています");
}
}
public record ApplicationRequest(@NotNull UUID requestId, @NotBlank @Size(max = 120) String title) {
}
}@Valid でIDの必須と件名の空白・長さを検証します。入力不備は400で、Serviceを呼ぶ前に止まります。Serviceが返した created が真なら201、既存受付なら200とし、同じIDで内容が異なる場合は409へ変えます。この409には、衝突した先の件名を入れていません。
HTTP応答とDBの件数を、同じテストで照合する
ZIPを展開し、pom.xml のある場所で mvn test を実行します。JDK 17、Maven 3.9系、Spring Boot 3.5.16、H2 2.3.232で試しています。HTTPの入口はMockMvcを使い、INSERTとSELECTは実際のH2へ送ります。1回目が201で2回目が200でも、DBに2行あれば対策できていません。HTTP応答のほか、件数と保持された件名も確認します。
通常の再送、別内容の409、別ID、入力不備に加え、同じPOSTを二つのスレッドから開始する試験と、別々の接続が先に0件を読む競合の試験があります。並行POSTでは201と200の順番を決めず、応答本文の一致と1行を確認します。後者ではH2の SESSION_ID() を比較し、両方の接続が0件を読んでからINSERTへ進んだことを待ち合わせで保証します。
ReceiptRegistrationTest.java(全文)
package info.syachiku.receipts;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.Callable;
import java.util.concurrent.CyclicBarrier;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
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.dao.DuplicateKeyException;
import org.springframework.http.MediaType;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import org.springframework.transaction.PlatformTransactionManager;
import org.springframework.transaction.support.TransactionTemplate;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@SpringBootTest
@AutoConfigureMockMvc
class ReceiptRegistrationTest {
private static final UUID FIRST = UUID.fromString("00000000-0000-4000-8000-000000000001");
private static final UUID SECOND = UUID.fromString("00000000-0000-4000-8000-000000000002");
private static final String TITLE = "備品購入申請";
private static final String OTHER_TITLE = "別の申請";
@Autowired
private MockMvc mvc;
@Autowired
private JdbcTemplate jdbc;
@Autowired
private PlatformTransactionManager transactionManager;
@BeforeEach
void clearReceipts() {
jdbc.update("DELETE FROM application_receipt");
}
@Test
void sameIdAndTitleReturnsTheStoredReceipt() throws Exception {
var first = send(FIRST, TITLE).andExpect(status().isCreated())
.andExpect(jsonPath("$.requestId").value(FIRST.toString()))
.andExpect(jsonPath("$.title").value(TITLE)).andReturn().getResponse();
var replay = send(FIRST, TITLE).andExpect(status().isOk()).andReturn().getResponse();
assertEquals(first.getContentAsString(), replay.getContentAsString());
assertEquals(1, countReceipts());
}
@Test
void sameIdAndDifferentTitleReturnsConflictAndPreservesOriginal() throws Exception {
send(FIRST, TITLE).andExpect(status().isCreated());
var conflict = send(FIRST, OTHER_TITLE).andExpect(status().isConflict()).andReturn().getResponse();
assertFalse(conflict.getContentAsString().contains(TITLE));
assertEquals(TITLE, jdbc.queryForObject(
"SELECT title FROM application_receipt WHERE request_id = ?", String.class, FIRST));
assertEquals(1, countReceipts());
}
@Test
void differentIdsAreSeparateReceiptsEvenWithSameTitle() throws Exception {
send(FIRST, TITLE).andExpect(status().isCreated());
send(SECOND, TITLE).andExpect(status().isCreated());
assertEquals(2, countReceipts());
}
@Test
void invalidRequestIsRejectedBeforeInsert() throws Exception {
send(FIRST, " ").andExpect(status().isBadRequest());
assertEquals(0, countReceipts());
}
@Test
void concurrentIdenticalPostsCreateOneRowAndReturnTheSameReceipt() throws Exception {
var start = new CyclicBarrier(2);
Callable<Reply> sendPost = () -> {
start.await(5, TimeUnit.SECONDS);
var response = send(FIRST, TITLE).andReturn().getResponse();
return new Reply(response.getStatus(), response.getContentAsString());
};
var replies = runTogether(sendPost);
assertEquals(List.of(200, 201), replies.stream().map(Reply::status).sorted().toList());
assertEquals(replies.get(0).body(), replies.get(1).body());
assertEquals(1, countReceipts());
}
@Test
void bothConnectionsCanSeeNoRowBeforeOnlyOneInsertSucceeds() throws Exception {
var bothRead = new CyclicBarrier(2);
var transactions = new TransactionTemplate(transactionManager);
Callable<Attempt> checkThenInsert = () -> {
int[] sessionId = new int[1];
try {
transactions.executeWithoutResult(status -> {
sessionId[0] = jdbc.queryForObject("SELECT SESSION_ID()", Integer.class);
assertEquals(0, countReceipts());
await(bothRead);
jdbc.update("INSERT INTO application_receipt (request_id, title) VALUES (?, ?)", FIRST, TITLE);
});
return new Attempt(sessionId[0], "inserted");
} catch (DuplicateKeyException ex) {
return new Attempt(sessionId[0], "duplicate");
}
};
var attempts = runTogether(checkThenInsert);
assertEquals(2, attempts.stream().map(Attempt::sessionId).distinct().count());
assertEquals(List.of("duplicate", "inserted"),
attempts.stream().map(Attempt::result).sorted().toList());
assertEquals(1, countReceipts());
}
private ResultActions send(UUID requestId, String title) throws Exception {
String json = """
{"requestId":"%s","title":"%s"}
""".formatted(requestId, title);
return mvc.perform(post("/applications").contentType(MediaType.APPLICATION_JSON).content(json));
}
private long countReceipts() {
return jdbc.queryForObject("SELECT COUNT(*) FROM application_receipt", Long.class);
}
private static void await(CyclicBarrier barrier) {
try {
barrier.await(5, TimeUnit.SECONDS);
} catch (InterruptedException ex) {
Thread.currentThread().interrupt();
throw new IllegalStateException(ex);
} catch (Exception ex) {
throw new IllegalStateException(ex);
}
}
private static <T> List<T> runTogether(Callable<T> work) throws Exception {
var workers = Executors.newFixedThreadPool(2);
try {
var first = workers.submit(work);
var second = workers.submit(work);
return List.of(first.get(10, TimeUnit.SECONDS), second.get(10, TimeUnit.SECONDS));
} finally {
workers.shutdownNow();
}
}
private record Reply(int status, String body) {
}
private record Attempt(int sessionId, String result) {
}
}ReceiptApplication.java(全文)
package info.syachiku.receipts;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class ReceiptApplication {
public static void main(String[] args) {
SpringApplication.run(ReceiptApplication.class, args);
}
}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>info.syachiku</groupId>
<artifactId>spring-post-idempotency-sample</artifactId>
<version>1.0.0</version>
<properties>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</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>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>修正版は6件成功します。別の場所にZIPを展開し、schema.sql から CONSTRAINT pk_application_receipt PRIMARY KEY (request_id) と、その前の行末カンマを取り除くと、同じ mvn test で4件失敗します。再送は200のはずが201になり、先読み競合では二つのINSERTが成功します。試したら制約を元に戻し、6件成功に戻ることを確認します。
主キーがある場合と外した場合のログ抜粋
修正版の mvn test
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0
主キーを外した再現版の mvn test
[ERROR] ReceiptRegistrationTest.sameIdAndTitleReturnsTheStoredReceipt:54 Status expected:<200> but was:<201>
[ERROR] ReceiptRegistrationTest.concurrentIdenticalPostsCreateOneRowAndReturnTheSameReceipt:95 expected: <[200, 201]> but was: <[201, 201]>
[ERROR] Tests run: 6, Failures: 4, Errors: 0, Skipped: 0実運用では、誰のIDかと再送に答える期間も決める
レビューコメント例「タイムアウト時、再送するクライアントは前回のUUIDを持っていますか。別利用者が同じUUIDを知った場合にも先の受付を読めてしまうので、認証した利用者やテナントでキーを分け、既存行を返す前に参照権限を確認しましょう。」
この教材では一つの受付を前提にUUIDを単独のキーとして使い、登録行は消しません。たとえばテナントごとに受付を管理するなら、認証情報から得たテナントと受付IDの組を一意にし、INSERTも再取得もその組で行います。期限後に登録行を消す運用なら、どの期間の再送を同じ受付として扱うかも契約に含めます。行を消した後に同じUUIDを受け付けると、新しいINSERTが成立し得ます。
REQUIRES_NEW で確定した受付は、呼び出し元の既存トランザクションが後からロールバックしても残るため、受付と業務データを一緒に確定させる処理へ組み込むときは、どこまでを一つのトランザクションに含めるか見直します。
サンプルのH2はメモリ内にあるため、アプリを終了すると消えます。実運用で別のDBへ置き換えるときは、使うドライバーが返す例外、同時書き込み時の待機やタイムアウト、ロールバック後に読み直せる条件を実際のDBで確かめます。受付と同時にメール送信などを行う場合も、その処理を再送のたびに実行してよいかを別に決めます。
提出前に、同じIDの再送と衝突を確認する
- 同じ操作を再送するとき、最初の受付IDが再利用される。
- DBに主キーまたは用途に合う一意制約があり、並行実行でも1行だけ残る。
- 同じ内容の再送は保存済みの受付を返し、異なる内容は409で元の行を残す。
- 重複を判定して読み直す際、別のDB障害や権限エラーと混同しない。
- 実運用では、参照権限と再送として受け付ける期間を定める。
POSTとステータスコードの役割から整理したいときは、『Webを支える技術』のHTTPメソッドとステータスコードを扱う章が参考になります。画面の動きと、サーバーが201・200・409を返す契約を分けて読めます。
Webを支える技術
HTTP・URI・RESTを、Webアプリ開発の土台から理解する。
RequestParamやRequestBodyの暗記だけでは見えにくい、Web通信の基本原則を整理できます。
- HTTPの仕組みから理解したい
- RESTやURIの設計意図を学びたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
POSTを再送しても同じ申請を増やさないために、送信前に決めた受付IDを再利用し、DBの主キーで1件に制限します。重複後に保存済みの件名を比べて、同じなら既存受付、別なら409を返します。2回のHTTP応答と、DBに残った1件をセットで確認します。



