Wallet / TransactionWallet / Transaction

ví đang hoạt độngactive wallets

5M

ví đang hoạt độngactive wallets

giao dịch lúc cao điểmtransactions at peak

~2,000/s

giao dịch lúc cao điểmtransactions at peak

p99 cho một lần chuyểnp99 for one transfer

< 200ms

p99 cho một lần chuyểnp99 for one transfer

số dư âm hoặc trừ trùngnegative balances or double debits

0

số dư âm hoặc trừ trùngnegative balances or double debits

Wallet API nhận lệnh chuyển kèm request id, ghi hai bút toán và cập nhật số dư trong một transaction trên Postgres, rồi phát sự kiện qua outbox. Job đối soát cộng lại ledger để kiểm tra số dư cache. Chọn “Hai lệnh rút đồng thời” để xem khoá dòng chặn double spending, hoặc “Retry cùng request id” để xem idempotency.The Wallet API takes a transfer with a request id, writes two ledger entries and updates balances in one Postgres transaction, then publishes an event through the outbox. A reconciliation job re-sums the ledger to check the cached balances. Pick “Two concurrent withdrawals” to see the row lock stop double spending, or “Retry with the same request id” to see idempotency.

1. 1

   Double spending khi có request đồng thờiDouble spending under concurrent requests

   Đọc số dư rồi mới trừ ở tầng ứng dụng là race condition. Dùng UPDATE … SET balance = balance − x WHERE balance − held ≥ x, hoặc SELECT … FOR UPDATE rồi kiểm tra trong cùng transaction.Reading the balance and then subtracting in application code is a race. Use UPDATE … SET balance = balance − x WHERE balance − held ≥ x, or SELECT … FOR UPDATE and check inside the same transaction.

   Unit of Work
2. 2

   Deadlock khi chuyển ngược chiềuDeadlocks on opposite transfers

   A→B và B→A cùng lúc, mỗi bên giữ một khoá và chờ khoá kia. Luôn khoá theo thứ tự id tăng dần; nếu DB vẫn báo deadlock thì retry có backoff.A→B and B→A at once, each holding one lock and waiting for the other. Always lock in ascending id order; if the DB still reports a deadlock, retry with backoff.

   Retry with Exponential Backoff
3. 3

   Retry làm trừ tiền hai lầnRetries debiting twice

   Client retry khi timeout dù server đã commit. Bảng transfer có unique(request_id); request lặp trả về kết quả đã lưu. Hai retry chạy song song thì bên sau vướng unique constraint và rollback.Clients retry on timeout even when the server already committed. The transfer table has unique(request_id); a repeated request gets the stored result. Two parallel retries: the later one hits the unique constraint and rolls back.

   Command
4. 4

   Số dư lệch khỏi lịch sửBalance drifting from history

   Ledger kép là nguồn sự thật: mỗi giao dịch có ít nhất hai dòng, tổng bằng 0. Cột balance chỉ là cache có version, cập nhật trong cùng transaction và được đối soát lại từ ledger.The double-entry ledger is the source of truth: each transaction has at least two rows that sum to zero. The balance column is only a versioned cache, updated in the same transaction and re-checked against the ledger.

   Event SourcingUnit of Work
5. 5

   Giữ tiền khi đơn chưa xác nhậnHolding funds before an order is confirmed

   Tạo hold làm tăng held_minor, số dư khả dụng = balance − held. Capture chuyển hold thành bút toán thật; release hoặc hết hạn thì giảm held. Hold có trạng thái ACTIVE → CAPTURED · RELEASED · EXPIRED.Creating a hold raises held_minor; available = balance − held. Capture turns the hold into real entries; release or expiry lowers held. A hold moves ACTIVE → CAPTURED · RELEASED · EXPIRED.

   State
