Đến nội dung chính
notes.vinhnq.com

Tìm kiếm

System DesignSenior19 phút đọc

Idempotency phần 1: at-least-once, unique constraint và Idempotency-Key trên PostgreSQL

Ôn 14 thẻ
Trong bài này

Cụm bài Idempotency: 1. Khái niệm, API và database · 2. Kafka và IPN cổng thanh toán

Ở mỗi chặng của hệ thống phân tán, bên gửi không nhận được xác nhận thì gửi lại, nên một việc có thể tới nơi hai, ba lần (at-least-once). Idempotency là thuộc tính giúp “tới nhiều lần” cho kết quả như “tới một lần”. Đọc xong, bạn chọn được cách chống trùng ở tầng API và database, và cài được Idempotency-Key chịu được request đồng thời.

Phần 2 lo Kafka và IPN cổng thanh toán. Hợp đồng API (header, status code) ở bài Async job, Idempotency-Key và tài liệu API.

1. Vì sao không có “exactly-once” miễn phí

Ý chính: bên gửi không biết request bị mất hay chỉ response bị mất, nên buộc phải retry, và retry có thể làm trùng. Lối ra duy nhất là bên nhận nhận ra lần thứ hai và không làm lại.

Mức Cách làm Hậu quả
At-most-once Gửi một lần, không retry Có thể mất
At-least-once Retry tới khi nhận được ack Có thể trùng
Exactly-once At-least-once + bên nhận khử trùng Phải tự xây
sequenceDiagram
    participant C as Client
    participant S as Payment service
    participant D as Database
    C->>S: POST /payments (lần 1)
    S->>D: trừ tiền, COMMIT
    S--xC: response bị mất (timeout)
    Note over C: Không biết đã trừ tiền hay chưa
    C->>S: POST /payments (retry)
    S->>D: trừ tiền lần nữa?

Nên người ta nói “exactly-once processing” (hay effectively-once), không nói “exactly-once delivery”.

Phía bên gửi, retry sao cho không thành retry storm (chỉ retry lỗi tạm thời, giới hạn số lần, backoff có jitter, circuit breaker khi bên kia đã chết hẳn) có ở Timeout, retry và circuit breaker. Ở góc chọn giao thức, bài giao tiếp đồng bộ REST và gRPC dùng cùng bảng mức bảo đảm này và chỉ bật retry của gRPC cho method idempotent.

Retry đến từ cả reverse proxy, và giới hạn exactly-once của Kafka

Reverse proxy cũng retry: Nginx với proxy_next_upstream chuyển request sang backend khác khi backend đầu lỗi kết nối hoặc timeout. Từ 1.9.13 nó không retry POST/PATCH đã gửi đi.

Nhưng nếu ai đó bật proxy_next_upstream error timeout non_idempotent;, một POST /orders đã ghi DB xong, chỉ timeout ở bước trả response, sẽ được gửi lại và tạo đơn lần hai, mà client không hề retry. Chi tiết và cách giới hạn số lần thử ở bài Reverse proxy với Nginx.

2. Ba cách làm một thao tác idempotent

Ý chính: viết lệnh dạng “đặt trạng thái đích” thay vì “cộng thêm”; để unique constraint của DB làm trọng tài; hoặc ghi “đã xử lý” vào bảng dedupe trong cùng transaction với nghiệp vụ.

2.1. Idempotent tự nhiên: viết lệnh dạng “đặt giá trị”, không phải “thay đổi giá trị”

-- Không idempotent: chạy lại là cộng thêm lần nữa
UPDATE account SET balance = balance + 100000 WHERE id = 'A';

-- Idempotent: đặt trạng thái đích, có điều kiện chuyển trạng thái
UPDATE booking SET status = 'PAID', paid_at = now()
WHERE id = 981 AND status = 'PENDING_PAYMENT';
-- Lần hai: 0 dòng bị ảnh hưởng, không có gì thay đổi

Câu thứ hai là conditional update theo state machine (chỉ cho chuyển PENDING_PAYMENT → PAID). Số dòng bị ảnh hưởng (0 hay 1) cho biết có phải lần đầu.

2.2. Unique constraint và upsert

