Doanh nghiệpEnterprise

Transactional Outboxaka Outbox, Outbox + Relay

Ghi dữ liệu nghiệp vụ và event vào cùng một transaction DB, rồi một relay đẩy event sang broker.Write the business row and the event in one DB transaction, then a relay pushes the event to the broker.

Độ khóDifficulty: VừaMedium
Mức phổ biếnUsage: Mức phổ biếnUsage 4/5
Thời gian đọcReading time: ~9 phút đọc~9 min read

Thảo luậnDiscussion

Ví dụ đời thườngReal-life analogy

Ở bưu cục, bạn không chạy ra xe tải gửi thư ngay lúc viết xong. Bạn bỏ thư vào hộp 'thư đi' (outbox) ngay tại bàn — việc viết thư và bỏ vào hộp là một động tác. Định kỳ nhân viên bưu cục gom hộp và mang ra xe. Xe tới trễ hay hỏng giữa đường thì thư vẫn nằm an toàn trong hộp, lần sau gom tiếp.At a post office you don't run to the truck the moment you finish a letter. You drop it into the 'outgoing' box right at your desk — writing and dropping are one motion. Periodically a clerk empties the box onto the truck. If the truck is late or breaks down, the letters stay safe in the box until the next round.

Vấn đề và giải phápProblem and solution

Không có patternWithout the pattern

Sau khi lưu đơn hàng, service gửi event OrderPlaced lên Kafka để kho và thông báo xử lý. Nhưng DB và Kafka là hai hệ thống, không có transaction chung (dual-write). Commit DB xong mà Kafka lỗi → đơn tồn tại nhưng kho không bao giờ biết. Gửi Kafka trước rồi DB rollback → kho trừ hàng cho một đơn không tồn tại. Gửi Kafka bên trong @Transactional cũng không giúp gì.After saving an order, the service publishes OrderPlaced to Kafka for inventory and notifications. But the DB and Kafka are two systems with no shared transaction (dual-write). DB commits but Kafka fails → the order exists but inventory never hears about it. Kafka first and the DB rolls back → inventory reserves stock for an order that doesn't exist. Sending to Kafka inside @Transactional doesn't help either.

Với Transactional OutboxWith Transactional Outbox

Thêm bảng outbox ngay trong database nghiệp vụ. Trong cùng transaction, INSERT đơn hàng VÀ INSERT một dòng event vào outbox — cả hai cùng commit hoặc cùng rollback. Một tiến trình relay riêng đọc các dòng chưa gửi (poll với FOR UPDATE SKIP LOCKED, hoặc CDC như Debezium đọc WAL), đẩy lên Kafka, rồi đánh dấu đã gửi. Kết quả: giao hàng at-least-once, nên consumer phải idempotent theo eventId.Add an outbox table inside the business database. In the same transaction, INSERT the order AND INSERT an event row into the outbox — both commit or both roll back. A separate relay reads unsent rows (polling with FOR UPDATE SKIP LOCKED, or CDC like Debezium reading the WAL), publishes them to Kafka, then marks them sent. The result is at-least-once delivery, so consumers must be idempotent on eventId.

Thành phần tham giaParticipants

Business service: Ghi dữ liệu nghiệp vụ + dòng outbox trong cùng một transaction.Writes the business data + an outbox row in the same transaction.
Outbox table: Bảng trong cùng DB: id, aggregate, type, payload, published_at.A table in the same DB: id, aggregate, type, payload, published_at.
Relay (poller / CDC): Đọc dòng chưa gửi, publish lên broker, đánh dấu đã gửi.Reads unsent rows, publishes them to the broker, marks them sent.
Message broker: Kafka/RabbitMQ — phân phối event cho các service khác.Kafka/RabbitMQ — distributes events to other services.
Idempotent consumer: Bỏ qua event trùng (theo eventId) vì giao hàng là at-least-once.Skips duplicate events (by eventId) since delivery is at-least-once.

Sơ đồ và luồng thực thiDiagram and execution flow

Dùng Tự chạy hoặc phím mũi tên để đi qua từng bước gọi giữa các object. Console hiển thị output tương ứng của chương trình.Use Autoplay or the arrow keys to step through each call between objects. The console shows the matching program output.

1placeOrder(): trong MỘT transaction, chèn dòng orders và dòng outbox. Commit là có cả hai, rollback là mất cả hai.placeOrder(): in ONE transaction, insert the orders row and the outbox row. Commit gives both, rollback loses both.

← →

console

1BEGIN; INSERT orders; INSERT outbox; COMMIT

