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

Transactional Outbox

Ghi thay đổi nghiệp vụ và event tương ứng trong cùng một transaction, rồi publish event từ bảng đó — không bao giờ mất event, cũng không publish event cho dữ liệu đã rollback.

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ấn đề dual write và vì sao đảo thứ tự hai lần ghi không giải quyết được.
  • Mô tả bảng outbox và relay (polling publisher hoặc change data capture).
  • Hiểu vì sao outbox cho giao nhận at-least-once chứ không phải exactly-once.
  • Triển khai outbox với Spring Data và một relay chạy định kỳ.

Tổng quan

Một cửa hàng ghi mỗi lần bán vào sổ, và còn phải gọi điện báo kho. Nếu người bán ghi sổ xong rồi bị gián đoạn trước khi gọi điện, kiện hàng sẽ không bao giờ được gửi. Cách sửa: ghi "gọi kho về đơn #42" vào danh sách việc cần làm ngay trong cuốn sổ đó, trên cùng một dòng. Một người khác lần lượt làm và đánh dấu các việc trong danh sách. Danh sách việc cần làm đó chính là outbox.

Trong hệ thống event-driven, một service thường phải làm hai việc cùng lúc: cập nhật database và publish event tới một broker như Kafka. Database và broker không thể dùng chung một transaction. Pattern outbox biến event thành một dòng trong bảng outbox, được ghi trong cùng local transaction với thay đổi nghiệp vụ. Một relay riêng đọc bảng này và phát các event đi.

Vấn đề: ghi kép (dual write)

Order ServiceOrders DBKafka

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

Phần trên: điều có thể sai giữa hai lần ghi. Phần dưới: phiên bản dùng outbox.
  • Lưu rồi mới publish — crash hoặc broker sập ở giữa để lại một order mà không service nào khác biết tới.
  • Publish rồi mới lưu — nếu transaction database sau đó thất bại, mọi người đều nghe về một order không tồn tại.
  • Publish bên trong transaction — message đã gửi tới broker không thể rollback, và một broker chậm giờ giữ khoá database.

Chạy thử: mất event hay tồn đọng

Cả hai kịch bản có cùng các lần crash và cùng 6 giây broker sập. Với dual write, Event bị mất tăng và không bao giờ quay lại. Với outbox, Tồn đọng outbox tăng trong lúc sự cố rồi giảm dần — không mất gì, chỉ chậm lại.

Đang tải mô phỏng…

Hai cách chạy relay

Polling publisherChange data capture (CDC)
Cách làmMột job định kỳ chọn các dòng chưa gửi, publish, rồi đánh dấu đã gửi.Một công cụ như Debezium đọc log của database và publish các dòng outbox mới chèn.
Độ trễBằng chu kỳ poll (vd. 100 ms – 1 s).Gần thời gian thực.
Tải databaseThêm truy vấn; cần index trên các dòng chưa gửi.Đọc replication log; không thêm tải truy vấn.
Vận hànhChỉ là code ứng dụng của bạn.Phải chạy và giám sát Kafka Connect + Debezium.
Thứ tựGiữ được theo từng aggregate nếu publish theo thứ tự chèn.Giữ được theo từng aggregate nhờ thứ tự log và message key.

Triển khai với Spring

bảng outbox
CREATE TABLE outbox (
    id             UUID PRIMARY KEY,
    aggregate_type VARCHAR(64)  NOT NULL,
    aggregate_id   VARCHAR(64)  NOT NULL,   -- dùng làm Kafka key: giữ thứ tự theo từng order
    event_type     VARCHAR(128) NOT NULL,
    payload        JSONB        NOT NULL,
    created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
    published_at   TIMESTAMPTZ
);
CREATE INDEX outbox_unpublished ON outbox (created_at) WHERE published_at IS NULL;
OrderService.java
@Service
public class OrderService {

    private final OrderRepository orders;
    private final OutboxRepository outbox;

    OrderService(OrderRepository orders, OutboxRepository outbox) {
        this.orders = orders;
        this.outbox = outbox;
    }

    @Transactional   // một local transaction: cả hai dòng cùng commit, hoặc không dòng nào
    public Order placeOrder(PlaceOrder command) {
        Order order = orders.save(Order.place(command));
        outbox.save(OutboxEvent.of("Order", order.id(), "OrderPlaced", OrderPlaced.from(order)));
        return order;
    }
}
Nâng cao
OutboxRelay.java (polling publisher)
@Component
class OutboxRelay {

    private final OutboxRepository outbox;
    private final KafkaTemplate<String, String> kafka;

    OutboxRelay(OutboxRepository outbox, KafkaTemplate<String, String> kafka) {
        this.outbox = outbox;
        this.kafka = kafka;
    }

    @Scheduled(fixedDelay = 200)
    @Transactional
    public void publishPending() {
        // SELECT ... WHERE published_at IS NULL ORDER BY created_at LIMIT 100 FOR UPDATE SKIP LOCKED
        for (OutboxEvent event : outbox.lockNextBatch(100)) {
            kafka.send("order-events", event.aggregateId(), event.payload()).join();  // chờ ack
            event.markPublished();   // crash trước khi commit nghĩa là event này được gửi lại
        }
    }
}

Nâng cao FOR UPDATE SKIP LOCKED cho phép nhiều instance relay chạy mà không đồng thời publish cùng một dòng. Publish đồng bộ (chờ ack của broker) trước khi đánh dấu dòng giữ được bảo đảm at-least-once. Hãy xoá hoặc lưu trữ các dòng đã publish định kỳ để bảng luôn nhỏ.

Đánh đổi

ĐượcMất
Độ tin cậyKhông mất event và không có event cho thay đổi đã rollback.Có thể trùng lặp: consumer phải idempotent.
Độ trễRequest của người dùng không phải chờ broker.Event tới sau một chu kỳ poll (hoặc độ trễ CDC).
Vận hànhChịu được broker sập một cách êm ái, chỉ tồn đọng tăng lên.Thêm một bảng, một relay phải vận hành, và việc dọn dòng cũ.

Lưu ý khi chạy production

  • Cảnh báo theo kích thước tồn đọng outbox và tuổi của dòng chưa publish lâu nhất.
  • Dùng id của aggregate làm message key để các event của một order giữ đúng thứ tự.
  • Đặt một event id trong payload — consumer dùng nó để khử trùng lặp (xem Idempotent Consumer).

Đọc thêm

Bài liên quan