Cụm bài REST API nâng cao: 1. Method idempotent, URL và phân trang · 2. Async job, Idempotency-Key và tài liệu API
Bài Thiết kế REST API và Spring Boot đã nói quy ước cơ bản (URL, versioning, format lỗi, cache HTTP); bài này lo phần API “chạy được trên production”: ngữ nghĩa method, URL qua gateway, phân trang bảng hàng chục triệu dòng, sắp xếp và quan hệ. Phần 2 đi tiếp vào export file 500 MB, request thanh toán bị trùng và tài liệu API. Nên đọc trước: Web và HTTP (ngữ nghĩa method, status code) và Index và hiệu năng truy vấn (vì sao OFFSET chậm).
Sơ đồ tóm tắt:
mindmap
root((REST API nâng cao))
Idempotent
PUT, DELETE idempotent
POST không, PATCH không đảm bảo
Retry chỉ với idempotent
URL
Tên service chỉ cho nội bộ
Phân trang
OFFSET chậm và sót dòng
Cursor: lấy sau dòng cuối
Deferred join vẫn theo offset
Sort qua whitelist
1. Tư duy: thiết kế trước, code sau
Ý chính: thiết kế API trước khi code rẻ hơn sửa sau, vì API công khai khó đổi nhất: bạn không kiểm soát client.
(“Soft” trong software nghĩa là dễ thay đổi.) Thiết kế trước giúp:
- Nghĩ ở mức cao: bao phủ từ đầu lỗi, phân trang, retry, quyền.
- Ít công sửa: đổi một dòng thiết kế rẻ hơn đổi API mà mobile app đã phát hành đang dùng.
- Làm song song: frontend, mobile, đối tác code theo hợp đồng (contract), dựng mock server từ spec.
Bốn nguyên tắc khi review API:
- Scalable: dữ liệu tăng 100 lần còn đúng không? (OFFSET, export đồng bộ, response không giới hạn hay gãy ở đây.)
- Consistency: mọi service chung quy ước tên field, phân trang, format và mã lỗi.
- Inspect every single aspect: lỗi, phân trang, sắp xếp, xác thực, phân quyền, idempotency, timeout, rate limit, kích thước payload.
- No one fits all: chỉ có trade-off hợp bối cảnh.
2. Safe và idempotent: định nghĩa cho đúng
Ý chính: safe = không đổi trạng thái server; idempotent = gửi 1 hay N lần thì trạng thái server sau cùng như nhau. Cả hai nói về tác động lên server, không nói về response.
| Method | Safe | Idempotent | Dùng cho |
|---|---|---|---|
| GET, HEAD, OPTIONS, TRACE | Có | Có | Đọc |
| PUT | Không | Có | Thay thế toàn bộ resource |
| DELETE | Không | Có | Xoá, vô hiệu hoá |
| POST | Không | Không | Tạo mới, hành động |
| PATCH | Không | Không đảm bảo | Sửa một phần |
Ghi log hay tăng counter thống kê không tính là “đổi trạng thái”.
Hai sắc thái hay bị hỏi:
- PATCH không bị cấm idempotent, chỉ không được đảm bảo: JSON Merge Patch
{"age": 34}thì có, JSON Patch “tăngbalancethêm 10” thì không. - POST có thể được làm cho idempotent bằng Idempotency-Key (phần 2): server tự đảm bảo, HTTP không.
Vì sao quan trọng: client, proxy, thư viện HTTP và service mesh tự retry khi timeout. Retry mù một POST chuyển tiền là tạo giao dịch thứ hai.
3. Quy ước URL và routing qua API gateway
Ý chính: URL dùng danh từ số nhiều, có version, quy ước chung toàn công ty. Tên service ở đầu path giúp gateway route đơn giản, nhưng chỉ nên dùng cho API nội bộ.
- Danh từ, không động từ:
/orders, không/createOrder. Hành động ngoài CRUD thành sub-resource:POST /orders/145/cancellation. - Số nhiều cho collection:
/users,/users/34. - Lồng URL để thể hiện quan hệ, tối đa hai cấp:
/posts/{post_id}/comments. - Version trong path:
/v1/.... - kebab-case cho URL (
/order-items), snake_case cho field JSON (total_amount) hoặc camelCase, miễn thống nhất. Khoá học dùng snake_case.
Bài tập nhỏ từ khoá học: URL qua API gateway
API Gateway đứng trước User Service (team A) và Order Service (team B). Segment đầu của path là tên service để gateway route theo prefix (tiền tố):
| Yêu cầu | Method + URL |
|---|---|
| Tạo order | POST /order-service/v1/orders |
| Xem chi tiết order 145 | GET /order-service/v1/orders/145 |
| Chỉ sửa tuổi của user 34 | PATCH /user-service/v1/users/34 body {"age": 35} |
| Vô hiệu hoá user 34 | DELETE /user-service/v1/users/34 (dù bên dưới là soft delete) |
Reverse proxy với Nginx dựng bài tập trên bằng Docker Compose (Nginx bỏ tên service, chuyển /v1/... vào trong), kèm lỗi proxy_pass có/không có URI và header X-Forwarded-*.
4. Phân trang ở quy mô lớn
Ý chính: OFFSET chậm dần theo độ sâu trang và sót dòng khi dữ liệu đổi. API công khai dùng cursor; chỉ khi buộc “nhảy tới trang N” mới dùng OFFSET, kèm deferred join.
4.1. Hai kiểu tham số
Ý chính: page/size và offset/limit khác tên nhưng cùng là offset pagination dưới SQL.
page+size:GET /users?page=0&size=20, hợp trang quản trị có số trang.offset+limit:GET /events?offset=40&limit=20, hay gặp với infinite scroll, log, sự kiện.
Bug thật hay gặp: không ghi rõ page bắt đầu từ 0 hay 1. Spring Data mặc định 0, nhiều frontend mặc định 1; lệch nhau là trang đầu biến mất. Luôn giới hạn size tối đa (ví dụ 100) và trả 400 thay vì âm thầm cắt. Trong Spring Boot, spring.data.web.pageable.one-indexed-parameters=true cho ?page=1 là trang đầu, còn max-page-size thì âm thầm cắt size về mức trần, không trả 400 (bài DTO, response và validation).
4.2. Hai vấn đề của OFFSET
Ý chính: OFFSET tốn O(offset), và dòng bị xoá/thêm giữa hai lần gọi làm dữ liệu trượt qua ranh giới trang.
Vấn đề 1: hiệu năng. OFFSET 100000 LIMIT 10 đọc rồi vứt 100.000 dòng. SELECT COUNT(*) cho tổng số trang phải đếm mọi dòng khớp: PostgreSQL lẫn InnoDB không lưu sẵn số dòng vì MVCC (DB giữ nhiều phiên bản mỗi dòng, mỗi transaction thấy số dòng khác nhau).
Vấn đề 2: resource skipping (bỏ sót bản ghi). Chạy thử trên PostgreSQL 16, bảng users id 1..200000, trang 5 dòng:
SELECT id FROM users ORDER BY id LIMIT 5 OFFSET 0; -- trang 1: 1,2,3,4,5
DELETE FROM users WHERE id IN (2, 3); -- ai đó xoá 2 dòng của trang 1
SELECT id FROM users ORDER BY id LIMIT 5 OFFSET 5; -- trang 2: 8,9,10,11,12 (mất 6 và 7!)
SELECT id FROM users WHERE id > 5 ORDER BY id LIMIT 5; -- keyset: 6,7,8,9,10
Dòng 6 và 7 “trượt” lên trang 1 đã đọc xong, nên không bao giờ hiện ra. Insert vào đầu danh sách thì ngược lại: phần tử bị lặp ở trang sau. Với feed là khó chịu; với job đồng bộ lặp qua các trang là mất dữ liệu.
4.3. Cursor (keyset) pagination
Ý chính: thay vì “bỏ qua N dòng”, lọc “các dòng sau dòng cuối của trang trước”. Trang sâu cỡ nào cũng nhanh như trang đầu.
-- index: (created_at DESC, id DESC)
SELECT id, name, created_at
FROM users
WHERE (created_at, id) < (:last_created_at, :last_id) -- MySQL: viết dạng OR khai triển
ORDER BY created_at DESC, id DESC
LIMIT 20;
Trên bảng thử, câu này đọc đúng 10 dòng (Index Cond: ROW(created_at, id) < ROW(...), 0,02 ms) dù con trỏ sâu cỡ nào. Ba điều kiện:
- Khoá sắp xếp duy nhất và ổn định:
created_atcó thể trùng, nên thêmidlàm tie-breaker (cột phụ phá thế hoà). Tránh cột hay bị sửa (nhưupdated_at): dòng sẽ nhảy qua lại giữa các trang. - Index khớp đúng thứ tự
ORDER BY. - Cursor mờ (opaque): trả chuỗi
next_cursorthay vìlast_idtrần, để client không phụ thuộc cấu trúc bên trong và server đổi được khoá sort mà không breaking.
Response gợi ý: {"data": [...], "meta": {"next_cursor": "MTc5MzUyNzIwMDAwMDo5ODE", "has_next": true}}. Lấy limit + 1 dòng để biết has_next mà không cần COUNT(*). Thiết kế news feed kiểu Threads dùng đúng cursor này (id bài cuối đã xem), vì bài mới chèn lên đầu làm OFFSET trả lặp bài.
Cursor base64 ai cũng decode và sửa được: server luôn áp lại lọc và phân quyền, không tin cursor.
Code Java encode/decode cursor và bẫy base64
record Cursor(Instant createdAt, long id) {
String encode() {
String raw = createdAt.toEpochMilli() + ":" + id;
return Base64.getUrlEncoder().withoutPadding()
.encodeToString(raw.getBytes(StandardCharsets.UTF_8));
}
static Cursor decode(String token) {
try {
String raw = new String(Base64.getUrlDecoder().decode(token), StandardCharsets.UTF_8);
String[] parts = raw.split(":", 2);
return new Cursor(Instant.ofEpochMilli(Long.parseLong(parts[0])), Long.parseLong(parts[1]));
} catch (RuntimeException e) {
throw new IllegalArgumentException("invalid cursor"); // map thành 400, đừng để thành 500
}
}
}
4.4. Deferred join khi buộc phải dùng OFFSET
Ý chính: phân trang trên một index nhỏ chỉ lấy id, rồi join lại lấy cột đầy đủ cho đúng 10 dòng. Rẻ hơn khoảng 10 lần nhưng vẫn là O(offset).
Dùng khi trang quản trị cần “nhảy tới trang 37”, không dùng cursor được. SQL trong slide trộn USING id với JOIN ... ON nên không chạy; bản đúng:
-- PostgreSQL và MySQL đều chạy
SELECT u.*
FROM (
SELECT id FROM users
ORDER BY created_at DESC, id DESC
LIMIT 10 OFFSET 150000
) AS page
JOIN users u USING (id)
ORDER BY u.created_at DESC, u.id DESC; -- join không giữ thứ tự, phải ORDER BY lại
Nó rẻ hơn chỉ vì đi trên index thay vì dòng đầy đủ. Trên PostgreSQL, bảng chưa VACUUM thì mẹo này có thể còn chậm hơn.
Số đo deferred join trên PostgreSQL 16 và bẫy visibility map
Bảng 200.000 dòng, mỗi dòng có cột bio 500 byte, index (created_at DESC, id DESC), sau VACUUM:
| Câu | Plan chính | Buffer đọc |
|---|---|---|
SELECT * ... LIMIT 10 OFFSET 150000 |
Index Scan, lấy 150.010 dòng đầy đủ từ heap | ~11.900 trang |
| Deferred join | Index Only Scan (Heap Fetches: 0) + 10 lần tra PK | ~1.200 trang |
Tổng số trang tốn một COUNT(*) mỗi request; mặc định cho API công khai là has_next + cursor.
Các cách trả tổng số trang
5. Sắp xếp và lọc
Ý chính: chỉ cho sort theo field trong whitelist, ánh xạ tên field API sang tên cột thật, và luôn thêm id làm tie-breaker.
Cú pháp: GET /products?sort=price:asc,name:desc hoặc sort=+price,-name. Whitelist vì:
- An toàn: tên cột trong
ORDER BYkhông bind parameter được như giá trị; ghép chuỗi là SQL injection. - Hiệu năng: mỗi field sort được phép phải có index; cho sort tuỳ ý là cho client quyền gây full scan + filesort (sort ngoài index) trên bảng lớn.
Code Java: dựng ORDER BY từ whitelist
static final Map<String, String> SORTABLE = Map.of(
"price", "p.price", "name", "p.name", "created_at", "p.created_at");
static String orderBy(String sort) {
if (sort == null || sort.isBlank()) return "p.created_at DESC, p.id DESC";
String[] items = sort.split(",");
if (items.length > 3) throw new IllegalArgumentException("too many sort fields");
StringJoiner sql = new StringJoiner(", ");
for (String item : items) {
String[] kv = item.trim().split(":");
String column = SORTABLE.get(kv[0]); // tên field API -> tên cột thật
if (column == null) throw new IllegalArgumentException("unsupported sort field: " + kv[0]);
String dir = kv.length > 1 ? kv[1].toLowerCase(Locale.ROOT) : "asc";
if (!dir.equals("asc") && !dir.equals("desc")) throw new IllegalArgumentException("bad direction: " + dir);
sql.add(column + " " + dir.toUpperCase(Locale.ROOT));
}
return sql.add("p.id ASC").toString(); // tie-breaker: thứ tự luôn xác định
}
// orderBy("price:desc,name") -> "p.price DESC, p.name ASC, p.id ASC"
6. Mô hình hoá quan hệ
Ý chính: quan hệ thể hiện bằng URL lồng nhau; thêm một phần tử dùng PUT (idempotent), thêm nhiều dùng bulk endpoint có giới hạn lô.
- 1-N:
GET /articles/123/comments. - N-N (lớp và học viên):
GET /classes/{class_id}/students. - Thêm một học viên: slide dùng
POST /classes/{id}/students/{student_id}. Mình thíchPUT: URL đã đủ xác định quan hệ, gọi lại bao nhiêu lần vẫn vậy (đúng ngữ nghĩa idempotent). Gỡ ra:DELETE /classes/{id}/students/{student_id}. - Thêm nhiều học viên:
POST /classes/{id}/studentsvới body{"student_ids": ["s1", "s2", "s3"]}.
Bài tập
Bài 1: Thiết kế URL cho hệ thống lớp học
Đề (diễn giải): service course-service quản lý lớp và học viên. Viết method + URL cho: liệt kê học viên lớp 7, thêm s9 vào lớp 7, thêm nhiều học viên một lần, gỡ s9 khỏi lớp, đổi tên lớp.
Lời giải Bài 1
GET /course-service/v1/classes/7/students?limit=20&cursor=...
PUT /course-service/v1/classes/7/students/s9 # idempotent, 204 dù đã có hay chưa
POST /course-service/v1/classes/7/students # {"student_ids": ["s1","s2"]}, tối đa 100
DELETE /course-service/v1/classes/7/students/s9 # 204, gọi lại vẫn 204 hoặc 404, đều được
PATCH /course-service/v1/classes/7 # {"name": "Java nâng cao K12"}
Senior sẽ hỏi thêm: thêm học viên vào lớp đã đủ chỗ trả gì (409 hoặc 422 với type rõ ràng), và bulk add là all-or-nothing hay từng phần.
Bài 2: Chuyển API danh sách giao dịch sang cursor
Đề: GET /v1/transactions?page=&size= chậm ở trang sâu và job đối soát bị sót giao dịch. Thiết kế lại.
Lời giải Bài 2
GET /v1/transactions?limit=50&cursor=<opaque>; sắpORDER BY created_at DESC, id DESC.- Index
(account_id, created_at DESC, id DESC)vì luôn lọc theo tài khoản. - Cursor = base64 của
created_at|id; trảnext_cursorvàhas_next(lấy 51 dòng). - Job đối soát lặp theo khoá tăng dần (
id > :last_id), không theo số trang. - Giữ API cũ một thời gian, đánh dấu header
Deprecation.
Ghi nhớ
- Giải thích được vì sao DELETE lần hai trả 404 vẫn idempotent, và PATCH khi nào idempotent.
- Nêu được hai vấn đề của OFFSET và vì sao job đồng bộ theo số trang mất dữ liệu.
- Kể được ba điều kiện của cursor pagination, và vì sao không tin dữ liệu trong cursor.
- Biết khi nào dùng deferred join và vì sao trên PostgreSQL nó có thể chậm hơn.
- Biết khi nào giữ tên service trong URL, khi nào để gateway ánh xạ theo resource.
Câu hỏi phỏng vấn
Junior
Safe và idempotent khác nhau thế nào? Cho ví dụ method idempotent nhưng không safe.
Safe là không đổi trạng thái server; idempotent là gọi 1 hay N lần thì trạng thái cuối như nhau. PUT và DELETE idempotent nhưng không safe.
Mọi method safe (GET, HEAD) đều idempotent, chiều ngược lại không đúng: PUT và DELETE thay đổi dữ liệu nhưng lặp lại vẫn ra cùng trạng thái. Idempotent không yêu cầu response giống nhau: DELETE lần hai có thể trả 404.
Vì sao phải ghi rõ page bắt đầu từ 0 hay 1?
Vì hai bên mặc định khác nhau (Spring Data từ 0, nhiều UI từ 1), hiểu lệch là mất hoặc lặp một trang mà không có lỗi nào báo.
Ghi rõ trong tài liệu, validate giá trị âm, và giới hạn size tối đa.
Mid
Vì sao OFFSET chậm trên bảng lớn, và ngoài hiệu năng nó còn vấn đề gì?
DB phải đọc rồi bỏ mọi dòng trước offset, nên chi phí tăng tuyến tính theo độ sâu trang; ngoài ra dữ liệu đổi giữa hai lần gọi làm sót hoặc lặp dòng.
COUNT(*) cho tổng số trang cũng phải quét mọi dòng khớp. Resource skipping: dòng bị xoá hoặc thêm làm các dòng trượt qua ranh giới trang. Với job đồng bộ dữ liệu, sót dòng là mất dữ liệu.
Cursor pagination cần những điều kiện gì để đúng?
Khoá sắp xếp duy nhất và ổn định, index khớp đúng ORDER BY, và cursor mờ.
Thêm id làm tie-breaker, tránh sort theo cột hay bị sửa. Cursor mờ để client không phụ thuộc cấu trúc bên trong. Server vẫn áp lại mọi điều kiện lọc và phân quyền ở mỗi request, không tin dữ liệu trong cursor. Đổi lại, không nhảy tới trang bất kỳ được.
Deferred join là gì và khi nào nó không giúp?
Phân trang trên index nhỏ chỉ lấy id, rồi join lại lấy cột đầy đủ cho đúng số dòng của trang; ít trang phải đọc hơn nhưng vẫn O(offset).
Không giúp khi index không đủ để trả lời subquery (phải đọc bảng), hoặc trên PostgreSQL khi visibility map chưa được VACUUM: index-only scan vẫn phải đọc heap và có thể chậm hơn câu thường.
Vì sao phải whitelist field sort?
Vì tên cột trong ORDER BY không bind được như tham số, ghép chuỗi là SQL injection; và sort theo cột không có index gây full scan.
Full scan + sort tốn RAM trên bảng lớn; whitelist chỉ mở các field đã có index. Thêm id làm tie-breaker để thứ tự xác định khi phân trang.
Senior
Có nên đặt tên service vào URL công khai không?
Với API công khai thì không: tách hoặc gộp service là URL đổi, tức breaking change. Với API nội bộ thì được.
Tên service trong path giúp gateway route bằng một quy tắc prefix và mỗi team tự quản namespace, nhưng lộ cấu trúc nội bộ. Mình giữ tên service cho API service-to-service, còn API cho mobile hoặc đối tác thì ánh xạ theo resource ở gateway hoặc BFF để URL ổn định theo nghiệp vụ.
Thiết kế endpoint thêm nhiều phần tử một lúc thế nào?
Giới hạn kích thước lô và chọn rõ ngữ nghĩa: all-or-nothing trong một transaction, hoặc partial success trả kết quả từng phần tử.
All-or-nothing dễ hiểu, client retry cả lô. Partial success trả 207 hoặc 200 với danh sách trạng thái; khi đó retry phải idempotent (thêm lại phần tử đã có không được lỗi), nên dùng upsert hoặc ON CONFLICT DO NOTHING. Ghi hành vi vào tài liệu và có test cho trường hợp lỗi giữa lô.
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 |
|---|---|---|---|
| keyset pagination | /ˈkiː.set ˌpædʒ.əˈneɪ.ʃən/ | phân trang theo khoá | “Keyset pagination keeps deep pages as fast as the first one.” |
| tie-breaker | /ˈtaɪ ˌbreɪ.kər/ | cột phụ để phá thế hoà khi sắp xếp | “We add the id as a tie-breaker so the order is deterministic.” |
| opaque cursor | /oʊˈpeɪk ˈkɜːr.sər/ | con trỏ mờ, client không hiểu nội dung | “The cursor is opaque, so we can change the sort key later.” |
| resource skipping | /ˈriː.sɔːrs ˈskɪp.ɪŋ/ | sót bản ghi khi phân trang | “Deletes between page loads caused resource skipping in the sync job.” |
| deferred join | /dɪˈfɜːrd dʒɔɪn/ | join trì hoãn | “A deferred join pages over the index first and fetches full rows later.” |
| design-first | /dɪˈzaɪn fɜːrst/ | thiết kế hợp đồng trước khi code | “We work design-first, so the OpenAPI spec is reviewed before any code is written.” |
| API gateway | /ˌeɪ.piːˈaɪ ˈɡeɪt.weɪ/ | cổng API đứng trước các service | “The API gateway routes requests by path prefix.” |
| bulk endpoint | /bʌlk ˈend.pɔɪnt/ | endpoint xử lý nhiều phần tử | “The bulk endpoint returns a result per item instead of failing the whole batch.” |
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.