Bạn đang ngồi trên tàu. Bấm Đặt hàng, vòng loading cứ quay, tàu chui vào hầm, mất sóng, một lúc sau app báo request bị timeout. Bên dưới hiện nút Thử lại.
Nút đó có nên ở đó không?
Còn tùy, mà cái "tùy" ấy lại nằm ở chỗ app không nhìn thấy. Timeout chỉ có nghĩa là client đã thôi chờ. Nó không cho biết server đã làm gì. Sau cùng một dòng lỗi ấy là ba câu chuyện khác hẳn nhau:
- Request chưa hề tới server. Chưa có gì xảy ra. Retry là đúng.
- Request tới nơi rồi bị lỗi. Không có gì được lưu. Retry là đúng.
- Request tới nơi, đơn đã được lưu, nhưng response rơi mất trên đường về. Retry sẽ tạo ra đơn thứ hai.
Nhìn từ phía client, ba trường hợp này giống hệt nhau. Cứ thế retry thì trường hợp 3 trừ tiền khách hai lần. Không bao giờ retry thì trường hợp 1 làm mất đơn. Lối ra duy nhất là sửa phía server, sao cho retry lúc nào cũng là lựa chọn đúng.
Bài này kể lại cách một nền tảng mười ba service NestJS làm điều đó trong repository: idempotency key cho chuyện cùng một request bị gửi hai lần, version cho chuyện hai người cùng sửa một bản ghi, và trường hợp cần cả hai cùng lúc. Chỗ nào phần cài đặt còn dang dở, tôi cũng sẽ nói rõ.
Đơn đã được tạo chưa? Timeout đang giấu điều gì
Hãy nghĩ tới cửa ra máy bay. Thẻ lên máy bay của bạn có một mã vạch. Lần quét đầu tiên cho bạn lên máy bay. Quét lại lần nữa, chẳng hạn vì nhân viên không nghe thấy tiếng "bíp", thì máy quét không cấp cho bạn ghế thứ hai. Nó báo đã lên máy bay.
Đó chính là tính chất ta cần. Máy quét thoải mái với chuyện quét hai lần vì nó giữ một cuốn sổ: mã vạch, kết quả, thời điểm. Lần quét thứ hai chỉ là tra sổ, không phải lên máy bay thêm lần nữa.
API có được tính chất đó nhờ hai mảnh ghép:
- client gửi kèm một key đặt tên cho thao tác, và retry bao nhiêu lần cũng gửi đúng key đó (mã vạch);
- server giữ một receipt (biên nhận) cho key đó cùng câu trả lời đã đưa ra, và phát lại câu trả lời ấy cho mọi lần retry (cuốn sổ ở cửa).
Toàn bộ ý tưởng chỉ có vậy. Phần còn lại là chi tiết, và bug nằm đúng trong chi tiết.
Idempotency key là gì, và ai tạo ra nó?
Một thao tác là idempotent nếu làm hai lần thì hệ thống vẫn ở đúng trạng thái như làm một lần. PUT /items/7 {"qty": 3} vốn đã idempotent: đặt số lượng bằng 3 hai lần thì vẫn là 3. POST /orders thì không: gọi lần nào ra một đơn mới lần đó.
Idempotency key giúp một lời gọi không idempotent lặp lại được mà không sinh chuyện. Client gửi nó trong một header, theo quy ước là Idempotency-Key, và IETF đang chuẩn hóa header này trong bản draft Idempotency-Key.
Key phải đại diện cho ý định của người dùng, chứ không phải cho từng lần gửi HTTP. Đây là lỗi hay gặp nhất, và nó gói gọn trong đúng một dòng:
// Sai: mỗi lần thử lại sinh key mới, server thấy ba request chẳng liên quan gì nhau
await retry(() =>
fetch('/api/v1/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify(order),
}),
);// Đúng: sinh key một lần, ngay lúc người dùng bấm nút, rồi dùng lại cho mọi lần retry
const idempotencyKey = crypto.randomUUID();
await retry(() =>
fetch('/api/v1/orders', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
body: JSON.stringify(order),
}),
);Nếu app có thể bị tắt giữa hai lần thử, hãy lưu key cùng bản nháp đơn. Một tấm thẻ lên máy bay mà cứ mỗi lần bạn tới cửa lại in ra mã vạch mới thì chẳng còn là thẻ lên máy bay nữa.
Trong repository, order service bắt buộc có header này khi ghi đơn, và chỉ nhận từ 16 đến 100 ký tự ASCII in được. UUID thì vừa. 1 thì không.
Thế nào là hai request "giống nhau"?
Chỉ có key thì chưa đủ. Có ba câu hỏi quyết định server sẽ làm gì.
Key này của ai? Key do client tự chọn, nên hai client hoàn toàn có thể chọn trùng nhau. Vì vậy receipt được giới hạn theo người gọi, tenant và thao tác, chứ không chỉ theo key. Hai người dùng cùng gửi abc… sẽ không bao giờ thấy receipt của nhau.
Có thật là cùng một request không? Một client có bug có thể dùng lại key cho một body khác. Server lưu fingerprint của request đầu tiên (hash của method, path đã chuẩn hóa và body) rồi so lại ở mỗi lần retry.
Lần trước đã ra sao? Đang chạy, đã xong, hay chưa từng bắt đầu.
Ghép lại thành bốn trường hợp:
| Key | Fingerprint | Lần gửi trước | Server trả lời |
|---|---|---|---|
| Mới | — | Chưa có | Chạy, lưu receipt |
| Đã thấy | Giống | Đã xong | Phát lại response đã lưu |
| Đã thấy | Giống | Đang chạy | "Đang xử lý, thử lại sau" |
| Đã thấy | Khác | Bất kỳ | Từ chối: key bị dùng lại |
Fingerprint có một cái bẫy. {"qty":2,"item":"A"} và {"item":"A","qty":2} là cùng một request nhưng khác byte. Hãy hash dạng chuẩn tắc (canonical) với key đã sắp xếp, đừng hash body thô:
import { createHash } from 'node:crypto';
type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
function canonical(value: Json): string {
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
if (value !== null && typeof value === 'object') {
const keys = Object.keys(value).sort();
return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
}
return JSON.stringify(value);
}
function fingerprint(method: string, path: string, body: Json): string {
return createHash('sha256').update(canonical({ method, path, body })).digest('hex');
}
console.log(
fingerprint('POST', '/orders', { qty: 2, item: 'A' }) ===
fingerprint('POST', '/orders', { item: 'A', qty: 2 }),
); // trueThư viện dùng chung trong repository cũng làm y như vậy, và còn từ chối số không hữu hạn lẫn object tham chiếu vòng.
Thêm hai lựa chọn nhỏ. Key gốc không bao giờ chạm vào bảng: order service chỉ lưu HMAC-SHA256 của key, một giá trị vô nghĩa nếu không có secret của server. Còn response được lưu thì mã hóa, vì nó chứa dữ liệu cá nhân y như chính đơn hàng và nằm trong bảng suốt một ngày.
Receipt nên nằm ở đâu? Ba thiết kế, ba khe hở
Câu hỏi thật sự không phải "có lưu receipt không?" mà là "receipt trở thành sự thật vào lúc nào, so với việc mà nó mô tả?"
Thiết kế 1: kiểm tra, làm, rồi ghi nhớ
const existing = await db.receipt.findUnique({ where: { key } });
if (existing) return existing.response;
const order = await db.order.create({ data: input }); // hai lần retry đều có thể tới được dòng này
await db.receipt.create({ data: { key, response: toDto(order) } });
return toDto(order);Các lần retry không lịch sự chờ nhau. Một client di động với timeout gắt sẽ bắn lần thứ hai trong khi lần thứ nhất vẫn đang chạy. Cả hai cùng đọc thấy "chưa có receipt", cả hai cùng tạo đơn. Khi tải cao, khe hở giữa lúc kiểm tra và lúc insert mở toang.
Thiết kế 2: claim trước, hoàn tất sau
Để một unique constraint chọn ra người thắng trước khi bắt đầu làm gì:
// Chỉ một lần gửi insert được claim; những lần khác đụng unique constraint
await db.receipt.create({ data: { key, status: 'IN_PROGRESS', leaseUntil: secondsFromNow(30) } });
const order = await db.order.create({ data: input }); // tự commit riêng
// <- process chết ngay tại đây
await db.receipt.update({ where: { key }, data: { status: 'SUCCEEDED', response: toDto(order) } });Trùng lặp đồng thời đã được giải quyết, nhưng đơn hàng và receipt vẫn commit riêng. Nếu process chết giữa hai bước, đơn đã tồn tại còn receipt vẫn báo "đang xử lý" cho tới khi lease hết hạn. Lúc đó lần retry kế tiếp claim lại và tạo đơn thứ hai. Nhả claim khi gặp bất kỳ lỗi nào, trong khi đã có thứ được ghi xuống, cũng mở ra đúng cái lỗ đó.
Đây không phải chuyện giả định. Một helper đời cũ, dùng chung, trong chính repository này có đúng hình dạng ấy, và decision record của mảng này ghi nhận một lỗ hổng fail-open phát hiện qua static review. Chính decision record đó cũng không dám hứa một bảo đảm chung cho toàn nền tảng.
Thiết kế 3: receipt commit cùng tác động bền vững đầu tiên
Thôi coi receipt là tờ ghi chú về công việc, hãy biến nó thành một phần của công việc. Command receipt của order service làm việc này qua hai bước.
Claim trong một transaction ngắn: insert receipt ở trạng thái IN_PROGRESS với một claim token mới và lease 30 giây. Nếu receipt đã có thì phát lại, báo "đang xử lý", hoặc tiếp quản một lease đã hết hạn.
Execute trong một transaction chứa mọi thứ bền vững:
return db.$transaction(
async (tx) => {
// Mọi lần gửi đụng tới key này đều xếp hàng ở đây cho tới khi transaction kết thúc
await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtextextended(${scope}, 0))`;
const receipt = await tx.receipt.findUniqueOrThrow({ where: { scope } });
if (receipt.status === 'SUCCEEDED') return receipt.response; // một lần gửi khác đã xong
if (receipt.claimToken !== claimToken) throw new ClaimLostError(); // lease của mình đã bị tiếp quản
const order = await tx.order.create({ data: input });
await tx.outboxEvent.create({ data: orderCreatedEvent(order) });
const response = { status: 201, body: toDto(order) };
await tx.receipt.update({ where: { scope }, data: { status: 'SUCCEEDED', response } });
return response;
},
{ isolationLevel: 'Serializable' },
);Giờ thử cho nó chết ở từng chỗ:
- Chết trước khi commit. Postgres rollback cả đơn, event lẫn lệnh cập nhật receipt. Receipt vẫn là
IN_PROGRESScho tới khi lease hết hạn, rồi một lần retry tiếp quản và làm lại từ đầu, như thể lần trước chưa từng xảy ra. - Chết sau khi commit. Đơn và receipt
SUCCEEDEDcùng tồn tại. Lần retry phát lại đúng response 201 đã lưu. - Bản gốc chậm, bản retry vội. Bản gốc bị kẹt trước khi vào transaction, lease hết hạn, một lần retry claim receipt với token mới. Khi bản gốc rốt cuộc chạy tới, bước kiểm tra token thất bại và nó dừng lại. Token đóng vai hàng rào (fencing token): chỉ ai đang giữ lease hiện tại mới được ghi.
Không có trạng thái nào mà đơn đã tồn tại còn receipt thì chưa, hay ngược lại. Dòng outbox đi chung transaction đó, nên event báo tin về đơn hàng cũng không thể thất lạc. Đó là transactional outbox.
Có một giới hạn: cách này chỉ đúng khi tác động bền vững đầu tiên nằm cùng database với receipt. Lời gọi sang nhà cung cấp thanh toán thì không bọc vào được. Khi đó hãy truyền một key xuống dưới, suy ra một cách tất định từ key của bạn để mọi lần retry gửi đúng một key (UUIDv7 dẫn xuất làm đúng việc này), hoặc đẩy lời gọi ra sau outbox và để một saga lo phần đó.
Làm sao chặn lost update? Version và If-Match
Idempotency key xử lý chuyện một client nói cùng một điều hai lần. Nó không giúp gì khi hai client nói hai điều khác nhau về cùng một bản ghi.
Hai nhân viên vận hành cùng mở một đơn. Cả hai đều thấy ghi chú giao hàng "để trước cửa", version 1. Alice sửa thành "gọi khi tới" rồi lưu. Bob vẫn đang nhìn version 1, sửa số điện thoại liên hệ rồi lưu cả form, kèm luôn ghi chú cũ. Thay đổi của Alice biến mất, và không ai nhận được lỗi nào. Đó là lost update.
Cách sửa: mọi lệnh ghi phải nói rõ nó dựa trên version nào, và database từ chối lệnh ghi dựa trên version cũ. Đoạn này chạy được ngay trong psql:
CREATE TABLE orders (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
note text NOT NULL,
version integer NOT NULL DEFAULT 1
);
INSERT INTO orders (note) VALUES ('để trước cửa');
-- Alice và Bob cùng đọc version 1. Alice ghi trước.
UPDATE orders SET note = 'gọi khi tới', version = version + 1
WHERE id = 1 AND version = 1; -- UPDATE 1
-- Bob vẫn đang cầm version 1.
UPDATE orders SET note = 'để trước cửa', version = version + 1
WHERE id = 1 AND version = 1; -- UPDATE 0: không ghi đè gì cả, báo xung độtKiểm tra và ghi nằm trong cùng một câu lệnh, nên không gì chen vào giữa được. Cách làm dễ bị cám dỗ, là đọc row, so version trong TypeScript rồi mới update, mở lại đúng cái khe mà mệnh đề WHERE vừa đóng.
Qua HTTP, version đi dưới dạng entity tag. GET trả về ETag: "1", client gửi PATCH kèm If-Match: "1", và server đặt version đó vào WHERE. Ở order service, thiếu If-Match hoặc If-Match sai định dạng sẽ nhận 428 Precondition Required: server không chịu đoán xem client đang nhìn phiên bản nào.
Quay lại cửa ra máy bay: nhân viên đổi bạn sang ghế 14C dựa trên sơ đồ ghế in ra từ trước. Nếu sơ đồ đã thay đổi kể từ lúc đó, lệnh đổi bị từ chối và họ phải in sơ đồ mới. Đó là optimistic locking. Không ai giữ khóa trong lúc suy nghĩ; xung đột hiếm khi xảy ra và bị bắt ngay lúc ghi.
SELECT … FOR UPDATE, tức phương án pessimistic, hợp khi việc đọc và ghi nằm gọn trong một transaction ngắn phía server. Nó không thể kéo dài qua cả phút một người ngồi sửa form, mà đó lại đúng là lúc lost update xảy ra.
Vì sao cần cả hai? Lần retry xung đột với chính bóng ma của nó
Đây là trường hợp khiến tôi thôi coi hai thứ này là hai tính năng tách rời.
Client gửi PATCH /orders/{id} kèm If-Match: "3". Server áp dụng xong, đơn lên version 4. Response rơi mất trong hầm. Client retry đúng request đó, vẫn với If-Match: "3".
Nếu chỉ có version, lần retry thất bại vì xung đột. Client đang xung đột với chính nó: "người ghi kia" là lần gửi đầu tiên của nó. Một client cẩn thận, xử lý xung đột bằng cách đọc lại rồi áp lại thay đổi, có thể áp một thay đổi tương đối như "thêm một sản phẩm" tới hai lần.
Khi có receipt đứng trước, lần retry không bao giờ chạm tới bước kiểm tra version. Cùng key, cùng fingerprint, receipt SUCCEEDED: server phát lại đúng 200 ban đầu kèm ETag: "4". Điều này chạy được vì order service đưa expectedVersion vào fingerprint và lưu header ETag cùng response.
| Mối nguy | Idempotency key | Kiểm tra version |
|---|---|---|
| Một request tới hai lần | Phát lại câu trả lời đầu | Báo xung đột giả |
| Hai người sửa một bản ghi | Không nhìn thấy | Từ chối lệnh ghi cũ |
| Retry sau khi mất response | Phát lại kèm ETag mới | Cần key đứng trước |
Vậy nên kiểm tra receipt trước, version sau. Receipt trả lời câu "mình đã thấy đúng request này chưa?", còn version trả lời câu "request này có dựa trên dữ liệu hiện tại không?". Chỉ request mới cần tới câu hỏi thứ hai.
Phía consumer có cần điều tương tự không?
Có, vì event được giao ít nhất một lần. Consumer cần cuốn sổ riêng của mình: một bảng inbox với event id unique, ghi cùng transaction với tác động, cộng thêm version theo từng aggregate để một event cũ tới muộn không ghi đè trạng thái mới hơn. Bài về outbox đi qua từng trường hợp hỏng đó.
Bên dưới cả hai phía còn một lớp chặn cuối. Decision record giữ nguyên tắc dùng constraint hoặc transaction của database làm chốt chặn cuối cùng cho các bất biến. Key và version giúp retry rẻ; constraint giúp bug lộ ra ầm ĩ.
Receipt nên sống bao lâu?
Giữ mãi thì tốn, giữ quá ngắn thì trùng lặp quay lại. Order service giữ command receipt trong 24 giờ. Khi receipt hết hạn, job dọn dẹp không xóa nó mà chỉ xóa phần response đã lưu và đánh dấu row là đã purge, để lại một tombstone. Hash của key và fingerprint vẫn còn, nên client retry bằng một key đã cũ một ngày sẽ nhận "receipt đã hết hạn" thay vì một đơn thứ hai.
Lại là chuyện hãng bay: sau chuyến bay, sổ ở cửa quên thông tin hành khách nhưng vẫn nhớ mã vạch đó đã được quét.
Receipt đời cũ dùng chung trong cùng service thì xóa thẳng row hết hạn và dùng lease 5 phút thay vì 30 giây. Chính điểm vênh đó là lý do decision record dặn không được hứa giữ receipt 24 giờ trên toàn nền tảng.
Tôi sẽ đổi status code nào?
Hiện tại, mọi xung đột idempotency trong order service đều là 409 Conflict với error code riêng, và version cũ cũng là 409. Client vẫn phân biệt được nhờ error code, nhưng bản thân HTTP status đang nói ít hơn mức nó có thể:
| Tình huống | Trong repository hiện tại | Tôi sẽ trả về |
|---|---|---|
| Dùng lại key, body khác | 409 IDEMPOTENCY_KEY_REUSED |
422, như draft IETF gợi ý |
| Cùng key, vẫn đang chạy | 409, retryAfterMs trong body |
409 kèm header Retry-After |
If-Match đã cũ |
409 VERSION_CONFLICT |
412 Precondition Failed |
Thiếu If-Match |
428 | 428, giữ nguyên |
Đổi sang 412 là quan trọng nhất. RFC 9110 quy định rõ một If-Match thất bại phải trả về gì, và các HTTP client phổ thông vốn đã hiểu nó. Trả 409 thì client nào cũng phải viết code riêng cho API của bạn.
Còn một chỗ vênh khó thấy hơn: một service chờ If-Match: "7", service khác lại parse W/7. RFC 9110 so If-Match bằng phép so sánh mạnh (strong comparison), mà theo đó weak tag không bao giờ khớp. Tôi sẽ dùng strong tag ở mọi nơi, sinh ra từ một helper duy nhất.
Cái giá phải trả
- Thêm một lệnh ghi cho mỗi mutation, cộng một lần tra cứu cho mỗi lần retry.
- Mỗi key một đường đi tuần tự. Advisory lock thì rẻ, nhưng transaction tạo đơn chạy ở mức
Serializablevà được thử lại một lần khi gặp xung đột ghi. Traffic bình thường hiếm khi đụng cùng một key cùng lúc; key nóng thì sẽ thấy chậm. - Thêm secret phải quản lý. Key được hash và response được mã hóa nghĩa là xoay vòng khóa trở thành một phần của tính năng.
- Kỷ luật phía client. Không thứ gì ở trên cứu được một client sinh key mới cho mỗi lần gửi.
- Những quyết định không ai làm hộ. Lỗi nào được lưu, key hết hạn thì trả gì: đó là lựa chọn sản phẩm, không phải giá trị mặc định của thư viện.
Nếu làm lại, tôi sẽ làm khác gì?
Một cách cài đặt, không phải hai thế hệ. Order service đang có helper dùng chung (lease 5 phút, response lưu dạng JSON thô, xóa khi hết hạn, hoàn tất bên ngoài transaction nghiệp vụ) nằm cạnh command receipt mới hơn (lease 30 giây, response mã hóa, có tombstone, hoàn tất bên trong transaction). Các service khác lại có biến thể riêng. Tôi sẽ đưa thiết kế 3 vào thư viện dùng chung trước khi endpoint thứ hai cần tới nó.
Chỉ lưu những lỗi sẽ lặp lại. Command receipt ghi lại lỗi nó đã trả về, nên retry bằng cùng key sẽ nhận lại đúng lỗi đó. Như vậy là hợp lý với "sản phẩm đã hết hàng". Nhưng khi một lỗi tạm thời đã khiến transaction rollback, tức là chưa có gì xảy ra, tôi sẽ nhả claim để cùng key đó được chạy lại.
Viết test race condition trước. Tiêu chí hoàn thành trong decision record là đúng danh sách cần có: request trùng đồng thời, crash rồi retry, hết hạn, phát lại response, và race giữa các lần cập nhật cũ, cho từng endpoint, trước khi gọi endpoint đó là đã release.
Chốt status code ngay từ ngày đầu. Đổi về sau là làm gãy mọi client đã quen với code cũ.
Tóm tắt
- Timeout giấu ba kết cục. Thay vì đoán xem chuyện gì đã xảy ra, hãy làm cho retry lúc nào cũng an toàn.
- Client sinh một key cho mỗi ý định của người dùng và dùng lại nó ở mọi lần retry.
- Giới hạn receipt theo người gọi, tenant và thao tác, và so một fingerprint chuẩn tắc để key bị dùng lại không phát lại nhầm câu trả lời.
- Commit receipt trong cùng transaction với tác động bền vững đầu tiên. Làm khác đi là để hở một khe mà việc đã xảy ra còn receipt thì không biết.
- Version chặn lost update giữa nhiều người; key chặn trùng lặp từ một client. Kiểm tra receipt trước, version sau.
- Cho receipt hết hạn thành tombstone thay vì xóa hẳn, để một key cũ thất bại rõ ràng.
Phần tiếp theo là phiên đăng nhập, và nó dùng đúng mẹo này: refresh token rotation là một lệnh update có điều kiện mà chỉ một request thắng được.