Idempotency là gì? Vì sao bấm thanh toán hai lần mà hệ thống chỉ được xử lý một lần?

Idempotency là gì? Vì sao bấm thanh toán hai lần mà hệ thống chỉ được xử lý một lần?
Idempotency là gì? Hướng dẫn chống tạo đơn hàng, thanh toán và webhook trùng lặp khi retry API, có ví dụ SQL Server, ASP.NET Core và Idempotency-Key.

Xem nhanh:

Có một tình huống mà người làm website bán hàng không muốn gặp.

Khách hàng chọn sản phẩm, điền thông tin và nhấn nút thanh toán. Màn hình xoay một lúc, rồi không thấy phản hồi.

Khách bấm thêm lần nữa.

Lần thứ hai, hệ thống thông báo thành công. Nhưng phía sau, có thể đã xuất hiện hai yêu cầu thanh toán, hai đơn hàng hoặc hai tác vụ xử lý cùng một nghiệp vụ.

Khách hàng chỉ muốn thanh toán một lần.

Hệ thống lại làm hai lần.

Chú Nha 27 tuổi nghĩ rằng những ai từng xây dựng phần mềm có giao dịch đều nên hiểu rõ tình huống này, đặc biệt khi sử dụng AI Coding để phát triển API.

Vấn đề không đơn giản là khách bấm nút hai lần. Một request còn có thể được gửi lại bởi trình duyệt, ứng dụng mobile, API Gateway, HTTP client, queue worker hoặc nhà cung cấp webhook.

Đôi khi request đầu tiên đã được xử lý thành công, nhưng phản hồi bị mất trên đường truyền.

Phía gửi không biết kết quả nên thử lại.

Vậy làm sao để hệ thống biết đây là lần thử lại của cùng một yêu cầu, chứ không phải một giao dịch hoàn toàn mới?

Đó là bài toán Idempotency.

Trong bài này, chúng ta sẽ tìm hiểu Idempotency là gì, phân biệt với việc chống bấm nút hai lần, cách thiết kế Idempotency-Key, xử lý race condition, lưu trạng thái trên SQL Server, gọi cổng thanh toán an toàn và kiểm tra webhook không bị xử lý trùng.

Tôi cũng sẽ hướng dẫn cách giao AI Coding Agent triển khai tính năng này mà không chỉ thêm một câu lệnh if rồi tuyên bố đã giải quyết xong.

1. Idempotency là gì?

Idempotency là tính chất mà một thao tác được thực hiện nhiều lần với cùng ý định vẫn tạo ra tác động cuối cùng tương đương với việc thực hiện một lần, trong phạm vi hợp đồng hành vi đã xác định.

Trong toán học, một phép biến đổi f được gọi là idempotent nếu:

f(f(x)) = f(x)

Trong hệ thống phần mềm, chúng ta thường quan tâm đến việc tránh lặp lại những tác động nghiệp vụ ngoài ý muốn.

Ví dụ, khách hàng gửi yêu cầu tạo một giao dịch thanh toán. Do timeout, ứng dụng gửi lại đúng yêu cầu ấy.

Nếu API được thiết kế idempotent, việc retry không được tạo ra thêm một giao dịch thu tiền độc lập cho cùng ý định thanh toán.

Lưu ý rằng Idempotency không có nghĩa là hai request phải trả về phản hồi hoàn toàn giống nhau trong mọi hệ thống.

Cách trả về kết quả phụ thuộc vào hợp đồng API. Có API phát lại phản hồi ban đầu, có API trả về trạng thái hiện tại của cùng một giao dịch.

Điều quan trọng là tác động nghiệp vụ không bị nhân đôi trái ý muốn.

2. Vì sao request đầu tiên thành công nhưng ứng dụng vẫn báo lỗi?

Hãy xem một kịch bản.

KHÁCH HÀNG
        | | POST /payments
        v
BACKEND
        | | Create payment
        v
PAYMENT PROVIDER
        | | Payment created successfully
        v
BACKEND
        | | Return response     X NETWORK TIMEOUT  CLIENT: Không nhận được phản hồi. Không biết giao dịch thành công chưa.  CLIENT: Retry request.

Nếu backend coi lần retry là một yêu cầu hoàn toàn mới, nó có thể tạo thêm một giao dịch khác.

Điều đáng chú ý là timeout không chứng minh thao tác đầu tiên thất bại.

Timeout chỉ cho biết phía chờ phản hồi không nhận được kết quả trong khoảng thời gian quy định.

Đây là một khác biệt rất quan trọng khi thiết kế thanh toán, đặt chỗ và các hệ thống phân tán.

AWS Builders' Library phân tích sâu vấn đề này trong tài liệu Making retries safe with idempotent APIs. Một trong những mục tiêu của thiết kế idempotent là cho phép phía gọi retry khi kết quả chưa rõ mà không vô tình lặp lại tác động đã xảy ra.

