REST Tasarımı ve Idempotency

1
CREATE TABLE transfer_idempotency_key (
2
    customer_no    VARCHAR(20)  NOT NULL,
3
    idem_key       VARCHAR(64)  NOT NULL,
4
    request_hash   CHAR(64)     NOT NULL,   -- SHA-256 of the canonical request body
5
    transfer_id    UUID         NOT NULL,
6
    response_body  JSONB        NOT NULL,
7
    created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
8
    -- Keys are scoped per customer: two customers may pick the same UUID-shaped key.
9
    PRIMARY KEY (customer_no, idem_key)
10
);
11

12
-- A nightly job deletes rows past the retention window the API documents.
13
CREATE INDEX idx_transfer_idem_created_at ON transfer_idempotency_key (created_at);

1
@RestController
2
@RequestMapping("/transfers")
3
class TransferController {
4

5
    private final IdempotentTransfers transfers;
6

7
    TransferController(IdempotentTransfers transfers) {
8
        this.transfers = transfers;
9
    }
10

11
    @PostMapping
12
    ResponseEntity<TransferResponse> send(
13
            @AuthenticationPrincipal Jwt token,
14
            @RequestHeader("Idempotency-Key") @Size(min = 16, max = 64) String key,
15
            @Valid @RequestBody TransferRequest request) {
16

17
        // The customer comes from the verified token, never from the request body.
18
        String customerNo = token.getClaimAsString("customer_no");
19
        TransferResponse response = transfers.execute(customerNo, key, request);
20
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
21
    }
22
}

1
// Deliberately not @Transactional: a failed insert aborts a PostgreSQL transaction,
2
// so the duplicate check has to catch the error outside of it.
3
@Service
4
class IdempotentTransfers {
5

6
    private final FirstAttempt firstAttempt;
7
    private final IdempotencyKeys keys;
8

9
    IdempotentTransfers(FirstAttempt firstAttempt, IdempotencyKeys keys) {
10
        this.firstAttempt = firstAttempt;
11
        this.keys = keys;
12
    }
13

14
    TransferResponse execute(String customerNo, String key, TransferRequest request) {
15
        String hash = RequestHash.sha256(request);
16
        try {
17
            return firstAttempt.run(customerNo, key, hash, request);
18
        } catch (DuplicateKeyException alreadySeen) {
19
            // A concurrent twin waits on the primary key until the winner commits,
20
            // so by the time we get here the stored response is complete.
21
            StoredResponse stored = keys.find(customerNo, key).orElseThrow();
22
            if (!stored.requestHash().equals(hash)) {
23
                throw new IdempotencyKeyReusedException(key);
24
            }
25
            return stored.body();
26
        }
27
    }
28
}

1
// A separate bean so the call from IdempotentTransfers goes through the proxy
2
// and @Transactional applies.
3
@Service
4
class FirstAttempt {
5

6
    private final IdempotencyKeys keys;
7
    private final TransferService transfers;
8

9
    FirstAttempt(IdempotencyKeys keys, TransferService transfers) {
10
        this.keys = keys;
11
        this.transfers = transfers;
12
    }
13

14
    // Claim the key, move the money, store the answer: all three commit or none do.
15
    @Transactional
16
    TransferResponse run(String customerNo, String key, String hash, TransferRequest request) {
17
        UUID transferId = UUID.randomUUID();
18
        keys.claim(customerNo, key, hash, transferId);          // INSERT; throws on a duplicate
19
        TransferResponse response = transfers.post(transferId, customerNo, request);
20
        keys.storeResponse(customerNo, key, response);
21
        return response;
22
    }
23
}

1
// Same key, different transfer: the client has a bug, retrying will not help.
2
@ResponseStatus(HttpStatus.UNPROCESSABLE_ENTITY)
3
class IdempotencyKeyReusedException extends RuntimeException {
4

5
    IdempotencyKeyReusedException(String key) {
6
        super("idempotency key " + key + " was already used for a different transfer");
7
    }
8
}