DB thấy mọi request đồng thời, nên để nó làm trọng tài. Upsert là “chèn, nếu đã có thì làm việc khác (ở đây: không làm gì)”.

-- PostgreSQL
INSERT INTO booking (user_id, request_id, homestay_id, checkin, checkout)
VALUES (42, 'b1c9...', 7, '2026-12-20', '2026-12-23')
ON CONFLICT (user_id, request_id) DO NOTHING
RETURNING id;   -- không trả dòng nào nghĩa là đã có

-- MySQL
INSERT INTO booking (user_id, request_id, homestay_id, checkin, checkout)
VALUES (42, 'b1c9...', 7, '2026-12-20', '2026-12-23')
ON DUPLICATE KEY UPDATE id = id;   -- no-op, affected rows = 0 nếu đã có
MySQL: vì sao không dùng INSERT IGNORE để bỏ qua trùng

Bài giỏ hàng và đặt hàng dùng đúng cách này cho nút đặt hàng: unique (user_id, request_id) trên orders chặn double click, trong cùng transaction với bước trừ kho.

2.3. Bảng khử trùng (dedupe store)

Khi không có khoá tự nhiên, ghi “đã xử lý” vào bảng riêng: idempotency key cho API, processed_message cho consumer. Bảng dedupe và thay đổi nghiệp vụ phải ghi trong cùng một transaction, nếu không sẽ có khe hở. Một biến thể ngắn hạn ở thiết kế chat kiểu Discord: client gắn nonce vào mỗi tin, server nhớ (user_id, nonce) → message_id vài phút, gửi lại thì trả tin cũ thay vì tạo tin mới.

3. Idempotency-Key ở API: cài đặt và chạy thử

Ý chính: trong một transaction: claim key bằng INSERT ... ON CONFLICT DO NOTHING → chạy nghiệp vụ → lưu response vào cùng dòng. Key đã có thì trả lại response cũ, hoặc 422 nếu body khác.

Cùng nhu cầu xuất hiện ở thiết kế URL shortener: POST tạo link cần idempotency key để một lần bấm không sinh hai link.

Bảng lưu key (PostgreSQL):

CREATE TABLE idempotency_record (
  client_id      text        NOT NULL,
  idem_key       text        NOT NULL,
  request_hash   char(64)    NOT NULL,          -- SHA-256 của body đã chuẩn hoá
  status         text        NOT NULL CHECK (status IN ('IN_PROGRESS', 'COMPLETED')),
  http_status    int,
  response_body  text,                          -- text, không phải jsonb (xem pitfall bên dưới)
  created_at     timestamptz NOT NULL DEFAULT now(),
  expires_at     timestamptz NOT NULL DEFAULT now() + interval '24 hours',
  PRIMARY KEY (client_id, idem_key)
);
CREATE INDEX idempotency_record_expires ON idempotency_record (expires_at);  -- cho job dọn dẹp

Ba nhánh của handler:

  • Claim được key (insert 1 dòng): chạy nghiệp vụ, lưu http_status + response_body, đánh dấu COMPLETED, commit.
  • Key đã có, cùng hash: replay, trả lại đúng response cũ.
  • Key đã có, khác hash: client dùng sai key, trả 422 IDEMPOTENCY_KEY_REUSED.

Lỗi nghiệp vụ (thiếu số dư) cũng là kết quả, được lưu lại. Lỗi hạ tầng thì rollback, key mất theo, retry chạy lại từ đầu.

Chạy thử: 20 request cùng key cùng lúc chỉ tạo một giao dịch, cả 20 nhận cùng một response.

Code Java đầy đủ và kết quả chạy 20 request đồng thời

Phần lõi (JDBC thuần cho dễ chạy thử; trong Spring thì là một method @Transactional dùng JdbcTemplate):