3. Idempotency khác chống bấm nút hai lần như thế nào?

Một cách xử lý phổ biến trên frontend là vô hiệu hóa nút thanh toán sau khi người dùng nhấn lần đầu.

Ví dụ:

button.disabled = true;

Cách này có ích cho trải nghiệm người dùng.

Nhưng không đủ.

Người dùng có thể reload trang, mất kết nối, mở thêm tab hoặc gửi request trực tiếp đến API.

Ứng dụng mobile có thể tự retry. Một hệ thống trung gian cũng có thể gửi lại request.

Vì vậy, cần phân biệt:

  • Chống bấm nút hai lần: Giảm thao tác lặp từ giao diện.
  • Idempotency ở backend: Kiểm soát việc xử lý lặp lại cùng một ý định nghiệp vụ.

Frontend vẫn nên khóa nút trong lúc chờ phản hồi và hiển thị trạng thái rõ ràng.

Nhưng backend phải là nơi bảo vệ tính đúng đắn của giao dịch.

4. Có phải mọi API đều cần Idempotency-Key?

Không nhất thiết.

RFC 9110 mô tả tính idempotent của các phương thức HTTP. PUT và DELETE được định nghĩa là idempotent theo ngữ nghĩa của phương thức, còn POST không mặc nhiên có tính chất này.

Tuy nhiên, điều đó không có nghĩa một API sử dụng PUT hoặc DELETE sẽ tự động được triển khai an toàn trong mọi tình huống.

Ví dụ, một endpoint DELETE có thể được thiết kế đúng để xóa một tài nguyên. Gọi lại nhiều lần không làm tài nguyên bị xóa thêm lần nữa.

Nhưng nếu mỗi lần gọi endpoint ấy lại phát sinh một khoản phí mới hoặc gửi một tác vụ không có cơ chế chống trùng, thiết kế thực tế vẫn có vấn đề.

Đối với POST tạo đơn hàng, thanh toán hoặc phát hành phiếu, cần xem xét cơ chế Idempotency-Key hoặc một cơ chế định danh ý định nghiệp vụ tương đương.

Không nên áp dụng một kiểu khóa cho tất cả API mà không phân tích mục tiêu của từng thao tác.

5. Idempotency-Key là gì?

Idempotency-Key là một mã định danh được dùng để nhận biết những lần gửi lại của cùng một yêu cầu nghiệp vụ.

Thông thường, phía client tạo một mã đủ khó trùng và sử dụng lại mã đó khi retry cùng thao tác.

Ví dụ:

POST /api/payments/deposit Idempotency-Key: 7a4c20b5-demo-001

{

"orderId": 10025,

"amount": 300000,

"currency": "VND" }

Giả sử request đầu tiên đã tạo một payment operation với mã PAY-10025.

Khi client retry với cùng Idempotency-Key và cùng nội dung nghiệp vụ, API phải nhận diện đây là cùng một thao tác.

Nó không nên tạo thêm payment operation độc lập.

Trong ứng dụng thực tế, nên sử dụng UUID v4 hoặc một mã ngẫu nhiên có độ entropy phù hợp thay cho mã minh họa dễ đoán phía trên.

Không sử dụng email, số điện thoại, CCCD hoặc dữ liệu cá nhân làm Idempotency-Key.

6. Khi nào giữ nguyên key và khi nào tạo key mới?

Đây là quy tắc quan trọng mà AI Coding Agent cần hiểu.

Cùng ý định nghiệp vụ, retry cùng key.

Ý định nghiệp vụ mới, sử dụng key mới.

Ví dụ:

Khách tạo yêu cầu thanh toán A Key = K001

Request timeout.

Retry yêu cầu thanh toán A Key = K001

Retry lần nữa Key = K001

Ngược lại, nếu khách hàng thực sự bắt đầu một giao dịch mới được nghiệp vụ cho phép, cần sử dụng một key khác.

Không nên tạo key mới ở mỗi lần retry, bởi khi đó backend có thể xem các lần gửi lại là những yêu cầu độc lập.

Cũng không nên sử dụng một key duy nhất cho tất cả lần thanh toán của một khách hàng.

Key phải gắn với một ý định nghiệp vụ cụ thể.

7. Nếu cùng key nhưng nội dung request khác nhau thì sao?

Giả sử request đầu tiên:

Key: K001 Order: 10025 Amount: 300000 VND

Request tiếp theo:

Key: K001 Order: 10025 Amount: 500000 VND

Đây không còn là một lần retry tương đương.

Nếu backend chỉ kiểm tra key rồi phát lại kết quả cũ, nó có thể che giấu một lỗi nghiêm trọng trong ứng dụng hoặc quy trình thanh toán.

Vì vậy, nên lưu thêm dấu vân tay của nội dung nghiệp vụ, thường gọi là Request Fingerprint hoặc Request Hash.

