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

Tìm kiếm

System DesignSenior15 phút đọc

Idempotency phần 2: consumer Kafka, idempotent producer và IPN cổng thanh toán

Ôn 11 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

Phần 1 đã giải thích vì sao mọi kênh là at-least-once, và cách khử trùng ở tầng API và database. Phần này áp dụng cùng ý tưởng cho hai chỗ trùng hay gặp nhất trên production: Kafka giao lại message, và cổng thanh toán gọi lại callback. Đọc xong, bạn viết được consumer và handler IPN chạy lặp vô hại.

Nên đọc trước: phần 1, và transaction và locking cho conditional update.

1. Consumer Kafka idempotent

Ý chính: consumer at-least-once có thể nhận lại cùng message, nên ghi dấu “đã xử lý” vào DB trong cùng transaction với nghiệp vụ. Message tới lại sẽ đụng khoá chính và bị bỏ qua.

Thứ tự: nhận message → xử lý → commit offset (vị trí đã đọc tới trong partition). Message bị giao lại khi:

  • Crash sau khi xử lý, trước khi commit offset.
  • Rebalance (Kafka chia lại partition giữa các consumer trong group) giữa chừng.
  • Producer gửi trùng: outbox publish lại, hoặc ứng dụng tự retry.
CREATE TABLE processed_message (
  consumer_group text        NOT NULL,
  message_id     uuid        NOT NULL,
  processed_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (consumer_group, message_id)
);
@KafkaListener(topics = "wallet-transactions", groupId = "notification")
@Transactional   // transaction của DataSource: dedupe + nghiệp vụ commit cùng nhau
public void onFundTransfer(FundTransferEvent event) {
    int fresh = jdbc.update("""
        INSERT INTO processed_message (consumer_group, message_id) VALUES ('notification', ?)
        ON CONFLICT DO NOTHING""", event.messageId());
    if (fresh == 0) {
        log.info("duplicate {}, skip", event.messageId());
        return;                                   // vẫn để offset được commit bình thường
    }
    notificationRepository.save(Notification.from(event));
}
// Offset commit sau khi method trả về (AckMode.RECORD/BATCH). Crash trước đó: message tới lại,
// INSERT dedupe đụng khoá, bỏ qua. Không bao giờ ghi notification hai lần.

Hai việc còn lại:

  • Thứ tự: message cũ có thể tới sau message mới (retry, nhiều partition). Lưu version hoặc event_time trên bản ghi đích, chỉ cập nhật khi mới hơn: UPDATE ... WHERE id = ? AND version < ?.
  • Dọn dẹp: giữ processed_message lâu hơn retention của topic + thời gian replay tối đa, rồi xoá theo lô hoặc partition theo ngày.
Side effect ra ngoài DB: ba cách xử lý

2. Idempotent producer của Kafka

Ý chính: enable.idempotence=true cho broker nhận ra batch bị producer gửi lại khi ack bị mất, nhờ PID và sequence number. Nó chỉ chống trùng do retry nội bộ của client, không thay được dedupe ở consumer.

Vấn đề: broker ghi xong batch nhưng ack mất, producer retry, broker ghi hai lần. Cách idempotence giải quyết:

  • Mỗi producer nhận một Producer ID (PID) và epoch (số thế hệ của producer); mỗi batch tới một partition mang sequence number tăng dần.
  • Broker nhớ sequence cuối của mỗi (PID, partition): batch có sequence đã thấy thì bỏ (vẫn trả ack thành công); batch nhảy cóc sequence thì báo lỗi thay vì ghi lệch thứ tự.
  • Điều kiện: acks=all, retries > 0, max.in.flight.requests.per.connection ≤ 5 (số request chưa có ack trên một connection).
  • Từ Kafka 3.0, idempotence bật mặc định ở producer.

Phạm vi của nó hẹp hơn nhiều người nghĩ:

  • Chỉ trong một phiên producer: restart là có PID mới; muốn bền qua restart phải dùng transactional.id.
  • Chỉ chống retry nội bộ của client. Ứng dụng tự gọi send() hai lần (try/catch, outbox publish lại) là hai message khác nhau.
  • Không nói gì về phía consumer.

transactional.id chạy thế nào bên trong (coordinator, control marker, fencing) có ở bài producer bên trong.

Vì sao là 5, lỗi của service ví mẫu, và vì sao outbox publish lại

