IOSOR

IOSOR Kiến thức

Idempotency API gửi: trùng lặp, retry và tiền

Hướng dẫn cho nhà phát triển API gửi trả trước — khóa idempotency, retry an toàn, chống trùng và tương quan thân thiện sổ cái, để lỗi kỹ thuật không thành sự cố tài chính.

Timeout xảy ra. Bộ cân bằng tải retry. Client di động double-tap. Không có idempotency, sản phẩm "gửi một lần" thành trừ tiền trả trước hai lần và UX OTP trùng. Hướng dẫn này dành cho engineering và product kỹ thuật tích hợp API nhắn tin trả trước white-label — mọi trùng đều hiện trong ví. IOSOR kỳ vọng tích hợp money-aware: lời gọi đã xác thực, khoản trừ đối soát được, và lỗi client không đổ payload thương hiệu ngoài. Gần USD 1.000+ dùng nền tảng mỗi tháng, kỷ luật chống trùng không còn tùy chọn. Coi mỗi lần gửi trước hết là sự kiện sổ cái, rồi mới là lời gọi mạng — để finance và on-call chung một câu chuyện.

Vì sao trùng lặp trở thành vấn đề tiền

Chế độ lỗi Người dùng thấy Ví thấy
Timeout client + retry mù Hai OTP / hai cảnh báo Hai khoản trừ
Handler webhook không idempotent Side effect kép Nhầm lẫn khi success
User resend chồng lên auto-retry Người dùng khó chịu Đơn vị cộng dồn
Thiếu tương quan Ticket "thất bại" Dòng sổ cái không khớp

Demo tha thứ. Tài chính production thì không. Ở cường độ trả trước, một cuối tuần retry mù thành dự án đối soát, không phải chú thích log. Thiết kế happy path và đường timeout với cùng quy tắc trừ tiền.

Khóa idempotency sống sót qua retry

Đường gửi nghiêm túc chấp nhận khóa do client tạo, duy nhất theo ý định nghiệp vụ chứ không phải lần thử TCP. Khi replay trong cửa sổ TTL, nó phải trả cùng kết quả accepted. Điều này ngăn việc tạo khoản trừ thứ hai cho cùng ý định. Khóa phải được ghi cạnh message ID và tham chiếu trả trước. Nó phải hoạt động qua timeout, retry gateway và redrive hỗ trợ.

Ngân sách retry vs gửi lại của người dùng

Retry tự động cần ngân sách: số lần tối đa, backoff, và lớp lỗi nào retry được. Gửi lại do người dùng khởi xướng là hành động sản phẩm khác, có giới hạn và chi phí trả trước riêng. Trộn chúng biến mạng chập chờn thành sự kiện ví cuối tuần. Gắn cả hai với dừng khi số dư thấp và lý do từ chối rõ ràng.

Checklist người mua / engineering

  1. Tài liệu hóa ngữ nghĩa khóa idempotency và TTL.
  2. Kiểm tra replay chứng minh một khoản trừ cho một ý định.
  3. Tách biệt ngân sách auto-retry khỏi logic gửi lại của người dùng.
  4. Correlation ID xuyên suốt request, trạng thái và sổ cái.
  5. Staging thực tế, không dùng mock xanh.
  6. Vệ sinh khóa và quyền tối thiểu cho credentials.
  7. Xử lý 429 và 503 mà không mất khóa ý định gốc.
  8. Cảnh báo tự động cho tỷ lệ từ chối khóa trùng cao.

Cờ đỏ

  • "Retry đến 200" mà không dùng khóa idempotency.
  • Handler webhook không idempotent gây side effect kép.
  • Khóa bí mật hoặc token xuất hiện trong log/ticket.
  • Lỗi đổ payload thương hiệu upstream cho người dùng cuối.
  • Không có giám sát sai lệch giữa sổ cái và mạng.

Bắt đầu với IOSOR

Trong bảng gửi, bắn một OTP hoặc cảnh báo với khóa idempotency do client tạo. Ép timeout client rồi phát lại cùng yêu cầu trong TTL khóa. Mở ledger prepaid: ý định đó phải hiện một debit và một tin người dùng thấy. Hai hàng nghĩa là khóa không sống sót retry — sửa TTL và handler trước khi hành lang còn Live.

Điểm chính IOSOR

Làm: coi mỗi lần gửi là sự kiện ledger trước. Khóa duy nhất theo ý định nghiệp vụ, không theo lần TCP. Auto-retry có ngân sách; nút gửi lại của người dùng là hành động sản phẩm khác, có chi phí prepaid riêng.

Đừng: đập tới 200 không khóa, hay để webhook không idempotent đúc hiệu ứng thứ hai. Hai OTP cho một chạm là lỗi tiền, không phải chuyện mạng.

Hướng dẫn này có hữu ích không?

Hướng dẫn liên quan