Đi tới nội dung chính
System Design Lab
Microservice Patterns

Idempotent Consumer

Xử lý một message hai lần phải cho kết quả như xử lý một lần — vì sớm hay muộn, broker nào cũng sẽ giao trùng message.

Trung cấp 7 phút đọc· Cập nhật 2026-11-18

Sau bài này bạn sẽ

  • Giải thích vì sao giao nhận at-least-once là mặc định thực tế và bản trùng đến từ đâu.
  • Khử trùng lặp bằng bảng message đã xử lý trong cùng transaction với side effect.
  • Chọn giữa idempotency tự nhiên và khử trùng lặp tường minh.
  • Hiểu giới hạn của "exactly once" ở mức broker.

Nên đọc trước

Tổng quan

Bấm nút thang máy năm lần không gọi năm thang máy — lần bấm thứ hai không thay đổi gì. Đặt điều hoà 21 °C hai lần thì nó vẫn ở 21 °C. Những thao tác như vậy là idempotent. Một idempotent consumer làm cho việc xử lý message cũng như thế: lần giao thứ hai của "trừ tiền đơn #42" sẽ không trừ tiền lần nữa.

Broker cung cấp giao nhận at-least-once: message được giao lại trừ khi consumer xác nhận đã xử lý. Bất kỳ crash, timeout hay rebalance nào xảy ra giữa lúc làm việc và lúc xác nhận đều khiến công việc bị làm lại. Vì vậy consumer phải phát hiện được bản lặp — thường bằng cách ghi nhớ các message id đã xử lý.

Bản trùng đến từ đâu

  • Consumer crash sau khi thực hiện side effect nhưng trước khi commit offset.
  • Xử lý lâu hơn hạn chót của broker; partition bị giao cho consumer khác và message được giao lại (xem Xử lý message trùng lặp).
  • Producer thử gửi lại một message mà ack bị mất, hoặc relay của outbox phát một dòng hai lần.
  • Ai đó replay topic từ một offset cũ để khắc phục bug.
KafkaBilling consumerBilling DB

Bấm Chạy, hoặc dùng mũi tên để đi từng bước.

Bản ghi message đã xử lý và việc trừ tiền commit cùng nhau, nên lần giao lại bị phát hiện.

Chạy thử

Cả hai kịch bản cho consumer crash ở cùng thời điểm và giao lại cùng các message. Chỉ có ô đỏ Trừ tiền trùng lặp là khác. Dùng Cho billing-1 crash ngay và lỗi mạng giao trùng để tạo thêm các lần giao lại.

Đang tải mô phỏng…

Làm cho handler idempotent

Kỹ thuậtVí dụKhi nào phù hợp
Idempotency tự nhiênUPDATE orders SET status = 'SHIPPED' WHERE id = ?Thao tác đặt một trạng thái thay vì cộng dồn hay thêm vào.
Bảng message đã xử lýChèn message id có ràng buộc unique trong cùng transaction với công việc.Mọi side effect trong database của chính bạn. Lựa chọn mặc định.
Idempotency key ở phía dướiTruyền message id làm Idempotency-Key cho API thanh toán.Tác dụng phụ xảy ra ở hệ thống khác có hỗ trợ key.
Ghi có điều kiện / versionUPDATE … WHERE version = ? (optimistic locking).Cập nhật mà message mang theo trạng thái trước đó mong đợi.

Triển khai với Spring Kafka

processed_messages
CREATE TABLE processed_messages (
    consumer_group VARCHAR(100) NOT NULL,
    message_id     VARCHAR(100) NOT NULL,
    processed_at   TIMESTAMPTZ  NOT NULL DEFAULT now(),
    PRIMARY KEY (consumer_group, message_id)
);
BillingListener.java
@Component
class BillingListener {

    private final JdbcClient jdbc;
    private final BillingService billing;

    BillingListener(JdbcClient jdbc, BillingService billing) {
        this.jdbc = jdbc;
        this.billing = billing;
    }

    @KafkaListener(topics = "order-events", groupId = "billing")
    @Transactional
    public void on(OrderPlaced event) {
        int inserted = jdbc.sql("""
                INSERT INTO processed_messages (consumer_group, message_id)
                VALUES ('billing', :id) ON CONFLICT DO NOTHING
                """)
                .param("id", event.eventId())
                .update();
        if (inserted == 0) {
            return;                     // đã xử lý: bỏ qua, offset được commit sau khi return
        }
        billing.charge(event);          // cùng transaction database với lệnh insert ở trên
    }
}

Còn exactly-once của Kafka thì sao? Nâng cao

Nâng cao Transaction của Kafka cho ngữ nghĩa exactly-once với đọc-xử lý-ghi bên trong Kafka: tiêu thụ, ghi kết quả và commit offset một cách nguyên tử. Chúng không bao gồm side effect bên ngoài Kafka — ghi database, gửi email, trừ tiền thẻ. Với những thứ đó, vẫn cần idempotent consumer. Hãy hiểu "exactly once" là "hiệu quả như một lần": giao nhận at-least-once cộng với xử lý idempotent.

Đánh đổi

ĐượcMất
Tính đúng đắnCác lần giao lại trở nên vô hại.Chỉ khi bản ghi khử trùng và công việc dùng chung một transaction.
Hiệu năngMột lệnh insert có index cho mỗi message.Thêm một lần ghi mỗi message; bảng phải được dọn định kỳ.
Thiết kếCho phép dùng hạ tầng at-least-once đơn giản ở mọi nơi.Mỗi message cần một id ổn định, duy nhất do producer gán.

Lưu ý khi chạy production

  • Gán id tại nguồn (vd. id của dòng outbox), không bao giờ gán khi giao lại — mỗi lần thử một id mới là mất hết tác dụng.
  • Giữ id đã xử lý ít nhất bằng khoảng thời gian message có thể bị giao lại (retention của topic cộng cửa sổ replay), sau đó mới dọn.
  • Đếm số bản trùng bị bỏ qua thành metric: tăng đột ngột là dấu hiệu của rebalance hoặc producer thử gửi lại.

Đọc thêm

Bài liên quan