Cả bài trong một trang: ý chính, sơ đồ, điểm phỏng vấn.
REST API nâng cao: export bất đồng bộ, Idempotency-Key và tài liệu API
1Vì sao export phải bất đồng bộ
Export 500 MB mất vài phút, lâu hơn timeout của gateway (thường 60 giây). Làm đồng bộ thì gãy bốn kiểu.
Timeout: client nhận 504, bấm lại thành hai job
OOM: findAll() nạp cả kết quả vào heap
Thread và connection DB bị chiếm vài phút
Đứt mạng phút thứ 4 là làm lại từ đầu
2Luồng async job
POST tạo job trả 202 + Location, client hỏi trạng thái, rồi tải file qua presigned URL thẳng từ object storage.
sequenceDiagram
participant C as Client
participant A as API
participant S as Object storage
C->>A: POST /v1/exports
A-->>C: 202, Location /v1/jobs/001
C->>A: GET /v1/jobs/001
A-->>C: DONE
C->>A: GET /v1/jobs/001/result
A-->>C: 303 tới presigned URL
C->>S: tải file trực tiếp
3Job hỏng và webhook
Worker đọc DB và upload theo luồng nên bộ nhớ không đổi. Webhook ký HMAC trên raw body + timestamp; API trạng thái vẫn phải có.
Kiểu hỏng
Cách chặn
Worker chết giữa chừng
Lease locked_until, worker khác nhặt lại
Kết quả hết hạn
410 Gone, không phải 500
Đoán id job người khác
UUID và kiểm tra quyền
Quá tải
Giới hạn job mỗi user, 429
4Idempotency-Key đầy đủ
UNIQUE constraint chỉ chặn bản ghi thứ hai. Retry phải nhận lại đúng response lần đầu.
flowchart TD
A["Request + Idempotency-Key"] --> B{"Key đã có?"}
B -->|chưa| C["Insert IN_PROGRESS, xử lý, lưu response"]
B -->|"có, body khác"| D["422"]
B -->|"có, đang xử lý"| E["409 hoặc chờ"]
B -->|"có, COMPLETED"| F["Trả response đã lưu"]
5Envelope và mã lỗi
Envelope meta + data cho mọi response cùng hình dạng. Mã 6 chữ số = HTTP status + số thứ tự nghiệp vụ.
Bài này giải hai việc mà API đồng bộ “request vào, response ra” không làm nổi: thao tác mất vài phút (export file 500 MB) và thao tác không được chạy hai lần (thanh toán bị retry). Sau đó là response envelope với mã lỗi thống nhất và cách viết tài liệu API cho nhiều team dùng chung. Đọc xong, bạn thiết kế được async job và Idempotency-Key đầy đủ.
Nên đọc trước: phần 1 (safe và idempotent, phân trang), Web và HTTP (status code như 202, 303, 409, 410).
1. Case study: export file 500 MB
Ý chính: đừng làm export nặng trong một request đồng bộ. Tách thành “tạo job” và “lấy kết quả”, worker xử lý theo luồng, file đi thẳng từ object storage tới client.
1.1. Bài toán
Ý chính: API đồng bộ cho việc vài phút sẽ dính timeout, hết bộ nhớ, chiếm tài nguyên và không làm tiếp được khi đứt mạng.
Admin bấm “Xuất Excel” danh sách sản phẩm; với khách lớn, file khoảng 500 MB, tạo mất vài phút. Thiết kế ngây thơ: query, ghi file, trả file trong cùng request.
Timeout: Nginx proxy_read_timeout mặc định 60 giây, AWS ALB idle timeout 60 giây, Cloudflare khoảng 100 giây. Client nhận 504 nhưng server vẫn chạy; người dùng bấm lại thành hai job nặng.
OOM (out of memory, hết heap): findAll() nạp cả kết quả vào List, persistence context của JPA giữ mọi entity, thư viện Excel giữ cả workbook. 500 MB dữ liệu thành vài GB heap.
Giữ tài nguyên: thread servlet và connection DB bị chiếm vài phút; vài người export cùng lúc là pool cạn.
Không retry được: đứt mạng ở phút thứ 4 là làm lại từ đầu.
1.2. Thiết kế: async job
Ý chính:POST tạo job trả 202 Accepted + Location, GET hỏi trạng thái, GET /result chuyển hướng tới presigned URL (URL ký sẵn, hết hạn sau ít phút).
POST /v1/exports body {"type": "PRODUCTS", "filter": {"name": "pen"}} → 202 Accepted, header Location: /v1/jobs/001, body {"job_id": "001", "status": "PENDING", "issued_at": 1763443200000}.
GET /v1/jobs/001 → {"status": "PROCESSING", "progress": 42}, rồi {"status": "DONE", "updated_at": ...} hoặc {"status": "FAILED", "error": {...}}.
GET /v1/jobs/001/result → 302/303 tới presigned URL của object storage (S3, MinIO, GCS), hạn ví dụ 15 phút. File không đi qua app server.
Worker đọc và ghi theo luồng (stream: xử lý từng dòng rồi bỏ, không gom vào RAM), nên bộ nhớ không đổi dù file to cỡ nào.
Code worker export theo luồng và chi tiết theo từng DB
@Transactional(readOnly = true) // PostgreSQL: driver chỉ stream khi autocommit tắtpublic void runExport(ExportJob job, OutputStream out) { jdbcTemplate.setFetchSize(1_000); // lấy 1000 dòng mỗi lượt thay vì cả kết quả try (var writer = new BufferedWriter(new OutputStreamWriter(out, StandardCharsets.UTF_8))) { jdbcTemplate.query( "SELECT id, name, price FROM product WHERE name ILIKE ? ORDER BY id", rs -> { // RowCallbackHandler: từng dòng, không gom List writer.write(rs.getLong(1) + "," + csv(rs.getString(2)) + "," + rs.getBigDecimal(3)); writer.newLine(); }, "%" + job.filterName() + "%"); } catch (IOException e) { throw new UncheckedIOException(e); }}// out = stream multipart upload lên object storage, không phải file tạm khổng lồ trên đĩa pod
PostgreSQL: driver chỉ dùng cursor phía server khi autoCommit=false và fetchSize > 0.
MySQL Connector/J: cần useCursorFetch=true (hoặc fetchSize = Integer.MIN_VALUE để stream từng dòng).
Spring Data Stream<T>: phải trong transaction và detach entity sau mỗi dòng, nếu không persistence context vẫn phình.
Excel: dùng API streaming (Apache POI SXSSFWorkbook) hoặc xuất CSV.
1.3. Polling, webhook hay đẩy realtime
Ý chính: polling (client hỏi định kỳ) đơn giản nhất; webhook (server gọi lại URL của client) tiết kiệm nhưng phức tạp; SSE/WebSocket cho UI cần tiến độ tức thì. Dù chọn gì, vẫn giữ API trạng thái.
sequenceDiagram
participant C as Client
participant A as API
participant W as Worker
participant S as Object storage
C->>A: POST /v1/exports
A-->>C: 202 Accepted, Location /v1/jobs/001
A->>W: đưa job vào queue
loop Polling có backoff
C->>A: GET /v1/jobs/001
A-->>C: PROCESSING, Retry-After 5
end
W->>S: upload file theo multipart
W->>A: cập nhật job DONE
C->>A: GET /v1/jobs/001
A-->>C: DONE
C->>A: GET /v1/jobs/001/result
A-->>C: 303 tới presigned URL
C->>S: tải file trực tiếp
Với webhook, client gửi callback_url khi tạo job (hoặc đăng ký trước). Xong việc, server gọi POST callback_url với {"job_id": "001", "status": "DONE"}. Thực tế hay kết hợp: webhook để báo, API trạng thái làm dự phòng khi webhook mất.
Bảng so sánh polling, webhook và SSE/WebSocket
1.4. Các kiểu hỏng và cách xử lý
Ý chính: job async hỏng theo bốn kiểu: worker chết, kết quả hết hạn, lộ kết quả cho người khác, quá tải. Mỗi kiểu có một cách chặn cụ thể.
Worker chết giữa chừng: job kẹt PROCESSING. Worker cầm job bằng lease (quyền giữ có hạn, locked_until), gia hạn định kỳ; hết lease thì worker khác nhặt lại (SELECT ... FOR UPDATE SKIP LOCKED, xem transaction và locking). Quá số lần thử thì FAILED.
Kết quả hết hạn: lifecycle rule xoá file sau N ngày; GET /result trả 410 Gone, không phải 500.
Phân quyền: GET /jobs/{id} kiểm tra job thuộc user hiện tại. Id tăng dần dễ đoán: dùng UUID và vẫn kiểm tra quyền.
Quá tải: giới hạn job đồng thời mỗi user/tenant, vượt thì 429.
Code ký và xác minh chữ ký HMAC của webhook
static String sign(byte[] secret, long ts, String body) throws Exception { Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secret, "HmacSHA256")); return HexFormat.of().formatHex(mac.doFinal((ts + "." + body).getBytes(StandardCharsets.UTF_8)));}static boolean verify(byte[] secret, String header, String rawBody, long nowEpochSec) throws Exception { Map<String, String> kv = new HashMap<>(); for (String p : header.split(",")) { String[] x = p.split("=", 2); kv.put(x[0], x[1]); } long ts = Long.parseLong(kv.get("t")); if (Math.abs(nowEpochSec - ts) > 300) return false; // quá 5 phút: coi là replay byte[] expected = sign(secret, ts, rawBody).getBytes(StandardCharsets.US_ASCII); return MessageDigest.isEqual(expected, kv.get("v1").getBytes(StandardCharsets.US_ASCII));}// Chạy thử: đúng chữ ký -> true; sửa "DONE" thành "FAILED" -> false; gửi lại sau 1 giờ -> false
2. Case study: request trùng khi thanh toán
Ý chính: client gửi một Idempotency-Key cho mỗi thao tác; server lưu key cùng response lần đầu và trả lại đúng response đó cho mọi lần retry.
2.1. Bài toán
Ý chính: client bị timeout không biết tiền đã trừ chưa nên retry; mỗi request trùng là tiền thật.
Client gọi POST /payment-service/v1/payments. Server trừ tiền xong thì kết nối đứt, client nhận timeout và retry. Hoặc người dùng bấm “Thanh toán” hai lần, hoặc kẻ tấn công bắt request và gửi lại (replay).
Lời giải của khoá học: client sinh Idempotency-Key (UUID) cho mỗi thao tác, gửi trong header. Server lưu key vào cột có UNIQUE constraint; request thứ hai cùng key bị DB từ chối (“Duplicated!”).
2.2. Những gì lời giải gốc còn thiếu
Ý chính: UNIQUE constraint chỉ chặn bản ghi thứ hai. API idempotent đầy đủ còn phải trả lời sáu câu dưới đây.
Retry nhận được gì? Trả “Duplicated!” thì client tưởng thanh toán thất bại. Phải lưu response lần đầu và trả lại y nguyên (cùng status, cùng body).
Cùng key, khác body? (client có bug dùng lại key) Lưu hash body; khác thì trả 422 (Stripe làm vậy), không trả kết quả giao dịch cũ.
Hai request cùng key tới cùng lúc? Hoặc cho lần hai chờ (insert key trong cùng transaction, DB chặn ở unique index), hoặc trả 409 Conflict để client thử lại sau.
Phạm vi key: unique theo (client_id, key), không toàn cục.
Hết hạn: giữ key 24 giờ (Stripe) đến vài ngày, quá hạn thì job dọn dẹp xoá.
Lỗi nào thì lưu? Lỗi validation (400) không lưu, để client sửa rồi gửi lại cùng key. Kết quả nghiệp vụ đã chốt (thành công, “không đủ số dư”) thì lưu. Lỗi hạ tầng giữa chừng thì rollback cả key để retry chạy lại.
flowchart TD
A[Request + Idempotency-Key] --> B{Key đã có?}
B -- Chưa --> C[Insert key IN_PROGRESS] --> D[Xử lý nghiệp vụ] --> E[Lưu status + body, COMPLETED] --> F[Trả response]
B -- Có, hash body khác --> G[422 key bị dùng lại]
B -- Có, đang xử lý --> H[409 hoặc chờ]
B -- Có, COMPLETED --> I[Trả lại response đã lưu]
Bài Idempotency từ API đến Kafka và cổng thanh toán cài và chạy thử luồng này trên PostgreSQL (20 request trùng key cùng lúc chỉ tạo một giao dịch), kèm idempotency ở consumer Kafka và IPN cổng thanh toán.
Key nên do client sinh (UUID cho mỗi thao tác, giữ nguyên khi retry), vì chỉ client biết hai request là cùng một ý định.
Ba cách sinh key: client, server suy ra, server cấp trước
3. Response envelope và mã lỗi 6 chữ số
Ý chính: envelope (lớp bọc chung meta + data) cho mọi response cùng một hình dạng. Mã lỗi 6 chữ số chỉ có ích khi 3 chữ số đầu luôn bằng HTTP status thật.
Lỗi nghiệp vụ: meta.code = "400001", type = "INSUFFICIENT_DEBIT_AMOUNT", data = null. Mã 6 chữ số = HTTP status (3 chữ số) + số thứ tự nghiệp vụ (3 chữ số): nhìn 404003 biết ngay nhóm “không tìm thấy”. type là hằng số ổn định để client switch; message cho người đọc, có thể đổi.
4. Viết tài liệu API
Ý chính: tài liệu tốt mô tả rõ request/response, liệt kê mọi lỗi có thể xảy ra, có cURL chạy được; phần cơ học nên sinh tự động để không lệch với code.
4.1. Tài liệu cho một endpoint
Ý chính: mỗi endpoint cần spec chung, bảng field và bảng lỗi. Cột Description phải nói logic nghiệp vụ, format và ví dụ.
Ví dụ Description tốt cho amount: “integer, đơn vị nhỏ nhất của tiền tệ (VND không có phần lẻ), > 0, ≤ 500.000.000; ví dụ 150000”.
4.2. API map
Ý chính: API map là mục lục trả lời “luồng này gọi API nào, theo thứ tự nào, ai chịu trách nhiệm”, xếp theo luồng và theo resource.
Theo luồng (flow): Flow ID, tên luồng (Payment, Get balance), thứ tự gọi, link spec từng API, PIC (person in charge, người chịu trách nhiệm).
Theo resource: Payment, Order, Account… mỗi resource liệt kê mọi endpoint của nó.
Bắt đầu bằng bảng tính; quy mô lớn thì dùng developer portal (Backstage) hay API catalog. Tài liệu kiến trúc rộng hơn (C4, ADR) ở bài Viết tài liệu kiến trúc.
Ví dụ API map và Spring REST Docs
Flow
Bước
API
Service
PIC
F01 Payment
1
GET /account-service/v1/accounts/{id}/balance
account
Team A
F01 Payment
2
POST /payment-service/v1/payments
payment
Team B
F01 Payment
3
GET /payment-service/v1/payments/{id}
payment
Team B
Bài tập
Bài 1: Hợp đồng API cho export bất đồng bộ
Đề: viết đầy đủ các endpoint, status code và trạng thái job cho tính năng export.
Giải thích được vì sao export vài trăm MB phải là async job, và kể đủ bốn thứ gãy khi làm đồng bộ.
Vẽ được luồng POST → 202 + Location → polling → 303 presigned URL, và biết khi nào chọn webhook hay SSE.
Biết ký và xác minh webhook: HMAC trên raw body, timestamp chống replay, dedupe event_id.
Trả lời được sáu câu mà UNIQUE constraint chưa giải quyết cho Idempotency-Key.
Biết quy tắc mã lỗi 6 chữ số và khi nào chọn envelope riêng hay Problem Details.
Câu hỏi phỏng vấn
Junior
Vì sao không dùng GET để tạo job export?
Vì GET phải safe: nhiều thứ được phép gọi lại GET, và mỗi lần gọi lại sẽ tạo thêm một job nặng.
Crawler, prefetch, link preview và retry tự động đều có thể gọi lại GET. Tạo job là tạo resource nên dùng POST, trả 202 Accepted cùng header Location trỏ tới resource job.
Mid
Khi nào trả 202 Accepted thay vì 201 Created?
201 khi resource đã tạo xong ngay trong request; 202 khi server mới nhận yêu cầu và sẽ xử lý sau.
201 kèm Location tới resource. 202 nên kèm Location tới resource job để client theo dõi, có thể kèm Retry-After. 202 không hứa yêu cầu sẽ thành công.
Mã lỗi nghiệp vụ 6 chữ số có lợi gì và cần quy tắc gì?
Nhìn mã là biết nhóm lỗi (3 chữ số đầu là HTTP status), nhưng chỉ đúng khi prefix luôn khớp status thật.
3 chữ số sau là số thứ tự nghiệp vụ; type là hằng số ổn định để client switch. Quy tắc: prefix khớp HTTP status thật, mỗi mã một ý nghĩa duy nhất có trong tài liệu, không tái sử dụng mã cho ý nghĩa khác. Kiểm sự khớp bằng test tự động.
Senior
Thiết kế API export file vài trăm MB thế nào?
Làm async job: POST trả 202 + Location, worker xử lý theo luồng, kết quả qua presigned URL; không làm đồng bộ.
Đồng bộ thì dính timeout của LB/gateway (thường 60 giây), OOM, giữ thread và connection vài phút.
Worker đọc DB theo luồng (fetch size, cursor phía server, không gom List), ghi multipart lên object storage.
Client polling có Retry-After hoặc nhận webhook; tải qua presigned URL có hạn.
Worker chết: lease và retry có giới hạn. Thêm giới hạn job đồng thời mỗi tenant, kiểm tra quyền trên job, dọn file bằng lifecycle rule.
Idempotency-Key kiểu Stripe hoạt động thế nào?
Client gửi một key cho mỗi thao tác; server lưu key cùng response lần đầu và trả lại y nguyên cho mọi lần retry.
Server lưu (client, key) với UNIQUE constraint, hash body, trạng thái và response.
Lần đầu: insert key, xử lý, lưu status + body.
Lần sau cùng key: body khác → 422, đang xử lý → 409 (hoặc chờ), xong rồi → trả đúng response đã lưu.
Lỗi validation không lưu để client sửa; lỗi hạ tầng giữa chừng thì rollback key. Key hết hạn sau khoảng 24 giờ.
Polling, webhook, SSE/WebSocket: chọn thế nào cho thông báo job xong?
Polling cho tải thấp và mọi client, webhook cho B2B và thanh toán, SSE/WebSocket cho UI cần tiến độ tức thì; luôn giữ API trạng thái làm dự phòng.
Polling: đơn giản, chạy mọi client, tốn request rỗng.
Webhook: tiết kiệm, gần realtime, nhưng cần receiver có URL công khai, chữ ký HMAC, retry với backoff, receiver idempotent.
SSE/WebSocket: giữ kết nối lâu, phải phát sự kiện giữa các instance.
Bạn bảo vệ webhook receiver thế nào?
Xác minh chữ ký HMAC trên raw body, chống replay bằng timestamp, dedupe theo event_id, và với thanh toán thì gọi lại nhà cung cấp để xác nhận.
So chữ ký bằng phép so sánh thời gian hằng; chỉ nhận qua HTTPS.
Dedupe theo event_id vì bên gửi sẽ retry.
Trả 2xx nhanh rồi xử lý bất đồng bộ để không bị timeout và gửi lại.
Dữ liệu quan trọng: không tin tuyệt đối nội dung webhook, gọi API nhà cung cấp để xác nhận trạng thái.
Response envelope meta/data có nhược điểm gì?
Không chuẩn, client phải bóc data mọi chỗ, và dễ dẫn tới trả HTTP 200 cho cả lỗi.
Trả 200 cho lỗi làm hỏng retry, cache, alert dựa trên status. Nếu dùng, HTTP status phải luôn đúng và mã nghiệp vụ khớp status. Problem Details (RFC 9457) là lựa chọn chuẩn cho lỗi, mã nghiệp vụ để trong trường mở rộng.
Từ vựng tiếng Anh
Term
Phát âm
Nghĩa
Ví dụ câu tiếng Anh dùng trong phỏng vấn
idempotency key
/ˌaɪ.dəmˈpoʊ.tən.si kiː/
khoá chống xử lý trùng
“The client reuses the same idempotency key on every retry.”
async job
/ˈeɪ.sɪŋk dʒɑːb/
tác vụ bất đồng bộ
“We turned the export into an async job that returns 202.”
presigned URL
/ˌpriːˈsaɪnd ˌjuː.ɑːrˈel/
URL ký sẵn có hạn
“The result is downloaded through a presigned URL that expires in fifteen minutes.”
polling
/ˈpoʊ.lɪŋ/
hỏi định kỳ
“Polling is fine for exports, but it wastes requests at scale.”
webhook
/ˈweb.hʊk/
callback qua HTTP
“Partners receive a webhook when the payment settles.”
replay attack
/ˈriː.pleɪ əˈtæk/
tấn công gửi lại
“The timestamp in the signature protects us against replay attacks.”
envelope
/ˈen.və.loʊp/
lớp bọc response
“Every response uses the same envelope with meta and data.”
person in charge (PIC)
/ˈpɜːr.sən ɪn tʃɑːrdʒ/
người chịu trách nhiệm
“The API map lists the person in charge of each endpoint.”
lease
/liːs/
quyền giữ việc có thời hạn
“A worker holds a lease on the job and renews it while it runs.”
out of memory (OOM)
/aʊt əv ˈmem.ər.i/
hết bộ nhớ
“Loading the whole result set into a list caused an out-of-memory error.”
Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.