Chuyển tới nội dung chính

Giao dịch phân tán

Dependency govex-cloud-transaction giải quyết bài toán distributed transaction: một chuỗi thao tác trải trên nhiều database/kho dữ liệu trong cùng một nghiệp vụ. Cơ chế hoạt động: gắn XID nghiệp vụ cho toàn bộ chuỗi thao tác (qua annotation @XidTransactional) và ghi undo log (ChangeData) trong lúc thực thi, để có thể hoàn tác/bù trừ theo từng loại database khi một bước thất bại. XID ở đây là cơ chế định danh chuỗi giao dịch, không phải mục đích sử dụng.

Khi nào sử dụng​

  • Method cần chạy trong một transaction vật lý gắn với XID nghiệp vụ (mã đơn, mã hồ sơ...) để tra cứu/đối soát.
  • Cần undo log để hoàn tác các thay đổi dữ liệu của một giao dịch đã commit (ví dụ khi bước sau thất bại).
  • Cần lưu vết thay đổi (ảnh trước/sau) cho mục đích audit hoặc khôi phục dữ liệu.
  • Cần cơ chế rollback bù trừ theo từng database khi không thể dùng distributed transaction.

Cài đặt​

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-transaction</artifactId>
</dependency>

Version do BOM quản lý — xem Cài đặt.

Cấu hình​

PropertyMô tảMặc định
govex.transaction.enabledBật/tắt hỗ trợ giao dịch phân tán.true
govex.transaction.undo.enabledBật undo log; khi bật mới đăng ký UndoLogManager và listener ghi log.false
govex.transaction.undo.table-nameTên bảng lưu undo log.undo_log
govex.transaction.undo.data-validation-enableKiểm tra hợp lệ dữ liệu trước khi undo.true
govex.transaction.undo.delete-log-after-undoXoá bản ghi undo log sau khi undo thành công.true
govex.transaction.undo.serializerTên serializer encode/decode undo log.jackson
govex.transaction.undo.compress.enabledBật nén dữ liệu undo log trước khi lưu.true
govex.transaction.undo.compress.thresholdNgưỡng kích thước bắt đầu nén.64k
govex.transaction.undo.columns.*Tên cột trong bảng undo log (id, transaction-id, application, context, data, action-time, action-user).tên cột chuẩn

Sử dụng​

Bước 1 — khai báo cấu hình; tên ứng dụng ghi vào log lấy từ spring.application.name:

spring:
  application:
    name: order-service

govex:
  transaction:
    enabled: true
    undo:
      enabled: true
      table-name: undo_log
      delete-log-after-undo: true
      compress:
        enabled: true
        type: none

Bước 2 — tạo bảng undo log trong database, tối thiểu gồm các cột theo cấu hình mặc định: id, transaction_id, application, context, data, action_time, action_user (dependency không tự tạo bảng, xem Lưu ý).

Bước 3 — đánh dấu method cần giao dịch; xid là biểu thức SpEL, có thể tham chiếu tham số method:

@XidTransactional(xid = "#command.orderId")
public void placeOrder(PlaceOrderCommand command) {
    orderRepository.save(new Order(command.orderId()));
    stockService.decrease(command.orderId());
}

Bước 4 — khi cần hoàn tác (ví dụ từ job xử lý lỗi hoặc console quản trị):

undoLogManager.undo("order-123");

Lưu ý​

  • Điều kiện tiên quyết: cần govex-cloud-datasource (proxy connection thu thập ChangeData) và PlatformTransactionManager/TransactionTemplate của ứng dụng; thêm dependency datasource nếu chưa có.
  • govex.transaction.undo.enabled mặc định là false; phải đặt true mới có undo log.
  • Bảng undo_log chưa được tạo tự động (changeset của dependency hiện rỗng) — cần tạo bằng migration/DDL của ứng dụng trước khi dùng.
  • Undo log chỉ ghi khi thao tác đi qua datasource proxy của govex-cloud-datasource; ChangeData được listener xử lý trước khi transaction commit.
  • Dependency có sẵn undo executor cho MySQL, MariaDB, Oracle và PostgreSQL.
  • @XidTransactional chỉ áp dụng trên method và chỉ có hiệu lực khi gọi qua proxy Spring; biểu thức xid được dịch tại runtime nên cần đúng cú pháp SpEL.