Service ví mẫu của khoá học cấu hình đúng phần này (acks=all, retries=30, enable.idempotence=true, max.in.flight=5), nhưng hai chỗ làm mất giá trị của nó:

  • Gửi message không có key, nên giao dịch của cùng một tài khoản rơi vào nhiều partition và mất thứ tự. Sửa: dùng debit_account hoặc transaction_id làm key.
  • Bọc kafkaTemplate.send() trong try/catch. Nhưng send() là bất đồng bộ: lỗi broker nằm trong CompletableFuture trả về, không ném ra. Sửa: xử lý kết quả của future.

Vì sao outbox publish lại: relay (tiến trình đọc bảng outbox và đẩy lên Kafka) gửi message rồi mới đánh dấu bản ghi là đã gửi, nên chết giữa hai bước là gửi lại. Mục “Transactional outbox” của bài Case study: gọi fraud-check đồng bộ qua Kafka có schema outbox, câu relay dùng FOR UPDATE SKIP LOCKED, và trade-off giữa relay polling với CDC (Debezium đọc WAL hoặc binlog). CDC có độ trễ thấp hơn và không quét bảng, đổi lại thêm Kafka Connect phải vận hành. Cả hai đều at-least-once. Vì sao cần outbox ngay từ đầu (dual write) có ở bài dual write và exactly-once; outbox chỉ giữ một service nhất quán, nhiều service thì cần saga.

3. Case study: IPN của cổng thanh toán

Ý chính: cổng báo kết quả qua hai đường, chỉ IPN có chữ ký mới được tin. Handler IPN kiểm chữ ký, số tiền, chỉ chuyển từ PENDING_PAYMENT, và trả “đã xác nhận” cho lần gửi lại.

3.1. Luồng

Mục này chỉ bàn phần idempotent. Toàn bộ luồng tích hợp (tạo URL, ký và kiểm chữ ký HMAC, mã phản hồi) có ở bài Tích hợp cổng thanh toán kiểu VNPay.

Với cổng kiểu redirect (VNPay và tương tự), backend tạo đơn PENDING_PAYMENT và trả URL đã ký. Người dùng trả tiền trên trang của cổng, rồi kết quả về theo hai đường:

sequenceDiagram
    participant B as Trình duyệt
    participant FE as Frontend
    participant BE as Backend
    participant PG as Cổng thanh toán
    BE-->>FE: URL thanh toán đã ký
    FE->>PG: redirect, người dùng trả tiền
    PG->>BE: IPN server-to-server (có thể gửi lại nhiều lần)
    BE-->>PG: mã phản hồi đã nhận
    PG->>B: redirect về return URL
    B->>FE: return URL kèm tham số
    FE->>BE: hỏi trạng thái đơn
    BE-->>FE: trạng thái trong DB
  • IPN (Instant Payment Notification): cổng gọi thẳng backend, là nguồn sự thật. Không nhận được phản hồi đúng định dạng thì cổng gửi lại.
  • Return URL: trình duyệt quay về, chỉ để hiển thị. Tham số sửa được, tab có thể bị đóng, nên frontend phải hỏi backend trạng thái thật.

3.2. Handler IPN idempotent