ApiResponse pay(String clientId, String key, PaymentRequest req) throws Exception {
    String hash = sha256(canonicalJson(req));
    try (Connection c = dataSource.getConnection()) {
        c.setAutoCommit(false);
        try {
            int claimed = update(c, """
                INSERT INTO idempotency_record (client_id, idem_key, request_hash, status)
                VALUES (?, ?, ?, 'IN_PROGRESS')
                ON CONFLICT (client_id, idem_key) DO NOTHING""", clientId, key, hash);
            // Nếu transaction khác đang giữ cùng key, câu INSERT trên CHỜ tới khi nó commit/rollback

            if (claimed == 0) {                               // key đã có: replay hoặc dùng sai key
                StoredRecord r = findRecord(c, clientId, key);
                c.commit();
                if (!r.requestHash().equals(hash)) return new ApiResponse(422, "{\"error\":\"IDEMPOTENCY_KEY_REUSED\"}");
                return new ApiResponse(r.httpStatus(), r.responseBody());   // trả lại đúng response cũ
            }

            ApiResponse result;
            int debited = update(c, "UPDATE account SET balance = balance - ? WHERE id = ? AND balance >= ?",
                    req.amount(), req.from(), req.amount());
            if (debited == 0) {
                result = new ApiResponse(422, "{\"error\":\"INSUFFICIENT_BALANCE\"}");  // kết quả nghiệp vụ: lưu lại
            } else {
                update(c, "UPDATE account SET balance = balance + ? WHERE id = ?", req.amount(), req.to());
                long paymentId = insertPayment(c, req);
                result = new ApiResponse(201, "{\"payment_id\":" + paymentId + "}");
            }
            update(c, """
                UPDATE idempotency_record SET status = 'COMPLETED', http_status = ?, response_body = ?
                WHERE client_id = ? AND idem_key = ?""", result.status(), result.body(), clientId, key);
            c.commit();
            return result;
        } catch (Exception e) {
            c.rollback();      // lỗi hạ tầng: key cũng biến mất, client retry sẽ chạy lại từ đầu
            throw e;
        }
    }
}

Bản đầy đủ chạy với Java 21, PostgreSQL 16, driver 42.7. Tài khoản A có 1.000.000; 20 request cùng key bắn cùng lúc bằng virtual thread, mỗi request chuyển 300.000:

distinct responses = [ApiResponse[status=201, body={"payment_id":1}]]
same key, other amount -> ApiResponse[status=422, body={"error":"IDEMPOTENCY_KEY_REUSED"}]
new key -> ApiResponse[status=201, body={"payment_id":2}]
payments = 2, balance A = 400000

20 request chỉ tạo một giao dịch, cả 20 nhận cùng một response. Dùng lại key với số tiền khác bị từ chối; key mới tạo giao dịch thứ hai. Số dư cuối 400.000 đúng bằng hai lần trừ.

4. Case study: booking trùng vì request_id không có UNIQUE

Ý chính: bảng có cột request_id nhưng không có unique constraint, nên retry của một lần đặt đã thành công chạy lại toàn bộ luồng. Sửa bằng UNIQUE (user_id, request_id) và claim nó trước khi lock phòng.

4.1. Bối cảnh

Project homestay mẫu của khoá học có POST /api/v1/bookings với body chứa request_id. Bảng booking có cột request_id text NOT NULL, nhưng không có unique constraint. Luồng đặt phòng, trong một transaction: SELECT ... FOR UPDATE các dòng homestay_availability (mỗi đêm một dòng) còn AVAILABLE; đủ số đêm thì chuyển sang BOOKED và insert booking.

4.2. Điều gì xảy ra khi client retry

Lần 1 commit thành công nhưng response bị mất. Lần 2 tới với cùng request_id:

  • Không có gì kiểm tra request_id, nên lần 2 chạy lại toàn bộ luồng.
  • Các đêm đã BOOKED, nên SELECT ... FOR UPDATE lọc status = 'AVAILABLE' trả ít dòng hơn số đêm: service trả HOMESTAY_BUSY.
  • Người dùng thấy “phòng đã có người đặt” dù chính họ vừa đặt. Họ đặt chỗ khác: hai booking thật, một lần trừ tiền ngoài ý muốn.

Lock bi quan chặn được đặt trùng cùng đêm, nên bug lộ ra thành một lỗi sai cho một thao tác thành công. Với tài nguyên không độc quyền (đơn hàng, nạp tiền), lỗ hổng này tạo bản ghi trùng trực tiếp.

