Thiết kế chiến lược Idempotency chống trùng lặp yêu cầu API

1. Vai trò và Bối cảnh Chuyên gia: Bạn là một kiến trúc sư phần mềm cấp cao chuyên về các hệ thống phân tán, thanh toán và giao dịch tài chính quy mô lớn, nơi tính toàn vẹn dữ liệu là yêu cầu tối thượng. Nhiệm vụ của bạn là thiết kế chiến lược chống trùng lặp yêu cầu (Idempotency) cấp doanh nghiệp, đảm bảo mỗi thao tác thay đổi trạng thái hệ thống chỉ được thực thi duy nhất một lần, bất chấp việc người dùng nhấn nút nhiều lần hoặc mạng chập chờn gây ra các yêu cầu gửi lại (retry). 2. Thông tin Đầu vào: Hãy xây dựng giải pháp dựa trên các thông số kỹ thuật được cung cấp dưới đây: - Ngôn ngữ lập trình triển khai: {{ngon_ngu_lap_trinh}} - Framework backend sử dụng: {{framework_su_dung}} - Hệ thống Redis lưu trữ khóa: {{he_quan_tri_redis}} - Thời gian hết hạn mặc định của khóa (TTL): {{thoi_gian_het_han_khoa}} - Endpoint giao dịch đại diện cần bảo vệ: {{endpoint_giao_dich}} 3. Nhiệm vụ Chính: Thiết kế kiến trúc giải pháp và viết mã nguồn chi tiết cho một Middleware xử lý Idempotency Key tiêu chuẩn. Middleware này có khả năng chặn đứng các truy vấn trùng lặp, giải quyết tranh chấp dữ liệu khi có nhiều yêu cầu gửi song song (race condition), lưu trữ bộ đệm kết quả phản hồi trên Redis và trả về kết quả nhất quán cho các yêu cầu lặp lại. 4. Quy trình Thực hiện Chi tiết: - Bước 1: Thiết kế ma trận trạng thái khóa trong Redis (bao gồm các trạng thái: STARTED, PROCESSING, COMPLETED, FAILED) và cơ chế khóa phân tán (distributed lock) sử dụng các lệnh nguyên tử. - Bước 2: Triển khai thuật toán băm dữ liệu yêu cầu (Request Payload Hashing) để so sánh nội dung body/query với Idempotency Key, ngăn chặn hành vi dùng lại Key cũ cho dữ liệu mới. - Bước 3: Viết mã nguồn hoàn chỉnh cho Middleware Idempotency bằng {{ngon_ngu_lap_trinh}} trên {{framework_su_dung}}, kết nối trực tiếp với {{he_quan_tri_redis}}. - Bước 4: Xử lý các trường hợp biên (edge cases) như: sự cố sập ứng dụng trong lúc đang xử lý, lỗi quá thời gian chờ (timeout), và giải phóng khóa an toàn khi có ngoại lệ xảy ra. - Bước 5: Viết mã nguồn minh họa việc tích hợp Middleware vào endpoint {{endpoint_giao_dich}} và cung cấp hướng dẫn kiểm thử chi tiết. 5. Yêu cầu Chất lượng và Ràng buộc: - Mã nguồn phải sẵn sàng cho môi trường thực tế (production-ready), chuẩn hóa, sạch sẽ và kèm ghi chú giải thích rõ ràng bằng tiếng Việt. - Sử dụng các thao tác nguyên tử trên Redis (như SET với tham số NX, PX hoặc script Lua) để triệt tiêu hoàn toàn race condition ở mức độ milisecond. - Nếu người dùng gửi lại đúng Idempotency Key nhưng Request Payload thay đổi, middleware phải từ chối và trả về mã lỗi HTTP 422 (Unprocessable Entity) hoặc 400 (Bad Request). - Nếu một yêu cầu trùng Key tới khi yêu cầu trước vẫn đang ở trạng thái PROCESSING, middleware phải trả về mã lỗi HTTP 409 (Conflict) cùng thông báo giao dịch đang được xử lý. - Đảm bảo thiết lập {{thoi_gian_het_han_khoa}} chính xác cho khóa để tránh việc lưu trữ rác làm tràn bộ nhớ Redis. 6. Định dạng Đầu ra Chi tiết: - Phần A: Sơ đồ luồng xử lý Idempotency và cấu trúc ma trận trạng thái trên Redis. - Phần B: Cấu trúc dữ liệu lưu trong Redis (Key format, Schema JSON của value). - Phần C: Mã nguồn chi tiết của Middleware Idempotency (bao gồm logic băm payload, thao tác Redis lock và xử lý cache). - Phần D: Mã nguồn Controller tích hợp Middleware tại endpoint {{endpoint_giao_dich}}. - Phần E: Kịch bản kiểm thử mẫu (Test Cases) cho 4 trường hợp: yêu cầu hợp lệ lần đầu, yêu cầu trùng lặp thành công, yêu cầu song song (race condition) và yêu cầu sai payload. 7. Tiêu chí Tự kiểm tra Trước khi Trả lời: - Mã nguồn đã sử dụng cơ chế xử lý bất đồng bộ chuẩn của {{ngon_ngu_lap_trinh}} chưa? - Cơ chế giải phóng khóa có nằm trong khối try-finally/catch để đảm bảo không bị dính deadlock khi ứng dụng gặp lỗi đột ngột hay chưa? - Các mã phản hồi HTTP (200, 400, 409, 422, 500) đã được phân định đúng chuẩn RESTful API chưa? - Tất cả các biến đầu vào gồm {{ngon_ngu_lap_trinh}}, {{framework_su_dung}}, {{he_quan_tri_redis}}, {{thoi_gian_het_han_khoa}}, và {{endpoint_giao_dich}} đều đã được đưa vào mã nguồn và phần giải thích một cách hợp lý chưa?