Chuyển tới nội dung

BKACAD

Trang chủ / Kiến thức CNTT / Devops / API tạo đơn hàng bị gửi hai lần: Thiết kế idempotency trong Spring Boot

API tạo đơn hàng bị gửi hai lần: Thiết kế idempotency trong Spring Boot

Trong quá trình xây dựng hệ thống thương mại điện tử bằng Java Spring Boot, API tạo đơn hàng là một trong những chức năng cần được kiểm soát chặt chẽ về tính chính xác của dữ liệu. Một tình huống thường gặp là người dùng nhấn nút đặt hàng hai lần, trình duyệt tự động gửi lại request hoặc kết nối mạng bị gián đoạn khiến client không nhận được phản hồi từ server. Khi đó, người dùng có thể gửi lại yêu cầu dù đơn hàng đầu tiên đã được tạo thành công. Nếu Backend không có cơ chế kiểm soát, hệ thống có thể phát sinh nhiều đơn hàng giống nhau, gây sai lệch dữ liệu, tính tiền nhiều lần và ảnh hưởng đến trải nghiệm khách hàng. Để giải quyết vấn đề này, idempotency key Spring Boot là một giải pháp quan trọng giúp API xử lý các request lặp lại một cách an toàn. Vậy Idempotency Key hoạt động như thế nào và cần thiết kế ra sao để hạn chế tối đa tình trạng tạo đơn hàng trùng lặp?

1. Idempotency key Spring Boot là gì và vì sao API tạo đơn hàng cần sử dụng?

1.1. Khái niệm Idempotency và cơ chế hoạt động của Idempotency Key

Idempotency là tính chất của một thao tác mà khi được thực hiện nhiều lần với cùng một đầu vào, kết quả cuối cùng trên hệ thống vẫn tương đương với việc chỉ thực hiện một lần. Trong thiết kế REST API, tính chất này đặc biệt quan trọng đối với những thao tác có thể làm thay đổi dữ liệu như tạo đơn hàng, thanh toán hoặc đăng ký giao dịch.

Theo tiêu chuẩn HTTP RFC 9110, các phương thức như GET, PUT và DELETE có ngữ nghĩa idempotent theo định nghĩa của giao thức. Trong khi đó, POST thường không có tính chất này vì mỗi request có thể tạo ra một tài nguyên mới. Do đó, nếu client gửi cùng một yêu cầu POST nhiều lần, server có thể tạo ra nhiều bản ghi khác nhau.

Đây chính là lý do idempotency key Spring Boot được sử dụng. Idempotency Key là một mã định danh duy nhất do client tạo ra và gửi kèm request, thường thông qua HTTP Header có tên Idempotency-Key. Backend sử dụng mã này để xác định liệu một yêu cầu đã được xử lý trước đó hay chưa.

Ví dụ, khi người dùng nhấn nút đặt hàng, frontend tạo một key như sau:

POST /api/orders
Content-Type: application/json
Idempotency-Key: order-7f3a9c82-2026

{
  "productId": 101,
  "quantity": 2,
  "totalAmount": 500000
}

Nếu request bị timeout và frontend gửi lại đúng yêu cầu với cùng Idempotency Key, Backend sẽ kiểm tra khóa này trước khi thực hiện nghiệp vụ tạo đơn hàng. Nếu request trước đó đã xử lý thành công, hệ thống trả lại kết quả đã lưu thay vì tạo thêm một đơn hàng mới.

Như vậy, idempotency key Spring Boot không đơn thuần là một mã chống nhấn nút nhiều lần. Đây là cơ chế nhận diện request trùng lặp ở phía server, giúp hệ thống duy trì tính nhất quán ngay cả khi xảy ra lỗi mạng hoặc client tự động retry.

1.2. Những tình huống khiến API tạo đơn hàng bị gửi hai lần

Trong thực tế, duplicate request có thể xuất hiện từ nhiều nguyên nhân khác nhau. Thứ nhất là thao tác của người dùng: họ nhấn nút đặt hàng liên tục vì giao diện chưa phản hồi hoặc không biết request đầu tiên đã được gửi thành công hay chưa. Thứ hai là vấn đề mạng: server đã xử lý và lưu đơn hàng nhưng phản hồi không đến được trình duyệt. Khi client gửi lại request, hệ thống có nguy cơ tạo thêm đơn hàng mới.

Ngoài ra, các cơ chế tự động retry trong frontend, API Gateway hoặc hệ thống phân tán cũng có thể khiến một request được gửi nhiều lần. Đặc biệt, khi Backend xử lý nhiều request đồng thời (concurrent requests), hai request có cùng nội dung có thể cùng vượt qua bước kiểm tra dữ liệu nếu hệ thống chỉ sử dụng một câu lệnh truy vấn thông thường.

