Thêm Idempotency-Key để khách gọi lại POST không tạo đơn trùng
Một bảng Postgres, một ràng buộc unique và quy tắc 409, 422 là phần lõi để mọi lần gọi lại nhận đúng kết quả cũ.
Tóm tắt nhanh
- Client sinh một UUID v4 cho mỗi thao tác và gửi lại đúng key đó khi retry; server lưu mã trạng thái và body của lần chạy đầu rồi phát lại.
- Cùng key nhưng payload khác thì trả 422; key đang được xử lý dở thì trả 409, theo bản draft của IETF.
- Ràng buộc unique đặt trên cặp (user_id, idempotency_key); handler có lời gọi ra hệ thống ngoài thì nên chia thành atomic phase với recovery point.
Thử hình dung hệ thống ERP của khách gọi POST /orders sang API bạn vừa bàn giao. Request bị timeout, ERP gọi lại, và kho nhận hai đơn hàng cho cùng một lần bấm nút. Code của bạn không có lỗi nào. Chỉ là nó chưa biết nhận ra một lần gọi lại.
Lỗi kiểu này thường chỉ lộ ra khi đã chạy với dữ liệu thật, đúng lúc FDE đang ngồi ở chỗ khách.
Tài liệu API của Stripe nói rõ idempotency dùng để làm gì: khi có lỗi kết nối, client có thể lặp lại request mà không sợ tạo thêm một object thứ hai hay chạy một lần cập nhật hai lần.
Hướng dẫn này dựng đúng cơ chế đó cho một endpoint POST bất kỳ, trong khoảng một buổi chiều.
Bạn sẽ có một bảng Postgres lưu key, một handler đã được bọc lại, một job dọn key cũ và ba lệnh curl để chứng minh endpoint chạy đúng. Bạn cần sẵn một endpoint POST đang chạy, quyền tạo bảng trong Postgres và curl. Code handler bên dưới là bản rút gọn, viết theo kiểu Python giả lập. Hãy chuyển sang framework bạn đang dùng.
Key là việc của client, ghi nhớ là việc của server
Brandur Leach, tác giả bài hướng dẫn dựng idempotency key kiểu Stripe trên Postgres, định nghĩa endpoint idempotent là endpoint gọi bao nhiêu lần cũng được mà tác dụng phụ chỉ xảy ra một lần. Muốn được như vậy, server cần một dấu hiệu để biết hai request thực chất là một thao tác.
Dấu hiệu đó do client tạo ra. Blog kỹ thuật của Stripe mô tả cách làm: client sinh một ID duy nhất cho đúng một thao tác, và khi retry thì gửi lại chính ID đó.
Tài liệu của Stripe khuyên dùng UUID v4 hoặc một chuỗi ngẫu nhiên đủ entropy, dài tối đa 255 ký tự, và cảnh báo không nhét dữ liệu nhạy cảm vào key. Bản draft draft-ietf-httpapi-idempotency-key-header của IETF chuẩn hóa tên header là Idempotency-Key, dùng cho các method vốn không idempotent như POST và PATCH.
Theo Stripe, GET và DELETE đã idempotent theo định nghĩa nên gửi key kèm chúng không có tác dụng gì. Vì thế bạn chỉ cần bọc các endpoint POST, và PATCH nếu có.
Bước 1: một bảng, một ràng buộc unique theo user
CREATE TABLE idempotency_keys (
user_id bigint NOT NULL,
idempotency_key varchar(255) NOT NULL,
request_hash text NOT NULL,
status text NOT NULL DEFAULT 'processing',
response_code int,
response_body jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (user_id, idempotency_key)
);
Chi tiết quan trọng nhất nằm ở dòng cuối. Trong thiết kế của Brandur, key không unique trên toàn bảng mà unique theo cặp (user_id, idempotency_key). Hai khách khác nhau vô tình sinh trùng chuỗi sẽ không đè lên dữ liệu của nhau, và một khách cũng không đoán được key để đọc phản hồi của khách khác.
Cột request_hash là băm của body request, dùng cho bước kiểm tra payload ở dưới. Kiểm tra: chạy \d idempotency_keys trong psql và xác nhận có một index unique trên hai cột.
Bước 2: giữ chỗ cho key trước khi làm bất cứ việc gì
Khi request đến, việc đầu tiên là cố chèn key vào bảng. Thao tác chèn này đồng thời là cái khóa của bạn:
INSERT INTO idempotency_keys (user_id, idempotency_key, request_hash)
VALUES ($1, $2, $3)
ON CONFLICT (user_id, idempotency_key) DO NOTHING
RETURNING status;
Nếu câu lệnh trả về một dòng, đây là lần đầu bạn thấy key này và có thể xử lý tiếp. Nếu không trả về dòng nào, key đã tồn tại. Lúc đó bạn đọc dòng cũ lên và quyết định theo ba trường hợp trong bảng sau.
| Tình huống khi key đã tồn tại | Phản hồi |
|---|---|
| Hash payload khác hash đã lưu | 422: cùng key không được dùng cho payload khác |
status = 'processing' |
409: request gốc vẫn đang chạy |
status = 'done' |
Phát lại đúng response_code và response_body đã lưu |
Hai mã trạng thái đầu lấy từ bản draft của IETF. Draft quy định key không được dùng lại cho một request có payload khác, và server nên trả 422 trong trường hợp đó.
Nếu lần gọi lại đến khi request gốc chưa xong, server nên trả 409. Stripe cũng so sánh tham số khi một key bị dùng lại và báo lỗi nếu chúng khác nhau, để chặn những lần dùng nhầm.
Bước 3: lưu lại phản hồi đầu tiên, kể cả khi đó là lỗi 500
# Bản rút gọn, minh họa luồng xử lý
def create_order(req):
key = req.headers.get("Idempotency-Key")
if key is None:
return handle(req) # tùy chính sách: cho qua hoặc bắt buộc
errors = validate(req.body)
if errors:
return 400, errors # lỗi validation: không lưu key
h = sha256(canonical_json(req.body))
row = try_reserve(req.user_id, key, h)
if row is None:
old = load(req.user_id, key)
if old.request_hash != h: return 422, {...}
if old.status == "processing": return 409, {...}
return old.response_code, old.response_body
code, body = handle(req)
save_response(req.user_id, key, code, body) # status = 'done'
return code, body
Theo tài liệu của Stripe, phiên bản v1 lưu mã trạng thái và body của request đầu tiên mang một key, tính từ lúc endpoint bắt đầu chạy, và phát lại chúng cho mọi lần retry, kể cả khi đó là lỗi 500.
Request trượt validation hoặc đụng một request khác đang chạy song song thì không được lưu, nên client cứ việc thử lại. Đó là lý do đoạn code trên validate trước khi giữ chỗ cho key.
Kiểm tra: sau một request thành công, SELECT status, response_code FROM idempotency_keys phải cho ra done cùng mã bạn vừa trả về.
Bước 4: chia việc thành từng pha khi có lời gọi ra ngoài
Đoạn code trên giả định handle chạy gọn trong một transaction. Ngoài thực tế, endpoint tạo đơn thường còn gọi cổng thanh toán hay gửi webhook sang hệ thống khác. Nếu tiến trình chết giữa chừng, dòng key sẽ kẹt mãi ở trạng thái processing.
Brandur xử lý chuyện này bằng atomic phase: một nhóm thay đổi trạng thái cục bộ chạy trong transaction, nằm giữa các lần thay đổi trạng thái ở hệ thống ngoài. Sau mỗi pha, bạn ghi một recovery point vào dòng key, chẳng hạn order_created hay payment_charged. Lần retry sau sẽ đọc recovery point đó và chạy tiếp từ chỗ đã dừng, thay vì làm lại từ đầu.
Với endpoint đầu tiên, bạn chưa cần dựng đủ cả bộ máy này. Hãy liệt kê mọi lời gọi ra ngoài trong handler: mỗi lời gọi là một ranh giới pha, và ngay sau mỗi ranh giới đó nên có một recovery point.
Bước 5: dọn key cũ và chứng minh bằng curl
Stripe có thể xóa key sau 24 giờ. Ví dụ dưới dùng đúng mốc đó; nếu khách retry lâu hơn, hãy tăng interval sao cho dài hơn cửa sổ retry lâu nhất của họ, rồi lên lịch chạy:
-- thay '24 hours' bằng khoảng dài hơn cửa sổ retry của khách
DELETE FROM idempotency_keys
WHERE created_at < now() - interval '24 hours';
Sau đó chạy ba kịch bản. Lệnh đầu tiên gửi một request bình thường:
curl -i -X POST https://api.example.com/orders \
-H "Idempotency-Key: 6f1d2c3a-8b4e-4f5a-9c7d-1e2f3a4b5c6d" \
-H "Content-Type: application/json" \
-d '{"sku":"A1","qty":2}'
Chạy lại y nguyên lệnh đó: bạn phải nhận về cùng một id đơn hàng và bảng orders không có thêm dòng nào. Giữ key nhưng đổi qty thành 3: kết quả phải là 422. Cuối cùng, dùng một key mới rồi bắn hai lệnh cùng lúc bằng cách thêm & sau mỗi lệnh. Nếu handler đủ chậm, một trong hai lệnh sẽ nhận 409.
Những lỗi hay gặp nhất
Lỗi phổ biến nhất là đặt unique trên mỗi cột key mà quên user_id. Lỗi thứ hai là chỉ lưu key mà không lưu hash payload, khiến client lỡ dùng lại key cho một đơn khác sẽ âm thầm nhận phản hồi của đơn cũ. Lỗi thứ ba là lưu cả lỗi validation, làm khách sửa xong request vẫn bị trả về cùng một lỗi 400.
Phía client cũng dễ sai không kém. Sinh key mới cho mỗi lần retry đồng nghĩa với việc không có idempotency nào cả. Blog của Stripe khuyên kết hợp key với retry theo backoff hàm mũ, cộng thêm một chút jitter ngẫu nhiên vào thời gian chờ của mỗi client, để các client không cùng đổ dồn vào server đúng một thời điểm.
Ở chỗ khách, kỹ năng này trông thế nào
Ở chỗ khách, đoạn SQL chỉ chiếm phân nửa công việc. Nửa còn lại là ngồi với đội tích hợp của khách, đọc code retry của họ và thống nhất ai sinh key, sinh ở đâu, lưu lại thế nào để lần retry dùng đúng key cũ.
Khi bạn đưa ra ba lệnh curl và bảng mã trạng thái ở trên, cuộc nói chuyện chuyển từ cãi xem lỗi thuộc bên nào sang thỏa thuận một hợp đồng API rõ ràng.
Nếu đang muốn chuyển sang làm FDE, bạn hãy làm bài này trên một dự án cá nhân rồi ghi vào CV cụ thể những gì đã kiểm chứng, ví dụ: “thêm Idempotency-Key cho API tạo đơn, kiểm thử gọi lặp, đổi payload và gọi song song”.
Khi đọc tin tuyển dụng, hãy để ý những yêu cầu về tích hợp API với hệ thống của khách. Đó là lúc bạn có thể kể lại bài thực hành này trong buổi phỏng vấn.
Lần tới có ai báo dữ liệu bị trùng, câu hỏi đầu tiên của bạn nên là: lần gọi lại có mang theo key cũ không?
Bài này có hữu ích không?
Cảm ơn bạn đã góp ý!