@GetMapping("/payment/ipn")
public IpnReply ipn(@RequestParam Map<String, String> params) {
    if (!signature.verify(params)) return IpnReply.INVALID_CHECKSUM;            // 1. chữ ký trước tiên
    Order order = orders.findByTxnRef(params.get("txn_ref")).orElse(null);
    if (order == null) return IpnReply.ORDER_NOT_FOUND;
    if (order.amountMinor() != Long.parseLong(params.get("amount"))) return IpnReply.INVALID_AMOUNT;
    if (order.isFinal()) return IpnReply.ALREADY_CONFIRMED;                   // 2. lần gửi lại: không làm gì

    boolean success = "00".equals(params.get("response_code"));
    int changed = tx.execute(s -> success
        ? orders.markPaid(order.id(), params.get("gateway_txn_no"))           // UPDATE ... WHERE status = 'PENDING_PAYMENT'
        : orders.markFailed(order.id(), params.get("response_code")));
    // changed == 0: IPN khác vừa xử lý xong đồng thời; vẫn trả "đã xác nhận"
    return changed == 1 ? IpnReply.CONFIRMED : IpnReply.ALREADY_CONFIRMED;
}
  1. Xác minh chữ ký và số tiền trước khi tin bất kỳ tham số nào. So số tiền theo đơn vị nhỏ nhất (cổng kiểu VNPay gửi số tiền đã nhân 100).
  2. State machine (tập trạng thái và bước chuyển được phép): chỉ chuyển từ PENDING_PAYMENT; trạng thái cuối (PAID, FAILED, EXPIRED) không bị ghi đè. Conditional update làm trọng tài khi hai IPN tới cùng lúc.
  3. Mã phản hồi đúng spec của cổng cho từng trường hợp (đã xác nhận, sai chữ ký, sai số tiền, không thấy đơn); cổng dựa vào đó để quyết định gửi lại. Lần gửi lại nhận “đã xác nhận”, không phải lỗi, không thì cổng gửi mãi.
  4. Unique constraint trên mã giao dịch của cổng trong bảng payment/ledger: lớp chặn cuối nếu code có lỗi.
  5. IPN không bao giờ tới: job đối soát định kỳ gọi API truy vấn giao dịch của cổng cho đơn PENDING_PAYMENT quá N phút. Quá hạn thanh toán thì chuyển EXPIRED và nhả các đêm/ghế đang giữ.

4. Lưu gì, trả gì, giữ bao lâu

Ý chính: tầng nào cũng cần một khoá khử trùng, nhưng thứ lưu và thời gian giữ khác nhau. Khoá tạm (Idempotency-Key, dấu consumer) giữ có hạn; khoá nằm trong dữ liệu thật (bản ghi, giao dịch) giữ vĩnh viễn.

Bảng tổng hợp sáu tầng: khoá, thứ lưu, thứ trả, thời gian giữ
Tầng Khoá khử trùng Lưu Trả cho lần lặp Giữ bao lâu
API (client_id, Idempotency-Key) Hash body, trạng thái, status + body response Response cũ; 422 nếu body khác; 409 nếu đang chạy 24 giờ tới vài ngày
Tạo bản ghi Khoá nghiệp vụ (user_id, request_id) Chính bản ghi Bản ghi đã có Vĩnh viễn (là dữ liệu)
Chuyển trạng thái Trạng thái hiện tại Không cần Kết quả hiện tại Không áp dụng
Consumer (consumer_group, message_id) hoặc id nghiệp vụ Dấu “đã xử lý” Bỏ qua, commit offset > retention + cửa sổ replay
Producer Kafka (PID, partition, sequence) Broker tự giữ Ack thành công Trong phiên producer
IPN Mã đơn + trạng thái cuối, unique mã giao dịch cổng Giao dịch, bút toán Mã “đã xác nhận” Vĩnh viễn

Bài tập

Bài 1: Review cấu hình producer

Đề: producer có acks=1, retries=10, max.in.flight.requests.per.connection=10, không đặt enable.idempotence, gửi message không key. Nêu rủi ro và sửa.

Lời giải Bài 1

Rủi ro:

  • acks=1 và max.in.flight=10 làm idempotence bị tắt; retry khi ack mất tạo bản ghi trùng.
  • In-flight > 1 mà không có idempotence thì retry có thể ghi lệch thứ tự.
  • acks=1 mất dữ liệu nếu leader chết trước khi follower kịp copy.
  • Không key thì không có thứ tự theo tài khoản.

Sửa: acks=all, enable.idempotence=true, max.in.flight=5, key = account_id, topic min.insync.replicas=2, và consumer vẫn khử trùng theo id nghiệp vụ.

Ghi nhớ

  • Giải thích được vì sao dedupe phải cùng transaction với nghiệp vụ, và commit offset lúc nào.
  • Biết khi nào dedupe theo message_id thất bại, và vì sao khoá nghiệp vụ tốt hơn.
  • Nêu được cơ chế PID + sequence, ba điều kiện cấu hình, và ba giới hạn của idempotent producer.
  • Vẽ được hai đường báo kết quả của cổng thanh toán và nói đường nào là nguồn sự thật.
  • Liệt kê được các bước của handler IPN, kể cả khi IPN không tới.

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

Junior

Vì sao không cập nhật trạng thái thanh toán theo return URL?

Vì return URL đi qua trình duyệt: sửa được tham số, và có thể không bao giờ tới.