implementsimplementsextendsextendsgọi / dùngcalls / usestạo racreatesgửi qua channelsends via channel1thứ tự chạy (bấm để nhảy bước)execution order (click to jump)

Code: Java Spring Boot ⇄ GoCode: Java Spring Boot ⇄ Go

Cùng một bài toán, hai ngôn ngữ. Rê chuột hoặc focus vào chú thích (số màu cam) để làm nổi bật dòng code tương ứng.Same problem, two languages. Hover or focus an annotation (orange number) to highlight its line.

JavaSpring Boot 3 · Java 21Spring Boot 3 · Java 21

package com.shop.order;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.shop.outbox.OutboxEvent;
import com.shop.outbox.OutboxRepository;
import java.util.UUID;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {
    private final OrderRepository orders;
    private final OutboxRepository outbox;
    private final ObjectMapper json;

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

    @Transactional1
    public UUID placeOrder(PlaceOrderRequest req) {
        Order order = orders.save(Order.place(req.customerId(), req.lines()));

        // Same DataSource, same transaction: both rows commit or neither does
        outbox.save(OutboxEvent.of(2
            "order", order.id().toString(), "OrderPlaced",
            toJson(new OrderPlaced(order.id(), order.customerId(), order.total()))));

        // NOT kafkaTemplate.send(...) here: Kafka can't join this DB transaction3
        return order.id();
    }

    private String toJson(Object event) {
        try {
            return json.writeValueAsString(event);
        } catch (JsonProcessingException e) {
            throw new IllegalStateException("cannot serialize " + event, e);
        }
    }
}

GoGo 1.23 · thư viện chuẩnGo 1.23 · standard library

package order

import (
	"context"
	"database/sql"
	"encoding/json"

	"github.com/google/uuid"
)

type OrderPlaced struct {
	OrderID    string `json:"orderId"`
	CustomerID string `json:"customerId"`
	Total      int64  `json:"total"`
}

type Service struct{ DB *sql.DB }

func (s *Service) PlaceOrder(ctx context.Context, customerID string, total int64) (string, error) {
	id := uuid.NewString()
	payload, err := json.Marshal(OrderPlaced{OrderID: id, CustomerID: customerID, Total: total})1
	if err != nil {
		return "", err
	}

	tx, err := s.DB.BeginTx(ctx, nil)
	if err != nil {
		return "", err
	}
	defer tx.Rollback() // no-op once committed2

	if _, err := tx.ExecContext(ctx,
		"INSERT INTO orders (id, customer_id, total, status) VALUES ($1, $2, $3, 'PLACED')",
		id, customerID, total); err != nil {
		return "", err
	}
	// Same tx: the event exists if and only if the order exists3
	if _, err := tx.ExecContext(ctx,
		"INSERT INTO outbox (id, aggregate_type, aggregate_id, type, payload) VALUES ($1, 'order', $2, 'OrderPlaced', $3)",
		uuid.NewString(), id, payload); err != nil {
		return "", err
	}
	return id, tx.Commit()
}

Khác biệt chính giữa Java và GoKey differences between Java and Go

01Spring: @Transactional bao quanh hai repository.save là đủ, relay chạy bằng @Scheduled. Go: tự BeginTx/Commit tường minh và tự viết vòng lặp ticker trong goroutine.Spring: @Transactional around two repository.save calls is enough, the relay runs via @Scheduled. Go: explicit BeginTx/Commit and a hand-written ticker loop in a goroutine.
02Khoá dòng: Spring giữ lock nhờ @Transactional trên relay() (qua proxy). Go giữ lock nhờ mọi lệnh chạy trên cùng *sql.Tx.Row locks: Spring holds them thanks to @Transactional on relay() (via proxy). Go holds them because every statement runs on the same *sql.Tx.
03Gửi Kafka: KafkaTemplate.send trả CompletableFuture, gọi join() để đợi ack từng message. kafka-go WriteMessages gửi cả batch và đồng bộ chờ ack.Kafka sends: KafkaTemplate.send returns a CompletableFuture, join() waits per message. kafka-go's WriteMessages sends the whole batch and waits for acks synchronously.
04Hệ sinh thái Java có Debezium (cũng là Java) + Spring Modulith event publication registry. Bên Go thường tự viết poller, hoặc vẫn dùng Debezium như một hạ tầng ngoài.The Java ecosystem has Debezium (itself Java) + Spring Modulith's event publication registry. In Go teams usually write a poller, or still run Debezium as external infrastructure.

Ứng dụng thực tếReal-world usage