Khi nhận lại cùng key:

  • Nếu fingerprint giống nhau, áp dụng chính sách retry của thao tác ban đầu.
  • Nếu fingerprint khác nhau, từ chối theo hợp đồng API, chẳng hạn trả HTTP 409 Conflict.

Stripe cũng mô tả cơ chế so sánh tham số khi một Idempotency-Key được sử dụng lại.

Lưu ý rằng thuật toán tạo fingerprint phải nhất quán. Không nên hash trực tiếp một chuỗi JSON có thứ tự thuộc tính thay đổi tùy cách serialize rồi coi hai request có ý nghĩa giống nhau là khác nhau.

8. Thiết kế vòng đời một yêu cầu idempotent

Với một API tạo payment operation, chúng ta có thể sử dụng các trạng thái:

RECEIVED    |    v PENDING    |    +---- PROCESSING    |        |    |        +---- SUCCEEDED    |        |    |        +---- FAILED    |        |    |        +---- UNKNOWN    |    +---- REJECTED

Đây là mô hình tham khảo, không phải một chuẩn trạng thái bắt buộc.

Điểm cần giữ là phân biệt kết quả đã chắc chắn với kết quả chưa thể xác nhận.

Ví dụ, timeout khi gọi cổng thanh toán không đủ để kết luận FAILED.

Giao dịch có thể đã thành công tại phía nhà cung cấp.

Trường hợp ấy có thể cần trạng thái UNKNOWN hoặc PENDING_RECONCILIATION, sau đó kiểm tra lại bằng API tra cứu hoặc cơ chế đối soát của nhà cung cấp.

Không nên tự động tạo một payment mới chỉ vì phản hồi lần trước bị timeout.

9. Lưu Idempotency-Key trong SQL Server

Đây là phần thực hành chính của bài.

Giả sử chúng ta có một ứng dụng ASP.NET Core kết nối SQL Server.

Đầu tiên, tạo bảng lưu các yêu cầu đã tiếp nhận.

Ví dụ dưới đây chỉ dùng cho database thử nghiệm; cần review schema, chỉ mục, thời hạn lưu trữ và phương án migration trước khi áp dụng vào hệ thống đang vận hành.

CREATE TABLE dbo.PaymentOperations (

OperationId UNIQUEIDENTIFIER

NOT NULL PRIMARY KEY,

TenantId BIGINT NOT NULL,

OrderId BIGINT NOT NULL,

IdempotencyKey NVARCHAR(120)

NOT NULL,

RequestHash CHAR(64) NOT NULL,

Status VARCHAR(20) NOT NULL,

ProviderPaymentId NVARCHAR(120) NULL,

CreatedAt DATETIME2 NOT NULL

DEFAULT SYSUTCDATETIME(),

UpdatedAt DATETIME2 NOT NULL

DEFAULT SYSUTCDATETIME(),

CONSTRAINT UQ_PaymentOperations_Key

UNIQUE (TenantId, IdempotencyKey),

CONSTRAINT CK_PaymentOperations_Status

CHECK (

Status IN (

'PENDING',

'PROCESSING',

'SUCCEEDED',

'FAILED',

'UNKNOWN'

)

) );

Điều đáng chú ý là unique constraint trên TenantId và IdempotencyKey.

Hai yêu cầu cùng key trong cùng tenant không được tạo ra hai dòng PaymentOperations độc lập.

Với hệ thống không có tenant, có thể thiết kế phạm vi khóa theo chủ thể hoặc API phù hợp.

Tuy nhiên, chỉ có bảng này chưa giải quyết toàn bộ vấn đề thanh toán trùng.

Chúng ta còn phải kiểm soát các hành động bên ngoài database.

10. Vì sao kiểm tra SELECT rồi INSERT vẫn có thể sai?

Một cách viết dễ gặp:

IF NOT EXISTS (

SELECT 1

FROM dbo.PaymentOperations

WHERE TenantId = @TenantId

AND IdempotencyKey = @Key ) BEGIN

INSERT INTO dbo.PaymentOperations (...)

VALUES (...); END;

Nhìn qua hợp lý.

Nhưng hai request có thể chạy gần như đồng thời.

REQUEST A

REQUEST B

SELECT: not exists

SELECT: not exists

INSERT

INSERT

Nếu không có cơ chế kiểm soát đồng thời, cả hai đều có thể tin rằng key chưa tồn tại.

Unique constraint sẽ giúp ngăn hai bản ghi trùng cùng phạm vi khóa được ghi thành công.

Nhưng ứng dụng vẫn cần xử lý tình huống một request thắng, request còn lại gặp xung đột.

Đây là lý do không nên chỉ dựa vào việc kiểm tra tồn tại ở tầng ứng dụng.

11. Mẫu stored procedure tiếp nhận yêu cầu an toàn hơn

Chúng ta có thể tạo một thủ tục dùng transaction và khóa dữ liệu để tiếp nhận yêu cầu, đồng thời dựa vào unique constraint như lớp bảo vệ cuối cùng.