Người dùng đóng tab trước khi redirect là nó không tới. Chỉ dùng nó để hiển thị và để frontend hỏi backend trạng thái thật. Trạng thái được cập nhật từ IPN server-to-server có chữ ký, cộng job đối soát.

Mid

Thiết kế consumer Kafka idempotent thế nào?

Trong cùng một transaction DB: insert dấu “đã xử lý” với ON CONFLICT DO NOTHING, insert được thì mới ghi nghiệp vụ; commit offset sau khi transaction commit.

Khoá là (consumer_group, message_id hoặc id nghiệp vụ) trong bảng processed_message. Message tới lại đụng khoá và bị bỏ qua. Xử lý thứ tự bằng version hoặc event_time, và dọn bảng dedupe sau khoảng retention cộng cửa sổ replay.

Bảng processed_message nên giữ bao lâu?

Lâu hơn khoảng thời gian một message có thể được giao lại: retention của topic cộng cửa sổ replay tối đa.

Cửa sổ replay là lúc bạn reset offset khi sự cố. Ngắn hơn thế thì một lần replay sẽ xử lý lại message cũ. Dọn theo lô hoặc partition bảng theo ngày để xoá rẻ; nếu dedupe theo khoá nghiệp vụ nằm luôn trong bảng dữ liệu thì không cần dọn.

Senior

Idempotent producer của Kafka hoạt động thế nào và giới hạn của nó?

Broker nhớ sequence gần nhất theo (PID, partition), bỏ batch trùng và từ chối batch lệch thứ tự. Nó chỉ chống trùng do retry nội bộ của client, trong một phiên producer.

  • Producer có PID và epoch, mỗi batch tới một partition có sequence number.
  • Cần acks=all, retries > 0, max.in.flight ≤ 5. Mặc định bật từ Kafka 3.0, nhưng bị tắt âm thầm nếu đặt acks=1 mà không ghi rõ enable.idempotence.
  • Giới hạn: restart có PID mới (cần transactional.id), không chống việc ứng dụng gọi send hai lần, không nói gì về consumer.
Thiết kế handler IPN cho cổng thanh toán thế nào?

Xác minh chữ ký, tìm đơn, so số tiền, rồi mới cập nhật bằng conditional update theo state machine. Đơn đã ở trạng thái cuối thì trả “đã xác nhận” để cổng ngừng gửi lại.

  • Chỉ chuyển từ PENDING_PAYMENT; ghi giao dịch và ledger trong cùng transaction; unique constraint trên mã giao dịch của cổng.
  • Return URL chỉ để hiển thị.
  • Job đối soát hỏi cổng cho các đơn pending quá hạn, chuyển EXPIRED và nhả tài nguyên đang giữ.
Kafka đã có exactly-once, sao consumer vẫn phải idempotent?

Vì exactly-once của Kafka chỉ bao luồng đọc Kafka → xử lý → ghi Kafka; ghi DB, gọi API, gửi email nằm ngoài transaction đó.

Exactly-once (idempotent producer, transaction, read_committed) commit offset và output trong cùng một transaction Kafka. Crash giữa lúc ghi PostgreSQL và commit offset vẫn làm message được xử lý lại. Nên side effect ra ngoài vẫn cần dedupe trong DB, cùng transaction với thay đổi nghiệp vụ.

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
redelivery /ˌriː.dɪˈlɪv.ər.i/ giao lại “A rebalance can cause redelivery of messages that were already processed.”
sequence number /ˈsiː.kwəns ˈnʌm.bər/ số thứ tự “The broker drops a batch whose sequence number it has already seen.”
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.”
reconciliation /ˌrek.ənˌsɪl.iˈeɪ.ʃən/ đối soát “A reconciliation job queries the gateway for orders stuck in pending.”
source of truth /sɔːrs əv truːθ/ nguồn sự thật “The IPN is the source of truth; the return URL is only for display.”
state machine /steɪt məˈʃiːn/ máy trạng thái “Final states in the state machine can never be overwritten.”
deduplication /diːˌduː.plɪˈkeɪ.ʃən/ khử trùng lặp “Deduplication happens in the same transaction as the business write.”
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.”
consumer group /kənˈsuː.mər ɡruːp/ nhóm consumer chia nhau partition “Each consumer group keeps its own offsets and its own dedupe table.”
in-flight request /ɪn flaɪt rɪˈkwest/ request đang bay, chưa có ack “With idempotence on, up to five in-flight requests still keep ordering.”

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.