Debezium Outbox Event RouterDebezium Outbox Event Router
Cách triển khai outbox phổ biến nhất: Kafka Connect + Debezium đọc WAL/binlog, SMT EventRouter định tuyến mỗi dòng outbox thành event sạch.The most common outbox implementation: Kafka Connect + Debezium reading the WAL/binlog, with the EventRouter SMT turning each outbox row into a clean event.
Spring ModulithSpring Modulith
Event Publication Registry lưu event vào bảng event_publication trong cùng transaction và publish lại khi khởi động nếu chưa hoàn tất — một dạng outbox có sẵn.Its Event Publication Registry stores events in an event_publication table in the same transaction and republishes incomplete ones on restart — a built-in outbox.
Go: Watermill forwarderGo: Watermill forwarder
Watermill có component forwarder: publish vào SQL trong transaction, rồi forward sang Kafka/NATS — chính là outbox cho Go.Watermill's forwarder component publishes into SQL inside the transaction and then forwards to Kafka/NATS — an outbox for Go.
Thanh toán & thông báoPayments & notifications
Đơn đã thanh toán thì chắc chắn phải có event cho kho, kế toán, gửi Zalo/SMS — mất một event là khách đã trả tiền mà không nhận hàng.A paid order MUST produce events for inventory, accounting and Zalo/SMS notifications — losing one means a customer paid and never got their goods.

Khi nào dùng và khi nào khôngWhen to use it, and when not

Nên dùng khiUse it when

Thay đổi dữ liệu trong DB và phải phát event/message cho service khác một cách đáng tin cậy.You change data in the DB and must reliably emit an event/message to other services.
Các bước trong Saga choreography, hoặc đồng bộ read model của CQRS.Steps in a choreographed Saga, or syncing CQRS read models.
Broker có thể tạm thời không sẵn sàng nhưng request của người dùng không được phép lỗi vì thế.The broker may be temporarily unavailable but user requests must not fail because of it.

Không nên dùng khiAvoid it when

Event chỉ dùng nội bộ trong process và mất cũng không sao (cache invalidation, log phụ).Events are in-process only and losing one is harmless (cache invalidation, auxiliary logs).
Hệ thống dùng chính event store / Kafka làm nguồn dữ liệu (event sourcing trên Kafka) — đã không còn dual-write.The system uses the event store / Kafka itself as the source of truth (event sourcing on Kafka) — there's no dual-write left.

Ưu điểmPros

Không mất event, không có event 'ma': nguyên tử nhờ chính transaction của DB.No lost events, no 'phantom' events: atomic thanks to the DB's own transaction.
Request của người dùng không phụ thuộc broker đang sống hay chết.User requests don't depend on whether the broker is up.
Không cần distributed transaction (2PC/XA) phức tạp và chậm.No need for complex, slow distributed transactions (2PC/XA).

Nhược điểmCons

At-least-once: event có thể bị gửi trùng → consumer bắt buộc idempotent.At-least-once: events may be duplicated → consumers must be idempotent.
Thêm độ trễ (chu kỳ poll) và thêm thành phần vận hành (relay, Kafka Connect).Adds latency (poll interval) and operational parts (relay, Kafka Connect).
Bảng outbox phình to — cần job dọn dẹp các dòng đã gửi.The outbox table grows — you need a cleanup job for sent rows.

Anti-pattern: lỗi thường gặpAnti-pattern: common mistake

Dual-write: gửi Kafka trong @TransactionalDual-write: sending to Kafka inside @Transactional

Trông có vẻ an toàn vì nằm trong @Transactional, nhưng Kafka không tham gia transaction của DB. Nếu flush/commit DB lỗi sau khi Kafka đã nhận, kho sẽ trừ hàng cho một đơn không tồn tại. Đảo thứ tự cũng không cứu được: commit xong rồi Kafka lỗi thì event mất vĩnh viễn.It looks safe because it's inside @Transactional, but Kafka doesn't join the DB transaction. If the DB flush/commit fails after Kafka accepted the message, inventory reserves stock for an order that doesn't exist. Swapping the order doesn't help: commit first and a Kafka failure loses the event forever.

@Transactional
public UUID placeOrder(PlaceOrderRequest req) {
    Order order = orders.save(Order.place(req.customerId(), req.lines()));
    kafka.send("order.events", order.id().toString(), toJson(order)); // ❌ not in the DB tx
    loyalty.addPoints(order);   // ❌ throws -> DB rolls back, Kafka message already out
    return order.id();
}

Dễ nhầm vớiEasily confused with

Transactional Outbox vs Event Sourcing