Ví dụ dưới đây chỉ xử lý bước đăng ký payment operation trong database. Nó chưa gọi cổng thanh toán và không phải một bộ thanh toán production hoàn chỉnh.

CREATE OR ALTER PROCEDURE

dbo.RegisterPaymentOperation

@TenantId BIGINT,

@OrderId BIGINT,

@Key NVARCHAR(120),

@RequestHash CHAR(64) AS BEGIN

SET NOCOUNT ON;

SET XACT_ABORT ON;

BEGIN TRY

BEGIN TRANSACTION;

DECLARE @OperationId UNIQUEIDENTIFIER;

DECLARE @ExistingHash CHAR(64);

DECLARE @Status VARCHAR(20);

SELECT

@OperationId = OperationId,

@ExistingHash = RequestHash,

@Status = Status

FROM dbo.PaymentOperations

WITH (UPDLOCK, HOLDLOCK)

WHERE TenantId = @TenantId

AND IdempotencyKey = @Key;

IF @OperationId IS NOT NULL

BEGIN

IF @ExistingHash <> @RequestHash

BEGIN

THROW 51001,

'Idempotency key reused with different request',

1;

END;

COMMIT TRANSACTION;

SELECT

@OperationId AS OperationId,

@Status AS Status,

CAST(0 AS BIT) AS IsNew;

RETURN;

END;

SET @OperationId = NEWID();

INSERT INTO dbo.PaymentOperations

(

OperationId,

TenantId,

OrderId,

IdempotencyKey,

RequestHash,

Status

)

VALUES

(

@OperationId,

@TenantId,

@OrderId,

@Key,

@RequestHash,

'PENDING'

);

COMMIT TRANSACTION;

SELECT

@OperationId AS OperationId,

'PENDING' AS Status,

CAST(1 AS BIT) AS IsNew;

END TRY

BEGIN CATCH

IF @@TRANCOUNT > 0

ROLLBACK TRANSACTION;

THROW;

END CATCH END;

Trong ví dụ này, UPDLOCK và HOLDLOCK hỗ trợ kiểm soát cạnh tranh truy cập khi kiểm tra một key, với giả định có chỉ mục phù hợp và giao dịch sử dụng đúng phạm vi.

Unique constraint vẫn cần được giữ lại để bảo vệ tính duy nhất ở database.

Trong một hệ thống thực tế, ứng dụng còn phải xử lý deadlock, timeout, lỗi unique constraint, cơ chế retry và các trường hợp giao dịch chưa rõ kết quả.

Đặc biệt, không sử dụng stored procedure này như một lời bảo đảm chống tạo giao dịch trùng tại nhà cung cấp thanh toán.

Nó mới giải quyết một phần của bài toán.

12. Đừng gọi cổng thanh toán ngay sau INSERT rồi nghĩ rằng đã an toàn

Giả sử backend thực hiện:

1. INSERT PaymentOperations.
2. COMMIT.
3. Call Payment Provider.
4. Save provider result.

Nếu tiến trình chết sau bước 2, trước bước 3, payment operation đã tồn tại nhưng chưa được gửi đi.

Nếu tiến trình chết sau khi provider xử lý ở bước 3, trước bước 4, backend không biết kết quả chắc chắn.

Những khoảng trống này là lý do hệ thống thanh toán cần được thiết kế như một quy trình có trạng thái và khả năng phục hồi.

Một hướng tiếp cận là Transactional Outbox.

Trong cùng transaction tạo payment operation, hệ thống ghi thêm một công việc cần xử lý vào bảng Outbox.

Sau khi commit, worker đọc Outbox để gọi nhà cung cấp thanh toán.

Đây là một mẫu kiến trúc, không phải cách duy nhất. Điều cần thiết là có cơ chế bảo đảm thao tác chưa xử lý không bị bỏ quên và thao tác bị retry không tạo tác động lặp ngoài ý muốn.

13. Ví dụ Transactional Outbox cho payment operation

Tạo bảng Outbox đơn giản:

CREATE TABLE dbo.PaymentOutbox (

OutboxId UNIQUEIDENTIFIER

NOT NULL PRIMARY KEY,

OperationId UNIQUEIDENTIFIER

NOT NULL,

EventType NVARCHAR(80) NOT NULL,

Status VARCHAR(20) NOT NULL

DEFAULT 'PENDING',

CreatedAt DATETIME2 NOT NULL

DEFAULT SYSUTCDATETIME(),

CONSTRAINT UQ_PaymentOutbox_Operation

UNIQUE (OperationId, EventType),

CONSTRAINT FK_PaymentOutbox_Operation

FOREIGN KEY (OperationId)

REFERENCES dbo.PaymentOperations(OperationId) );

Khi đăng ký một payment operation mới, ứng dụng cần ghi thêm Outbox trong cùng transaction trước khi commit.

Ví dụ phần SQL bổ sung vào nhánh tạo mới của thủ tục ở trên, ngay sau câu lệnh INSERT PaymentOperations:

INSERT INTO dbo.PaymentOutbox (

OutboxId,

OperationId,

EventType,

Status ) VALUES (

NEWID(),

@OperationId,

'CREATE_PROVIDER_PAYMENT',

'PENDING' );

Như vậy, nếu transaction rollback, cả payment operation và Outbox đều không được ghi thành công.

Nếu transaction commit, công việc cần xử lý được lưu lại để worker tiếp tục.

Nhưng Outbox cũng không tự bảo đảm worker chỉ chạy một lần.

Worker có thể xử lý xong tác vụ bên ngoài rồi gặp lỗi trước khi cập nhật Outbox.

Do đó, worker phải có cơ chế nhận việc an toàn, retry, lease hoặc timeout xử lý phù hợp và quan trọng nhất là giữ nguyên mã định danh ý định khi gọi provider.

14. Phải chống trùng ở cả phía nhà cung cấp thanh toán

Giả sử worker gửi yêu cầu tạo payment đến nhà cung cấp.

Phía provider xử lý thành công nhưng phản hồi bị mất.

Worker retry.

Nếu mỗi lần gọi provider lại dùng một key mới, có thể phát sinh thêm thao tác thanh toán.

Vì vậy, với nhà cung cấp hỗ trợ idempotency, chúng ta nên sử dụng một key ổn định được ánh xạ từ payment operation nội bộ.

Ví dụ:

Internal Operation: OP-10025

Provider Idempotency Key: PAYMENT-OP-10025

First attempt: Key = PAYMENT-OP-10025

Timeout.

Retry: Key = PAYMENT-OP-10025

Trong ví dụ này, mã chỉ mang tính minh họa.

Cần kiểm tra hợp đồng và thời gian lưu key của từng nhà cung cấp.

Stripe mô tả rằng kết quả của request với một Idempotency-Key được lưu và phát lại theo quy tắc riêng của API. Key có thể được loại bỏ sau một khoảng thời gian lưu trữ nhất định.

Vì vậy, không nên giả định rằng cùng một key sẽ được nhà cung cấp nhận diện mãi mãi.

Với thao tác đã có kết quả không chắc chắn, ưu tiên kiểm tra trạng thái giao dịch theo mã provider và quy trình đối soát trước khi tạo một thao tác mới.

15. Webhook bị gửi hai lần có phải lỗi của nhà cung cấp không?

Không nhất thiết.

Trong hệ thống phân tán, webhook có thể được gửi lại vì nhà cung cấp chưa nhận được phản hồi thành công, vì kết nối gián đoạn hoặc do cơ chế retry đã được thiết kế.

Do đó, webhook handler cần chịu được việc nhận cùng sự kiện nhiều lần.

Ví dụ:

EVENT 001: PaymentSucceeded  Webhook delivery 1
        | v Backend processes event.  Webhook delivery 2
        | v Backend recognizes duplicate. No duplicate business effect.

Đừng nhầm giữa hai loại key:

  • API Idempotency-Key: Nhận diện việc retry một thao tác do ứng dụng chủ động gửi đi.
  • Webhook Event ID: Nhận diện một sự kiện đã được nhà cung cấp phát ra.

Các hệ thống thường cần cả hai cơ chế.

16. Thiết kế Inbox để xử lý webhook

Một phương án là tạo bảng ghi nhận các sự kiện webhook đã nhận.

CREATE TABLE dbo.WebhookInbox (

InboxId BIGINT IDENTITY(1,1)

NOT NULL PRIMARY KEY,

Provider NVARCHAR(40) NOT NULL,

ProviderAccount NVARCHAR(120) NOT NULL,

EventId NVARCHAR(200) NOT NULL,

EventType NVARCHAR(100) NOT NULL,

ReceivedAt DATETIME2 NOT NULL

DEFAULT SYSUTCDATETIME(),

CONSTRAINT UQ_WebhookInbox_Event

UNIQUE (

Provider,

ProviderAccount,

EventId

) );

Unique constraint giúp không ghi trùng cùng Event ID trong phạm vi nhà cung cấp và tài khoản đã xác định.

Tuy nhiên, lưu Event ID chưa đủ để bảo đảm tính đúng đắn của nghiệp vụ.

Handler còn phải:

  • Xác minh chữ ký hoặc cơ chế xác thực webhook theo tài liệu provider.
  • Kiểm tra đối tượng và tài khoản nhận thanh toán.
  • Đối chiếu số tiền, loại tiền và mã giao dịch khi phù hợp.
  • Kiểm tra trạng thái hiện tại trước khi chuyển trạng thái.
  • Ghi nhận việc nhận sự kiện và thay đổi nghiệp vụ theo giao dịch dữ liệu an toàn.
  • Xử lý các sự kiện đến không đúng thứ tự hoặc nhiều sự kiện khác nhau mô tả cùng một thay đổi nghiệp vụ.