6. 6

   Sửa sai giao dịchCorrecting a wrong transaction

   Không UPDATE hay DELETE dòng ledger. Ghi bút toán đảo tham chiếu giao dịch gốc, nên kiểm toán thấy cả lỗi và lần sửa.Never UPDATE or DELETE a ledger row. Write an offsetting entry that points at the original, so auditors see both the mistake and the fix.

   CommandEvent Sourcing

Java: chuyển tiền giữa hai ví, khoá theo thứ tự cố định, ghi hai bút toán và outbox. Go: rút tiền không cần SELECT … FOR UPDATE, dựa vào UPDATE có điều kiện và INSERT … ON CONFLICT cho idempotency.Java: a transfer between two wallets that locks in a fixed order and writes two entries plus the outbox. Go: a withdrawal without SELECT … FOR UPDATE, relying on a conditional UPDATE and INSERT … ON CONFLICT for idempotency.

@Service
@RequiredArgsConstructor
public class TransferService {
    private final TransferRepository transfers;
    private final AccountRepository accounts;
    private final LedgerRepository ledger;
    private final OutboxRepository outbox;

    @Transactional
    public Transfer transfer(TransferCommand cmd) {
        Optional<Transfer> done = transfers.findByRequestId(cmd.requestId());
        if (done.isPresent()) return done.get();           // retry: same answer1

        long first = Math.min(cmd.fromId(), cmd.toId());
        long second = Math.max(cmd.fromId(), cmd.toId());
        Account a = accounts.lockById(first);              // SELECT … FOR UPDATE2
        Account b = accounts.lockById(second);
        Account from = a.id() == cmd.fromId() ? a : b;
        Account to = from == a ? b : a;

        long amount = cmd.amountMinor();
        if (from.available() < amount) {                    // balance - held3
            throw new InsufficientFundsException(from.id(), from.available());
        }
        Transfer t = transfers.save(Transfer.completed(cmd)); // unique(request_id)
        ledger.save(LedgerEntry.of(t, from, -amount));4
        ledger.save(LedgerEntry.of(t, to, amount));
        from.debit(amount);                                 // @Version bumps on flush
        to.credit(amount);
        outbox.save(OutboxEvent.of("wallet.transferred", t));
        return t;
    }
}

// Withdraw debits a wallet without SELECT … FOR UPDATE:
// the WHERE clause is the check, the row lock taken by UPDATE is the guard.
func (w *Wallet) Withdraw(ctx context.Context, req WithdrawReq) error {
	tx, err := w.db.BeginTx(ctx, nil)
	if err != nil {
		return err
	}
	defer tx.Rollback()

	var transferID int64
	err = tx.QueryRowContext(ctx,
		`INSERT INTO transfer(request_id, from_account, to_account, amount_minor, status)
		 VALUES ($1, $2, $3, $4, 'COMPLETED') ON CONFLICT (request_id) DO NOTHING RETURNING id`,1
		req.RequestID, req.AccountID, CashOutAccountID, req.Amount).Scan(&transferID)
	if errors.Is(err, sql.ErrNoRows) {
		return nil // same request id already applied
	}
	if err != nil {
		return err
	}

	res, err := tx.ExecContext(ctx,
		`UPDATE account SET balance_minor = balance_minor - $1, version = version + 1
		 WHERE id = $2 AND balance_minor - held_minor >= $1`,2
		req.Amount, req.AccountID)
	if err != nil {
		return err
	}
	if n, _ := res.RowsAffected(); n == 0 {
		return ErrInsufficientFunds // rollback also drops the transfer row3
	}

	if _, err := tx.ExecContext(ctx,
		`INSERT INTO ledger_entry(transfer_id, account_id, amount_minor)
		 VALUES ($1, $2, $3), ($1, $4, $5)`,4
		transferID, req.AccountID, -req.Amount, CashOutAccountID, req.Amount); err != nil {
		return err
	}
	return tx.Commit()
}

Mỗi pattern mở bài học tương ứng trong menu Pattern.Each one opens its lesson in the Patterns menu.