Ví dụ, hai request cùng kiểm tra xem đơn hàng đã tồn tại hay chưa. Nếu cả hai đều nhận kết quả chưa tồn tại trước khi bất kỳ request nào ghi dữ liệu, cả hai có thể tiếp tục tạo đơn hàng. Đây là một dạng race condition thường gặp trong các ứng dụng Backend.

Vì vậy, chỉ vô hiệu hóa nút đặt hàng ở frontend hoặc kiểm tra dữ liệu bằng câu lệnh SELECT là chưa đủ. Một hệ thống cần cơ chế kiểm soát request trùng lặp ngay tại Backend, kết hợp với ràng buộc dữ liệu trong database để bảo vệ tính toàn vẹn của hệ thống.

2. Cách thiết kế và triển khai idempotency key Spring Boot để chống tạo đơn hàng trùng lặp

2.1. Thiết kế luồng xử lý Idempotency Key trong Spring Boot

Để triển khai idempotency key Spring Boot, trước tiên cần xây dựng một luồng xử lý thống nhất giữa client, server và database. Thay vì tạo đơn hàng ngay khi nhận POST request, Backend cần kiểm tra Idempotency Key trước khi thực hiện nghiệp vụ.

Một thiết kế phổ biến gồm các bước sau:

  • Bước 1 – Nhận request: Client gửi yêu cầu tạo đơn hàng kèm Idempotency Key trong HTTP Header.
  • Bước 2 – Kiểm tra key: Backend tìm kiếm khóa trong database dựa trên phạm vi định danh phù hợp, chẳng hạn người dùng và loại thao tác.
  • Bước 3 – Kiểm tra nội dung request: Hệ thống so sánh hash của payload hiện tại với payload đã được ghi nhận. Nếu cùng key nhưng nội dung khác nhau, Backend từ chối xử lý.
  • Bước 4 – Xử lý đơn hàng: Nếu key chưa tồn tại, hệ thống ghi nhận khóa và thực hiện nghiệp vụ tạo đơn hàng.
  • Bước 5 – Lưu kết quả: Sau khi tạo đơn hàng thành công, Backend lưu mã đơn hàng, HTTP status và response cần thiết để sử dụng cho những lần retry tiếp theo.
  • Bước 6 – Trả kết quả: Nếu client gửi lại request với cùng key và cùng payload, hệ thống trả lại kết quả đã lưu thay vì thực hiện lại nghiệp vụ.
    Ensuring Reliable Payment Systems with Idempotency - DEV CommunityEnsuring Reliable Payment Systems with Idempotency - DEV Community

Để quản lý quá trình này, database có thể sử dụng một bảng riêng với tên idempotency_records. Bảng này lưu các thông tin như:

Trường dữ liệuÝ nghĩa
idKhóa chính của bản ghi
idempotency_keyMã định danh request
user_idNgười dùng thực hiện thao tác
request_hashHash của nội dung request
statusTrạng thái xử lý
response_statusHTTP status đã trả về
response_bodyNội dung phản hồi đã lưu
created_atThời điểm tạo khóa
expires_atThời điểm khóa hết hạn

Trong đó, idempotency_key cần được ràng buộc UNIQUE theo phạm vi sử dụng. Ví dụ, có thể tạo unique constraint trên cặp (user_id, operation_type, idempotency_key) để tránh xung đột giữa các người dùng hoặc các nghiệp vụ khác nhau.

Một điểm quan trọng là việc lưu Idempotency Key và tạo đơn hàng cần được thiết kế có tính nguyên tử trong phạm vi database transaction. Nếu đơn hàng được tạo nhưng bản ghi idempotency không được lưu, request retry vẫn có thể tạo thêm đơn hàng. Ngược lại, nếu khóa được ghi nhận nhưng nghiệp vụ tạo đơn hàng thất bại mà trạng thái không được xử lý đúng, hệ thống có thể từ chối những lần thử lại hợp lệ.

2.2. Triển khai Idempotency Key bằng Spring Boot và Spring Data JPA

Sau khi xác định được cấu trúc dữ liệu, lập trình viên có thể triển khai cơ chế idempotency key Spring Boot bằng Spring Data JPA và Spring Transaction.

Trước tiên, tạo entity đại diện cho bảng lưu Idempotency Key:

@Entity
@Table(
    name = "idempotency_records",
    uniqueConstraints = @UniqueConstraint(
        columnNames = {
            "user_id",
            "operation_type",
            "idempotency_key"
        }
    )
)
public class IdempotencyRecord {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private Long userId;