4.3. Sửa

ALTER TABLE booking ADD CONSTRAINT booking_user_request_uq UNIQUE (user_id, request_id);

Đầu transaction, INSERT ... ON CONFLICT (user_id, request_id) DO NOTHING RETURNING id. Không trả dòng thì trả booking đã có như lần đầu thành công (cùng booking_id, 201 hoặc 200). Claim request_id trước khi lock availability, để retry không chạm tới logic “còn phòng không”.

Cùng đoạn code còn gửi email và event Kafka bên trong transaction đặt phòng (sửa bằng transactional outbox).

Lỗi kèm theo: email và event Kafka trong transaction, sửa bằng outbox

Email và event được gửi bên trong transaction. Commit thất bại thì email “đặt thành công” đã đi; crash sau commit thì event mất. Cách sửa là transactional outbox: ghi event vào bảng outbox trong cùng transaction, một tiến trình riêng đọc và publish. Outbox là at-least-once, nên consumer phía sau phải idempotent (xem phần 2).

Bài Code review: hai buổi review mẫu review chính luồng này và viết các lỗi trên (thiếu UNIQUE cho request_id, email và event trong transaction) thành comment review có nhãn, kèm hậu quả và đề xuất sửa.

5. Lock không thay thế được idempotency

Ý chính: lock chỉ ngăn hai lần chạy cùng lúc; retry tới sau khi lần đầu nhả lock vẫn làm lại từ đầu. Idempotency cần một bản ghi bền rằng việc đã xong.

Code lock Redis của repo khoá học dùng SET key 1 NX PX ttl:

Boolean ok = redisTemplate.opsForValue().setIfAbsent(lockKey, "1", ttl);  // value hằng số "1"
// ... làm việc ...
redisTemplate.delete(lockKey);                                             // DEL không kiểm tra chủ

Bài tập

Bài 1: Nạp tiền ví qua webhook của ngân hàng

Đề (diễn giải): ngân hàng gọi webhook POST /topups mỗi khi có tiền chuyển vào, có thể gọi lại nhiều lần, đôi khi hai lần gần như cùng lúc. Thiết kế bảng và handler sao cho ví chỉ được cộng một lần.

Lời giải Bài 1: bảng topup với bank_txn_id làm khoá
CREATE TABLE topup (
  bank_txn_id  text PRIMARY KEY,           -- mã giao dịch phía ngân hàng: khoá tự nhiên
  wallet_id    bigint NOT NULL,
  amount       bigint NOT NULL CHECK (amount > 0),
  received_at  timestamptz NOT NULL DEFAULT now()
);
-- Trong một transaction:
INSERT INTO topup (bank_txn_id, wallet_id, amount) VALUES (:txn, :wallet, :amount)
ON CONFLICT (bank_txn_id) DO NOTHING;
-- chỉ khi INSERT trả 1 dòng:
UPDATE wallet SET balance = balance + :amount WHERE id = :wallet;
COMMIT;

Webhook thứ hai cùng bank_txn_id chờ ở unique index rồi nhận 0 dòng, bỏ qua việc cộng tiền và vẫn trả 200.

Senior sẽ thêm: xác minh chữ ký webhook, kiểm tra amount khớp khi trùng (khác là sự cố cần alert, không âm thầm bỏ qua), và job đối soát với sao kê ngân hàng.

Ghi nhớ

  • Giải thích được vì sao retry là bắt buộc, và vì sao chỉ đạt được exactly-once processing chứ không phải exactly-once delivery.
  • Biết khi nào dùng conditional update, unique constraint, hay bảng dedupe, và điều kiện “cùng transaction”.
  • Vẽ lại được ba nhánh của Idempotency-Key handler, và giải thích vì sao request đồng thời tự chờ ở unique index.
  • Biết khi nào phải chuyển sang hai pha IN_PROGRESS → COMPLETED và cái giá của nó.
  • Giải thích được vì sao distributed lock không thay được idempotency.

Câu hỏi phỏng vấn

Junior

Idempotency là gì và vì sao hệ thống phân tán cần nó?