Ví dụ, nếu ghi Event ID thành công nhưng tiến trình chết trước khi cập nhật đơn hàng, lần retry có thể bị xem là trùng và không được xử lý nữa.

Do đó, với xử lý đồng bộ, việc ghi nhận Inbox và thay đổi dữ liệu liên quan nên nằm trong cùng transaction khi có thể.

Với xử lý bất đồng bộ, cần lưu trạng thái nhận và xử lý riêng, có khả năng khôi phục những sự kiện bị bỏ dở.

17. Exactly Once, At Least Once và At Most Once

Khi nghiên cứu Idempotency, bạn sẽ gặp ba thuật ngữ này.

At Most Once

Một thao tác được thực hiện tối đa một lần, nhưng có thể không được thực hiện nếu xảy ra lỗi.

At Least Once

Hệ thống có thể gửi hoặc xử lý lại để tăng khả năng công việc cuối cùng được thực hiện, nhưng việc lặp lại có thể xảy ra.

Exactly Once

Trong một phạm vi được định nghĩa rõ, hiệu ứng xử lý tương đương với việc thực hiện đúng một lần.

Ở hệ thống nhiều thành phần, không nên hiểu Exactly Once là không bao giờ có request trùng, message trùng hoặc worker chạy lại.

Thực tế, nhiều hệ thống chấp nhận cơ chế gửi lại ít nhất một lần, rồi thiết kế các tác động nghiệp vụ idempotent để không bị nhân đôi.

Đây là lý do cần đặc biệt thận trọng khi AI giải thích rằng sử dụng queue hoặc transaction tự động mang lại Exactly Once cho toàn bộ chuỗi thanh toán.

Phải xác định rõ bảo đảm đó áp dụng ở lớp nào, điều kiện gì và có bao gồm thao tác bên ngoài database hay không.

18. Idempotency có thay thế unique constraint và transaction không?

Không.

Chúng bổ sung cho nhau.

Idempotency-Key giúp nhận diện việc retry cùng một thao tác.

Unique constraint giúp thực thi ràng buộc duy nhất tại database.

Transaction giúp một nhóm thay đổi dữ liệu được commit hoặc rollback theo các bảo đảm của hệ quản trị.

Authorization bảo đảm người dùng có quyền thực hiện thao tác.

Business Rules xác định thao tác có hợp lệ hay không.

Ví dụ, hai request với hai key khác nhau nhưng cùng cố gắng thanh toán một nghĩa vụ đã hoàn tất vẫn cần được kiểm soát bởi quy tắc nghiệp vụ.

Chỉ dùng Idempotency-Key không ngăn được tình huống ấy, bởi hệ thống có thể xem đó là hai ý định khác nhau.

Với giao dịch tài chính, cần có một định danh nghĩa vụ thanh toán và cơ chế chuyển trạng thái nhất quán.

19. Thử nghiệm Idempotency bằng những tình huống thực tế

Tôi đề xuất không chỉ viết một Unit Test rồi kết luận chức năng hoạt động đúng.

Hãy kiểm tra các tình huống sau:

  1. Cùng key, cùng payload, gửi tuần tự hai lần.
  2. Cùng key, cùng payload, gửi đồng thời từ hai request.
  3. Cùng key nhưng payload khác.
  4. Khác key nhưng cùng đơn hàng đã thanh toán.
  5. Timeout trước khi backend nhận request.
  6. Timeout sau khi database đã commit.
  7. Timeout sau khi provider xử lý thành công.
  8. Worker bị restart trong lúc xử lý Outbox.
  9. Webhook được gửi lại cùng Event ID.
  10. Hai sự kiện webhook khác nhau dẫn đến cùng trạng thái nghiệp vụ.
  11. Webhook đến sai thứ tự.
  12. Database gặp deadlock hoặc lỗi kết nối.
  13. Key đã hết thời gian lưu trữ.
  14. Hai tenant sử dụng cùng một chuỗi key.
  15. Người dùng không có quyền truy cập đơn hàng.

Với những trường hợp liên quan đến xử lý đồng thời và provider, cần integration tests hoặc mô phỏng lỗi có kiểm soát.

Một Unit Test mock toàn bộ database không thể chứng minh unique constraint và transaction hoạt động đúng dưới tải thực tế.

20. Nên đo những chỉ số nào?

Idempotency không phải tính năng để người dùng nhìn thấy, nhưng rất đáng theo dõi.

Có thể đo:

  • Số request có Idempotency-Key.
  • Số request được nhận diện là retry.
  • Số request bị từ chối do reuse key với payload khác.
  • Số operation đang PENDING hoặc UNKNOWN quá thời hạn dự kiến.
  • Số Outbox message cần retry.
  • Số webhook nhận trùng.
  • Số sai lệch đối soát với provider.
  • Số thao tác nghiệp vụ có nguy cơ bị xử lý trùng.

Không nên ghi toàn bộ payload thanh toán hoặc dữ liệu cá nhân vào log chỉ để phục vụ debug.