    private String operationType;

    private String idempotencyKey;

    private String requestHash;

    private String status;

    private Long orderId;

    private Integer responseStatus;

    @Column(columnDefinition = "TEXT")
    private String responseBody;

    private LocalDateTime createdAt;

    private LocalDateTime expiresAt;

    // Getters and setters
}

Tiếp theo, tạo Repository để truy vấn bản ghi theo key:

public interface IdempotencyRepository
        extends JpaRepository<IdempotencyRecord, Long> {

    Optional<IdempotencyRecord>
        findByUserIdAndOperationTypeAndIdempotencyKey(
            Long userId,
            String operationType,
            String idempotencyKey
        );
}

Ở tầng Service, cần triển khai logic kiểm tra key, đối chiếu request hash và xử lý tạo đơn hàng. Có thể mô tả luồng nghiệp vụ cốt lõi như sau:

@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final IdempotencyRepository idempotencyRepository;

    public OrderService(
            OrderRepository orderRepository,
            IdempotencyRepository idempotencyRepository) {
        this.orderRepository = orderRepository;
        this.idempotencyRepository = idempotencyRepository;
    }

    @Transactional
    public Order createOrder(
            Long userId,
            String key,
            String requestHash,
            OrderRequest request) {

        var existing = idempotencyRepository
            .findByUserIdAndOperationTypeAndIdempotencyKey(
                userId, "CREATE_ORDER", key
            );

        if (existing.isPresent()) {
            var record = existing.get();

            if (!record.getRequestHash().equals(requestHash)) {
                throw new IllegalArgumentException(
                    "Idempotency key reused with different payload"
                );
            }

            if ("COMPLETED".equals(record.getStatus())) {
                return orderRepository.findById(
                    record.getOrderId()
                ).orElseThrow();
            }
        }

        IdempotencyRecord record = new IdempotencyRecord();
        record.setUserId(userId);
        record.setOperationType("CREATE_ORDER");
        record.setIdempotencyKey(key);
        record.setRequestHash(requestHash);
        record.setStatus("PROCESSING");

        idempotencyRepository.saveAndFlush(record);

        Order order = new Order();
        order.setUserId(userId);
        order.setStatus("PENDING");

        Order savedOrder = orderRepository.save(order);

        record.setOrderId(savedOrder.getId());
        record.setStatus("COMPLETED");

        idempotencyRepository.save(record);

        return savedOrder;
    }
}

Đây là ví dụ minh họa logic cốt lõi, chưa phải implementation hoàn chỉnh cho môi trường production. Trong thực tế, cần bổ sung cơ chế xử lý request đồng thời và quản lý lỗi transaction.

Cụ thể, hai request có thể cùng truy vấn và nhận kết quả chưa tồn tại trước khi cùng ghi khóa. Vì vậy, unique constraint trong database đóng vai trò là lớp bảo vệ cuối cùng. Khi một request ghi thành công, request còn lại sẽ gặp xung đột khóa duy nhất. Backend cần xử lý lỗi này sau khi transaction của request thua cuộc đã rollback, sau đó đọc lại bản ghi đã được tạo để trả kết quả phù hợp. Không nên chỉ dựa vào câu lệnh kiểm tra exists trước khi insert vì thao tác kiểm tra và ghi dữ liệu không được bảo đảm nguyên tử.

Ngoài ra, việc sử dụng @Transactional giúp các thao tác trên database tham gia cùng một transaction. Nếu quá trình tạo đơn hàng thất bại, dữ liệu liên quan trong transaction có thể được rollback, tránh trường hợp lưu trạng thái hoàn thành khi đơn hàng chưa được tạo.

2.3. Những lưu ý quan trọng khi triển khai Idempotency trong môi trường thực tế

Khi đưa idempotency key Spring Boot vào production, lập trình viên cần quan tâm đến nhiều yếu tố hơn việc tạo key và kiểm tra dữ liệu.

Thứ nhất, cần xác định phạm vi sử dụng key. Một key nên gắn với người dùng hoặc tài khoản thực hiện thao tác, loại nghiệp vụ và request tương ứng. Không nên sử dụng một khóa chung cho tất cả người dùng vì có thể gây xung đột hoặc tạo ra rủi ro về dữ liệu.

Thứ hai, cần kiểm tra tính nhất quán của payload. Nếu một request đã được xử lý với key A và người dùng gửi lại key A nhưng thay đổi số lượng sản phẩm hoặc giá trị đơn hàng, hệ thống không nên trả lại kết quả cũ một cách âm thầm. Thay vào đó, cần so sánh request hash và trả về lỗi phù hợp, chẳng hạn HTTP 409 Conflict.