Outbox là kênh vận chuyển event tạm thời (gửi xong có thể xoá); Event Sourcing lưu event vĩnh viễn làm nguồn sự thật.The Outbox is a temporary transport for events (delete after sending); Event Sourcing keeps events forever as the source of truth.

Transactional Outbox vs Saga

Saga điều phối nhiều bước giữa các service; Outbox đảm bảo mỗi bước phát event đáng tin cậy. Saga thường dựa trên Outbox.A Saga coordinates multi-step work across services; the Outbox makes each step's event emission reliable. Sagas usually rely on the Outbox.

Bài tập áp dụngExercise

Viết consumer InventoryService idempotent cho event OrderPlaced: nếu cùng eventId đến hai lần thì chỉ trừ kho một lần.Write an idempotent InventoryService consumer for OrderPlaced: if the same eventId arrives twice, reserve stock only once.

Kiểm tra kiến thứcKnowledge check

Câu 1 / 5Question 1 of 5

Outbox giải quyết vấn đề cốt lõi nào?What core problem does the Outbox solve?

Phím 1–4 để chọn đáp án, Enter để kiểm tra.Press 1–4 to choose an answer, Enter to check.

Thẻ ghi nhớFlashcards

Ôn tập ngắt quãng (spaced repetition): thẻ được lặp lại sau 1 → 3 → 7 → 14 → 30 ngày để củng cố trí nhớ dài hạn.Spaced repetition: cards are repeated after 1 → 3 → 7 → 14 → 30 days to build long-term memory.

Dùng trong bài toánUsed in problems

6 bài toán Backend dùng pattern này6 backend problems use this pattern

Pattern liên quanRelated patterns

Saga CQRS Event Sourcing Unit of Work

Thảo luậnDiscussion

Transactional Outboxaka Outbox, Outbox + Relay

VừaMedium

Mức phổ biếnUsage 4/5

~9 phút đọc~9 min read

package com.shop.order; import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.ObjectMapper; import com.shop.outbox.OutboxEvent; import com.shop.outbox.OutboxRepository; import java.util.UUID; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; @Service public class OrderService { private final OrderRepository orders; private final OutboxRepository outbox; private final ObjectMapper json; public OrderService(OrderRepository orders, OutboxRepository outbox, ObjectMapper json) { this.orders = orders; this.outbox = outbox; this.json = json; } @Transactional1 public UUID placeOrder(PlaceOrderRequest req) { Order order = orders.save(Order.place(req.customerId(), req.lines())); // Same DataSource, same transaction: both rows commit or neither does outbox.save(OutboxEvent.of(2 "order", order.id().toString(), "OrderPlaced", toJson(new OrderPlaced(order.id(), order.customerId(), order.total())))); // NOT kafkaTemplate.send(...) here: Kafka can't join this DB transaction3 return order.id(); } private String toJson(Object event) { try { return json.writeValueAsString(event); } catch (JsonProcessingException e) { throw new IllegalStateException("cannot serialize " + event, e); } } }

package order import ( "context" "database/sql" "encoding/json" "github.com/google/uuid" ) type OrderPlaced struct { OrderID string `json:"orderId"` CustomerID string `json:"customerId"` Total int64 `json:"total"` } type Service struct{ DB *sql.DB } func (s *Service) PlaceOrder(ctx context.Context, customerID string, total int64) (string, error) { id := uuid.NewString() payload, err := json.Marshal(OrderPlaced{OrderID: id, CustomerID: customerID, Total: total})1 if err != nil { return "", err } tx, err := s.DB.BeginTx(ctx, nil) if err != nil { return "", err } defer tx.Rollback() // no-op once committed2 if _, err := tx.ExecContext(ctx, "INSERT INTO orders (id, customer_id, total, status) VALUES ($1, $2, $3, 'PLACED')", id, customerID, total); err != nil { return "", err } // Same tx: the event exists if and only if the order exists3 if _, err := tx.ExecContext(ctx, "INSERT INTO outbox (id, aggregate_type, aggregate_id, type, payload) VALUES ($1, 'order', $2, 'OrderPlaced', $3)", uuid.NewString(), id, payload); err != nil { return "", err } return id, tx.Commit() }

@Transactional public UUID placeOrder(PlaceOrderRequest req) { Order order = orders.save(Order.place(req.customerId(), req.lines())); kafka.send("order.events", order.id().toString(), toJson(order)); // ❌ not in the DB tx loyalty.addPoints(order); // ❌ throws -> DB rolls back, Kafka message already out return order.id(); }