Hãy sử dụng mã operation, mã giao dịch và những trường chẩn đoán phù hợp, với cơ chế kiểm soát truy cập log.

Đặc biệt, cần cảnh báo những operation đang ở trạng thái UNKNOWN quá lâu. Đó có thể là dấu hiệu cần đối soát thay vì retry vô hạn.

21. Task Specification cho AI Coding Agent

Nếu giao AI xây dựng Idempotency, tôi đề xuất bắt đầu bằng một file Markdown.

# TASK-PAY-IDEMPOTENCY-001

## Objective
Prevent duplicate payment operations when the same logical request is retried.

## Scope
- Create payment operation API
- Idempotency key validation
- Request fingerprint
- SQL Server uniqueness protection
- Payment operation status
- Retry behavior
- Integration tests

## Business
Rules
- One logical payment request must not

create duplicate charges.
- Reusing a key with different input

must be rejected.
- Payment completion must rely on

verified provider confirmation.
- Unknown provider outcomes must be

reconciled before creating new payment.

## Dependencies
- Order Service
- Payment Provider
- SQL Server
- Webhook Handler

## Constraints
- No production execution.
- No destructive migration.
- No unapproved payment rule changes.
- No secrets in code or logs.
- Preserve authorized behavior.

## Acceptance
Criteria AC-001: Same key and same request do not create a second operation.

AC-002: Concurrent duplicate requests are handled safely.

AC-003: Same key with different payload is rejected.

AC-004: A provider timeout does not trigger an unsafe new charge.

AC-005: Webhook retries do not repeat business effects.

AC-006: Unauthorized requests are rejected.

AC-007: Pending and unknown operations can be investigated and reconciled.

## Verification
- Unit tests
- SQL Server integration tests
- Concurrent request tests
- Provider failure simulations
- Webhook replay tests

## Deliverables
- Implementation plan
- Schema and migration scripts
- Application code
- Tests
- Recovery and reconciliation plan
- Review report

Một task như vậy giúp AI biết rằng "chống request trùng" không chỉ là tạo một bảng chứa key.

22. Prompt yêu cầu AI phân tích trước khi viết code

ROLE: Senior Payment Systems Architect

TASK: TASK-PAY-IDEMPOTENCY-001

PHASE 1
- RESEARCH

Review:
- Approved payment business rules
- Existing payment architecture
- Current SQL Server schema
- Payment provider documentation
- Webhook processing
- Retry and timeout handling
- Current transaction boundaries

PHASE 2
- DESIGN

Propose:
1. Idempotency key scope
2. Request fingerprint rules
3. Database uniqueness constraints
4. Operation status model
5. Concurrent request behavior
6. Provider retry strategy
7. Outbox / Inbox requirements
8. Unknown outcome reconciliation
9. Key retention policy
10. Failure and recovery tests

RULES:
- Do not modify code yet.
- Do not access production.
- Do not invent provider guarantees.
- Do not assume timeout means failure.
- Do not confuse unique records

with exactly-once external effects.
- Identify all unverified assumptions.

OUTPUT:
- Architecture proposal
- Sequence diagrams
- Database changes
- Risks
- Open decisions
- Test plan

Wait for approval before implementation.

Điểm cần kiểm tra trong kết quả AI là những bảo đảm mà nhà cung cấp thanh toán thực sự hỗ trợ.

Không phải cổng thanh toán nào cũng dùng cùng một cơ chế Idempotency-Key, thời hạn lưu khóa hoặc API đối soát.

Nếu tài liệu provider chưa có, AI phải báo thiếu thông tin, không tự giả định hành vi giống Stripe.

23. Checklist 15 mục trước khi Go-live một API idempotent

  1. Đã xác định chính xác thao tác nghiệp vụ cần chống trùng chưa?
  2. Đã xác định phạm vi duy nhất của Idempotency-Key chưa?
  3. Đã có cách tạo key đủ khó trùng chưa?
  4. Client có giữ nguyên key khi retry cùng ý định không?
  5. Đã kiểm tra reuse key với payload khác chưa?
  6. Đã có unique constraint tại database chưa?
  7. Đã thử hai request đồng thời chưa?
  8. Đã thiết kế trạng thái PENDING, SUCCESS và UNKNOWN phù hợp chưa?
  9. Đã xử lý timeout không rõ kết quả chưa?
  10. Đã kiểm tra chính sách idempotency của provider chưa?
  11. Đã thiết kế cơ chế retry an toàn cho Outbox chưa?
  12. Đã xử lý webhook trùng và sự kiện sai thứ tự chưa?
  13. Đã có phương án đối soát khi trạng thái không nhất quán chưa?
  14. Đã bảo đảm authorization và bảo vệ dữ liệu chưa?
  15. Đã có monitoring, cảnh báo và kiểm thử lỗi thực tế chưa?

24. Những sai lầm thường gặp khi dùng AI viết Idempotency

