Dữ liệu FDE TimesViệc làm FDE đang mở 873▼9 Thay đổi số việc đang mở trong 7 ngày, so sánh cùng phạm vi: không tính việc của các công ty mới được theo dõi tuần nàyMới trong 7 ngày 55Công ty đang tuyển 181Nhận làm từ xa 25%Lương trung vị (Mỹ) $200kTuyển nhiều nhất Databricks 98
中文EN

Tờ báo của nghề Forward Deployed Engineer

Bách khoa

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ũ.

Chia sẻLinkedInFacebookX

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.
Cây quyết định về cách server xử lý một request mang Idempotency-Key. Nếu key chưa có trong bảng, server xử lý và lưu phản hồi. Nếu key đã có và payload khác lần đầu, server trả 422. Nếu payload giống nhưng lần đầu còn đang xử lý, server trả 409. Nếu lần đầu đã xong, server phát lại phản hồi cũ. Nhánh này được tô màu cam.
Server tra bảng idempotency_keys trước khi làm bất cứ việc gì. Một lần gọi lại hợp lệ nhận đúng phản hồi đã lưu, kể cả khi đó là lỗi 500. Nguồn: bản draft Idempotency-Key của IETF, tài liệu API của Stripe và hướng dẫn của Brandur Leach, theo bài viết.

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?

Dùng cùng trợ lý AIHỏi Claude ↗Hỏi ChatGPT ↗
4 nguồn
Đọc tiếp trên lộ trình · Chặng 2: Kỹ thuật rộngKhách cấm cài broker? Dựng hàng đợi việc ngay trong PostgresMột câu SKIP LOCKED đủ để chia việc cho nhiều worker; phần khó hơn là xử lý job kẹt và bảng phình.