Thứ ba, cần thiết kế trạng thái xử lý rõ ràng. Một số trạng thái thường được sử dụng gồm PROCESSING, COMPLETED và FAILED. Khi request đang được xử lý, request trùng lặp có thể nhận phản hồi HTTP 409 hoặc 202 tùy theo thiết kế API. Khi xử lý thành công, hệ thống trả lại kết quả đã lưu. Khi thất bại, cần xác định rõ có cho phép retry bằng key cũ hay không và cách khôi phục trạng thái.

Thứ tư, cần thiết lập thời gian tồn tại của key (TTL). Nếu lưu tất cả khóa vĩnh viễn, database sẽ ngày càng tăng dung lượng. Tuy nhiên, thời gian hết hạn cần được lựa chọn dựa trên đặc điểm nghiệp vụ và khoảng thời gian client có thể retry. Những giao dịch tài chính quan trọng có thể cần lưu dấu vết lâu hơn để phục vụ đối soát.

Cuối cùng, cần phân biệt giữa idempotency trong database và các tác động bên ngoài. Ví dụ, việc tạo đơn hàng có thể thành công nhưng gửi yêu cầu thanh toán đến cổng thanh toán lại gặp lỗi. Khi đó, chỉ sử dụng @Transactional không thể bảo đảm rollback giao dịch ở hệ thống bên ngoài. Một giải pháp phù hợp là kết hợp Transactional Outbox, cơ chế retry và Idempotency Key của nhà cung cấp thanh toán để kiểm soát các tác động phân tán.

Kết luận

Tình trạng API tạo đơn hàng bị gửi hai lần là một vấn đề phổ biến trong quá trình phát triển Backend, đặc biệt với những hệ thống thương mại điện tử có nhiều request đồng thời và phụ thuộc vào kết nối mạng. Việc triển khai idempotency key Spring Boot giúp hệ thống nhận diện request lặp lại, tránh tạo nhiều đơn hàng cho cùng một thao tác và duy trì tính nhất quán của dữ liệu. Tuy nhiên, để đạt hiệu quả trong môi trường thực tế, lập trình viên cần kết hợp Idempotency Key với database unique constraint, transaction, kiểm tra request hash và cơ chế xử lý concurrent requests. Nếu muốn xây dựng nền tảng chuyên môn vững chắc về Java Backend, REST API, Spring Data JPA và quản lý transaction, bạn có thể tham khảo khóa học Backend Java Spring Boot tại BKACAD. Khóa học là lựa chọn phù hợp để từng bước nâng cao kỹ năng xây dựng và triển khai các ứng dụng Backend bằng Java Spring Boot.

Chia sẻ bài viết

Bài viết liên quan

Chuẩn hóa lỗi validation trong REST API Spring Boot để frontend hiển thị đúng trường

Trong quá trình phát triển ứng dụng web, việc kiểm tra dữ liệu đầu vào (Validation) là một bước quan trọng nhằm đảm bảo tính chính xác và nhất quán...

Học Photoshop từ cơ bản đến nâng cao: Lộ trình cho người mới

Học Photoshop từ cơ bản đến nâng cao nên bắt đầu với giao diện, Layer, công cụ tạo vùng chọn và Layer Mask, sau đó chuyển sang chỉnh màu, retouch...

Thiết kế ấn phẩm truyền thông là gì? Kỹ năng cần có

Thiết kế ấn phẩm truyền thông là quá trình sử dụng hình ảnh, màu sắc, typography và bố cục để tạo ra các sản phẩm phục vụ hoạt động quảng bá, giới...

Học Canva có đủ để làm thiết kế đồ họa chuyên nghiệp?

Học Canva có thể đủ để thực hiện nhiều công việc thiết kế đồ họa chuyên nghiệp ở mức cơ bản đến trung cấp, đặc biệt trong Social Media, Content...

Tư duy thiết kế là gì? 7 nguyên tắc thiết kế chuyên nghiệp

Tư duy thiết kế là khả năng phân tích vấn đề, tổ chức thông tin và lựa chọn các yếu tố thị giác để tạo ra sản phẩm vừa có tính thẩm mỹ, vừa truyền tải...

Người trái ngành có thể trở thành Graphic Designer không?

Người không học đúng chuyên ngành hoàn toàn có thể trở thành Graphic Designer nếu xây dựng được nền tảng tư duy thiết kế, sử dụng thành thạo các công...