Idempotency trong ASP.NET Core: khách bấm hai lần, bị trừ tiền hai lần
Khách gửi khiếu nại kèm ảnh sao kê: một đơn hàng 1.250.000 đồng, hai giao dịch trừ tiền cách nhau ba giây. Lần theo log thì thấy app gửi hai request thanh toán giống hệt nhau. Mạng 4G chập chờn, bấm "Thanh toán" mãi không thấy gì, khách bấm thêm lần nữa. Server nhận cả hai, xử lý cả hai, và cả hai đều thành công.
Không có dòng code nào sai theo nghĩa thông thường. Cái thiếu là code chưa bao giờ được hỏi câu: "nếu request này đến hai lần thì sao?". Bài này đi dọc một luồng thanh toán, từ lúc khách bấm nút tới lúc ghi xuống database, chỉ ra từng chỗ có thể chạy hai lần và cách chặn ở mỗi chỗ. Ví dụ dùng EF Core với SQL Server.
Chặng 1: nút bấm trên app
Phản xạ đầu tiên là disable nút sau khi bấm. Nên làm, nhưng không đủ. Thư viện HTTP phía client có thể tự retry khi timeout. Khách có thể tắt app mở lại rồi bấm tiếp. Request đầu có thể đã tới server và đang xử lý, chỉ là response chưa kịp về.
Nên bài học đầu tiên: phía client chỉ làm giảm khả năng gửi trùng. Người chặn thật sự phải là server.
Chặng 2: request tới API với idempotency key
Idempotent nghĩa là gọi một lần hay gọi nhiều lần cũng cho cùng một kết quả. GET vốn idempotent, POST /pay thì không. Cách phổ biến để biến nó thành idempotent: mỗi lần khách bắt đầu một lượt thanh toán, client sinh một GUID và gửi trong header Idempotency-Key. Bấm lại, retry, gửi lại bao nhiêu lần cũng dùng đúng key đó. Server nhớ key nào đã xử lý, gặp lại thì trả kết quả cũ thay vì làm lại.
public class IdempotencyRecord
{
public Guid Key { get; set; } // khoá chính: hai request cùng key không thể cùng ghi
public bool Completed { get; set; }
public int StatusCode { get; set; }
public string? ResponseBody { get; set; }
public DateTime CreatedAt { get; set; }
}
app.MapPost("/api/orders/{id:int}/pay", async (
int id,
[FromHeader(Name = "Idempotency-Key")] Guid? key,
AppDbContext db, PaymentService payments, CancellationToken ct) =>
{
if (key is null)
return Results.Problem("Thiếu header Idempotency-Key.", statusCode: StatusCodes.Status400BadRequest);
var existing = await db.IdempotencyRecords.FindAsync([key.Value], ct);
if (existing is not null)
{
// Đã xử lý xong: trả lại đúng response cũ. Đang xử lý dở: báo client chờ.
return existing.Completed
? Results.Text(existing.ResponseBody, "application/json", statusCode: existing.StatusCode)
: Results.Problem("Yêu cầu đang được xử lý.", statusCode: StatusCodes.Status409Conflict);
}
var record = new IdempotencyRecord { Key = key.Value, CreatedAt = DateTime.UtcNow };
db.IdempotencyRecords.Add(record);
try
{
await db.SaveChangesAsync(ct); // "giành" key trước khi làm việc thật
}
catch (DbUpdateException ex) when (ex.IsUniqueViolation())
{
// Request song song cùng key vừa giành trước mình một chút
return Results.Problem("Yêu cầu đang được xử lý.", statusCode: StatusCodes.Status409Conflict);
}
var result = await payments.PayAsync(id, key.Value, ct);
record.Completed = true;
record.StatusCode = StatusCodes.Status200OK;
record.ResponseBody = JsonSerializer.Serialize(result);
await db.SaveChangesAsync(ct);
return Results.Ok(result);
});
Chỗ quan trọng nhất là bước "giành" key: ghi bản ghi trước rồi mới làm việc thật. Hai request cùng key đến cùng lúc thì chỉ một bên ghi được, bên kia đụng khoá chính. Kiểm tra bằng SELECT rồi mới INSERT thì không chặn được trường hợp này, đúng cái khoảng hở giữa đọc và ghi mà mình đã nói ở bài schema và transaction bên series SQL.
IsUniqueViolation là một extension nhỏ tự viết, kiểm tra lỗi gốc có phải vi phạm unique trên SQL Server không:
public static bool IsUniqueViolation(this DbUpdateException ex) =>
ex.InnerException is SqlException { Number: 2627 or 2601 };
Hai chi tiết nữa khi làm thật. Bảng key cần dọn định kỳ, giữ vài ngày là đủ. Và nên lưu kèm hash của request body: cùng key mà body khác (client dùng lại key cho một thanh toán khác) thì trả lỗi thay vì trả nhầm kết quả cũ.
Chặng 3: hai request khác key cùng sửa một đơn
Idempotency key chặn được việc gửi lại cùng một ý định. Nó không chặn được hai ý định khác nhau va vào cùng một đơn: khách bấm thanh toán trên điện thoại, đồng thời bấm huỷ đơn trên web. Hai request đều đọc thấy đơn đang Pending, một bên ghi Paid, bên kia ghi Cancelled. Ai ghi sau thì thắng, và đơn có thể bị huỷ dù tiền đã trừ.
Cách gọn nhất với chuyển trạng thái là để database kiểm tra điều kiện ngay trong câu UPDATE (EF Core 7 trở lên):
var affected = await db.Orders
.Where(o => o.Id == id && o.Status == OrderStatus.Pending) // chỉ chuyển khi còn đang chờ
.ExecuteUpdateAsync(s => s.SetProperty(o => o.Status, OrderStatus.Paid), ct);
if (affected == 0)
return Results.Problem("Đơn đã được thanh toán hoặc đã bị huỷ.", statusCode: StatusCodes.Status409Conflict);
Request nào tới sau sẽ thấy affected == 0 và biết mình thua. Đây chính là kiểu UPDATE ... WHERE stock >= 1 bên series SQL, chỉ là viết bằng EF Core.
Khi cần đọc entity lên, sửa nhiều field rồi mới lưu, mình dùng optimistic concurrency với cột rowversion của SQL Server:
public class Order
{
public int Id { get; set; }
public OrderStatus Status { get; set; }
// SQL Server tự đổi giá trị này mỗi lần dòng bị update
[Timestamp] public byte[] RowVersion { get; set; } = [];
}
EF Core đưa RowVersion vào điều kiện WHERE của câu UPDATE. Nếu trong lúc mình đang sửa đã có ai khác update dòng đó, câu UPDATE không trúng dòng nào và EF ném DbUpdateConcurrencyException. Mình bắt nó và trả 409 cho client tải lại dữ liệu mới.
Chặng 4: gọi sang cổng thanh toán
Ở bài HttpClient mình đã nói: đừng retry POST bừa. Giờ có idempotency key rồi thì truyền luôn key đó sang cổng thanh toán. Nhiều cổng thanh toán hỗ trợ đúng cơ chế này (Stripe là ví dụ quen thuộc, cũng qua header Idempotency-Key), nên timeout giữa chừng thì retry an toàn: bên kia nhận ra key cũ và không trừ tiền lần nữa. Cổng bạn đang dùng có hỗ trợ hay không thì phải đọc tài liệu của họ, đừng đoán.
Chặng 5: webhook gửi lại
Cổng thanh toán báo kết quả qua webhook, và gần như cổng nào cũng gửi lại webhook nếu không nhận được 200 đủ nhanh. Nghĩa là handler webhook chắc chắn sẽ có lúc nhận cùng một sự kiện hai lần. Nếu mỗi lần nhận lại cộng điểm thưởng, gửi email, xuất kho thì khách được gấp đôi.
Cách chặn y như chặng 2, chỉ là key do bên gửi cung cấp:
db.ProcessedWebhookEvents.Add(new ProcessedWebhookEvent
{
EventId = payload.EventId, // id sự kiện do cổng thanh toán gửi, có unique constraint
ReceivedAt = DateTime.UtcNow
});
try
{
await db.SaveChangesAsync(ct);
}
catch (DbUpdateException ex) when (ex.IsUniqueViolation())
{
return Results.Ok(); // đã xử lý rồi: trả 200 để bên kia thôi gửi lại
}
await HandlePaymentSucceededAsync(payload, ct);
return Results.Ok();
Và đừng quên xác thực chữ ký webhook trước khi tin bất cứ thứ gì trong body. Không thì ai biết URL webhook cũng tự báo "đơn này đã thanh toán" được.
Message đi qua queue cũng cần y hệt cách này ở phía consumer. Như mình đã nói ở bài outbox, gửi "ít nhất một lần" thì bên nhận phải chịu được trùng.
Thử ngay: chọn endpoint nào làm mất tiền hoặc làm đổi trạng thái quan trọng (thanh toán, tạo đơn, cộng điểm), dùng Postman bắn cùng một request hai lần thật nhanh, hoặc chạy song song bằng một vòng lặp nhỏ. Rồi đếm xem database có mấy dòng mới.
Bài sau là xử lý lỗi trong ASP.NET Core, trong đó có cách trả 409 và 422 cho đúng mấy tình huống ở bài này. Bạn đang chặn request trùng ở đâu, client hay server? Comment cho mình biết với.
P.S. Luồng thanh toán là chỗ mình không dám tự tin vào góc nhìn của một người. Trước khi đổi luồng này, mình cho AI mở một cuộc tranh luận bằng skill predict-architecture-debate trong PrimeKit, bộ skill mình tự làm. Skill dựng năm chuyên gia với năm góc nhìn khác nhau, cùng phản biện thay đổi trước khi code, để bắt sớm vấn đề về kiến trúc, bảo mật, hiệu năng lẫn trải nghiệm người dùng. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:predict-architecture-debate kèm mô tả thay đổi. Một cuộc tranh luận không thay được test chạy song song thật, nhưng hay chỉ ra đúng mấy chặng mình quên nghĩ tới.
All Rights Reserved