Thao tác idempotent cho cùng trạng thái cuối dù chạy một hay nhiều lần; hệ thống phân tán cần nó để retry an toàn.

Bên gửi không phân biệt được “request bị mất” với “response bị mất”, nên phải retry, và retry biến mọi kênh thành at-least-once. Bên nhận idempotent thì retry không gây hại.

Vì sao kiểm tra “đã tồn tại chưa” bằng code rồi mới insert không đủ chống trùng?

Vì đó là race check-then-act: hai request đồng thời cùng thấy “chưa có” rồi cùng insert.

Chỉ unique constraint trong DB mới thấy mọi request song song và chặn được bản ghi thứ hai.

Mid

At-most-once, at-least-once, exactly-once khác nhau thế nào?

At-most-once có thể mất, at-least-once có thể trùng, còn exactly-once thực chất là at-least-once cộng bên nhận khử trùng.

At-most-once: không retry. At-least-once: retry tới khi có ack. Exactly-once delivery không đạt được qua mạng không tin cậy; cái làm được là exactly-once processing (idempotent consumer, unique constraint, dedupe store).

Distributed lock có thay cho idempotency được không?

Không. Lock chỉ ngăn hai lần chạy cùng lúc; retry tới sau khi lần đầu nhả lock vẫn chạy lại.

Lock còn có thể hết hạn khi lần đầu chưa xong. Idempotency cần bản ghi bền rằng việc đã làm (unique constraint, dedupe table); lock chỉ là tối ưu giảm tranh chấp.

Senior

Khi nào claim idempotency key trong một transaction, khi nào dùng hai pha?

Một transaction khi toàn bộ nghiệp vụ nằm trong cùng DB và ngắn; hai pha khi có lời gọi ra hệ thống ngoài.

  • Một transaction: key, thay đổi và response commit cùng nhau, request đồng thời tự chờ ở unique index.
  • Hai pha (commit IN_PROGRESS, gọi ra ngoài, commit COMPLETED): vì không thể giữ transaction mở trong lúc chờ HTTP. Phải xử lý key kẹt bằng lease hết hạn, trả 409 cho request trùng đang chạy, và truyền key xuống hệ thống ngoài để chính lời gọi đó cũng idempotent.
Một bug: người dùng báo “phòng đã có người đặt” nhưng thực ra họ vừa đặt thành công. Bạn điều tra thế nào?

Nghi ngay retry của một request đã thành công: lần hai chạy lại toàn bộ luồng và thấy các đêm đã BOOKED bởi chính lần một.

Kiểm tra log theo request_id, xem có hai request cùng request_id cách nhau vài giây không, và bảng có unique constraint trên request_id không. Sửa: unique (user_id, request_id), claim nó trước khi lock availability, trả lại booking cũ cho lần lặp.

Từ vựng tiếng Anh

Term Phát âm Nghĩa Ví dụ câu tiếng Anh dùng trong phỏng vấn
idempotent /ˌaɪ.dəmˈpoʊ.tənt/ chạy nhiều lần như một lần “The handler is idempotent, so redelivered messages are harmless.”
at-least-once delivery /æt liːst wʌns dɪˈlɪv.ər.i/ giao ít nhất một lần “Kafka consumers are at-least-once by default, so we deduplicate.”
deduplication /diːˌduː.plɪˈkeɪ.ʃən/ khử trùng lặp “Deduplication happens in the same transaction as the business write.”
check-then-act /tʃek ðen ækt/ kiểm tra rồi hành động (race) “Checking for existence in code is a check-then-act race.”
conditional update /kənˈdɪʃ.ən.əl ˈʌp.deɪt/ cập nhật có điều kiện “A conditional update only moves the order out of PENDING once.”
fencing token /ˈfen.sɪŋ ˈtoʊ.kən/ token tăng dần chống lock cũ “Without a fencing token, an expired lock holder can still write.”
replay /ˈriː.pleɪ/ trả lại / phát lại “A retry with the same key gets a replay of the original response.”
transactional outbox /trænˈzæk.ʃən.əl ˈaʊt.bɑːks/ bảng outbox trong transaction “We publish events through a transactional outbox to avoid dual writes.”

Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.