Chỉ khóa nút thanh toán ở frontend

Giao diện không thể bảo vệ hệ thống khỏi retry từ những thành phần khác.

Tạo key mới mỗi khi request timeout

Điều này làm mất khả năng nhận diện retry cùng một ý định.

Chỉ kiểm tra SELECT rồi INSERT

Có thể gặp race condition nếu không có cơ chế cạnh tranh và ràng buộc dữ liệu phù hợp.

Chỉ lưu key trong bộ nhớ của một instance

Trong hệ thống có nhiều server hoặc sau khi ứng dụng restart, trạng thái có thể không còn nhất quán.

Cho rằng unique constraint ngăn được mọi giao dịch trùng

Ràng buộc tại database không tự kiểm soát side effect tại cổng thanh toán hoặc các hệ thống bên ngoài.

Coi mọi timeout là thất bại

Thao tác có thể đã được xử lý thành công, chỉ có phản hồi bị mất.

Retry vô hạn

Không có giới hạn retry, backoff và cơ chế xử lý trường hợp không rõ kết quả có thể làm hệ thống quá tải.

Không kiểm tra payload khi reuse key

Cùng key nhưng thay đổi số tiền hoặc đơn hàng cần được xử lý như một xung đột có ý nghĩa.

Xử lý webhook chỉ bằng việc lưu Event ID

Nếu lưu Event ID và cập nhật nghiệp vụ không nhất quán, vẫn có thể bỏ sót sự kiện hoặc xử lý chưa hoàn chỉnh.

Không phân biệt giao dịch mới với retry

Hai ý định nghiệp vụ hợp lệ có thể cần hai key riêng, trong khi retry cùng một ý định phải dùng lại key.

Không quản lý thời hạn lưu key

Khi key đã bị xóa, một request rất cũ có thể bị xem là yêu cầu mới nếu không còn ràng buộc nghiệp vụ bổ sung.

Giao AI triển khai mà không có tài liệu provider

AI có thể viết theo giả định của một nhà cung cấp khác và tạo ra thiết kế không tương thích.

25. Kết luận: Không phải cứ nhận hai request là được phép làm hai lần

Có một điều thú vị trong phát triển hệ thống phân tán.

Chúng ta thường dành nhiều thời gian để bảo đảm một request được gửi đi. Nhưng khi hệ thống lớn hơn, một câu hỏi khác xuất hiện: Nếu request ấy được gửi thêm lần nữa thì sao?

Với website chỉ hiển thị nội dung, việc tải lại trang thường không gây hậu quả lớn.

Nhưng với thanh toán, tạo đơn hàng, giữ chỗ, trừ điểm thưởng hoặc gửi thông báo có chi phí, thao tác lặp lại có thể tạo ra vấn đề thật.

Idempotency giúp chúng ta thiết kế hệ thống biết phân biệt một lần thử lại với một yêu cầu mới.

Tuy nhiên, một Idempotency-Key không thể tự giải quyết toàn bộ bài toán.

Chúng ta còn cần transaction, unique constraint, kiểm soát đồng thời, trạng thái nghiệp vụ, cơ chế đối soát và khả năng xử lý khi kết quả không chắc chắn.

Với chú Nha 27 tuổi, đây là một trong những kiến thức nên hiểu trước khi giao AI Coding Agent xây dựng chức năng thanh toán.

AI có thể viết API rất nhanh. Nhưng để biết API ấy có an toàn khi mạng chập chờn, khi hai request đến cùng lúc hoặc khi provider gửi webhook nhiều lần, chúng ta phải thiết kế và kiểm chứng những tình huống ấy một cách có chủ đích.

Lần tới, nếu khách hàng nhấn thanh toán hai lần, hệ thống không nên lấy đó làm lời đề nghị thu tiền hai lần.

Khách chỉ đang cố hoàn thành một việc.

Phần mềm cần hiểu điều đó.

Và nếu AI thông báo: "Em đã chống giao dịch trùng bằng cách disable nút thanh toán rồi", chắc chú Nha sẽ hỏi thêm:

"Thế nếu khách mất mạng sau khi ngân hàng đã xử lý xong thì sao?"

Câu hỏi ấy mới là lúc chúng ta bắt đầu thiết kế Idempotency thật sự.

Nguồn tham khảo

Cảm ơn bạn đã đọc hết bài viết!

Nha thân tặng bộ source code blog này cho những ai quan tâm.
☕

Mời tác giả tách cà phê / Tiếp sức cho Blog

Nếu nội dung này hữu ích với bạn, hãy ủng hộ một khoản nhỏ để tiếp thêm động lực cho tác giả duy trì và chia sẻ nhiều kiến thức chất lượng hơn!

Giới thiệu

Tìm kiếm Google

Tài trợ

Liên kết

Mạng thư viện
Quà tặng con gái và con trai
Dotgrid Planner 2023
Mua hàng tại amazone
Bàn phím cơ