Một request đi qua gateway. Service phía sau gọi tiếp sang service thứ hai bằng gRPC, và hôm nay service thứ hai chạy chậm. Gateway hết kiên nhẫn trước, trả 504 cho client, client bỏ đi. Nhưng phía sau gateway, câu query vẫn chạy, dữ liệu vẫn được ghi, có khi service thứ ba vẫn bị gọi. Tất cả chỉ để phục vụ một client đã đi mất.
Không có gì crash, dòng code nào cũng làm đúng việc được giao. Trước khi bàn chuyện REST, gRPC hay Kafka, nên hiểu cho kỹ kiểu lỗi này, vì giao thức nào cũng có một phiên bản của nó.
Vì sao timeout không dừng được công việc?
Đây là cách sửa sai hay gặp nhất, rút gọn hết mức. Lưu thành race.mjs rồi chạy node race.mjs:
const slowLookup = () =>
new Promise((resolve) =>
setTimeout(() => {
console.log('lookup finished; nobody is listening');
resolve('stock: 12');
}, 3_000),
);
const giveUpAfter = (ms) =>
new Promise((_, reject) =>
setTimeout(() => reject(new Error(`timed out after ${ms} ms`)), ms),
);
try {
console.log(await Promise.race([slowLookup(), giveUpAfter(1_000)]));
} catch (error) {
console.log(error.message);
}Chương trình in ra timed out after 1000 ms, hai giây sau lại in tiếp lookup finished; nobody is listening. Promise.race chỉ quyết định bạn nhìn thấy kết quả nào, nó không dừng được promise thua cuộc. Timeout là quyết định của người chờ. Việc chỉ dừng khi có ai đó báo cho người đang làm.
Với gRPC, mặc định còn tệ hơn. Hướng dẫn về deadline của gRPC nói thẳng: không đặt deadline thì client có thể chờ phản hồi gần như mãi mãi. Trong khi đó gateway có đồng hồ riêng. Kong, gateway của nền tảng này, mặc định chờ upstream 60 giây. Nếu timeout xảy ra lúc kết nối hoặc lúc chờ response header, nó còn retry các method idempotent (GET, PUT, DELETE) tối đa năm lần (tài liệu proxy của Kong). Tức là lớp ngoài bỏ cuộc sau một phút và có thể gửi lại request, còn lớp trong không có deadline nên chẳng bao giờ bỏ cuộc.
Thử hình dung một tòa soạn lúc sáu giờ chiều. Phóng viên gọi cho một nguồn tin để xin câu trích dẫn, nguồn tin bảo "để tôi lục hồ sơ đã". Đến giờ lên khuôn, biên tập viên cắt đoạn đó và báo vẫn đi in. Không ai gọi lại báo cho nguồn tin, thế là người ta ngồi lục hồ sơ cả buổi tối cho một bài báo đã phát hành.
Microservice nói chuyện với nhau theo những cách nào?
Tòa soạn có ba kiểu trò chuyện, mỗi kiểu ứng với một giao thức.
Tờ báo đã in là thứ công khai, khuôn dạng cố định. Phát hành rồi thì không thu hồi được, chỉ có thể đăng đính chính ở số sau. Đó là public API: REST/JSON đi qua một gateway duy nhất. Một app mobile phát hành từ mấy tháng trước giống người đọc đang cầm số báo cũ: nó vẫn gọi API theo đúng hình dạng của ngày app ra mắt.
Cuộc gọi trước giờ lên khuôn là câu hỏi mà người hỏi phải có câu trả lời mới làm tiếp được. Hai bên phải cùng cầm máy một lúc, và cuộc gọi có giới hạn thời gian. Đó là gRPC giữa các service.
Bản tin thông tấn báo một chuyện đã xảy ra. Hãng thông tấn không đứng chờ xem ai đọc, tòa soạn nào nhận tin theo nhịp của tòa soạn đó. Thỉnh thoảng một bản tin đến hai lần. Muốn đính chính thì phát bản tin mới, không ai sửa bản tin cũ. Đó là một event trên Kafka.
Còn một thứ thứ tư, quan trọng hơn cả ba: kho tư liệu. Trước khi nhấc máy gọi ai, phóng viên giỏi lật kho tư liệu trước. Nếu con số hôm qua là đủ dùng thì khỏi phải gọi. Với một service, kho tư liệu là local projection: một bảng được dựng từ event của các service khác.
REST, gRPC hay Kafka: chọn thế nào?
Tôi hỏi ba câu, đúng thứ tự này, gặp câu trả lời "có" đầu tiên thì dừng:
- Đầu bên kia nằm ngoài nền tảng? Dùng REST qua gateway. Trình duyệt, app mobile hay hệ thống đối tác không bao giờ được cấp cổng gRPC hay topic Kafka.
- Một service vừa thay đổi state của chính nó? Service đó publish event sau khi thay đổi đã commit. Không consumer nào phủ quyết được một chuyện đã xảy ra.
- Bên gọi có cần câu trả lời mới làm tiếp an toàn được không, và dùng bản sao cũ ở local có nguy hiểm không? Chỉ khi cả hai đều đúng mới gọi gRPC. Kho tư liệu đủ dùng thì đọc kho tư liệu.
Câu thứ ba quan trọng nhất. Lời gọi đồng bộ nào cũng đòi hai service cùng sống một lúc, nên quy tắc của nền tảng là: một command chỉ gọi sang service khác khi nó không thể làm tiếp an toàn bằng local projection.
Với một loại đơn hàng cụ thể, lúc tạo đơn, service order hỏi inventory qua gRPC xem ngay lúc này có đủ hàng cho các dòng trong đơn không, với deadline 2 giây. Một projection trễ vài giây có thể dẫn tới bán vượt tồn kho. Nếu inventory không trả lời, việc tạo đơn fail closed với 503 thay vì đoán mò. Cái giá là có thật: inventory sập thì tạo loại đơn đó cũng sập theo.
Số dư điểm tích lũy của khách hàng thì ngược lại. Nó được đọc từ local projection, và response nói rõ dữ liệu cũ đến mức nào: có timestamp asOf cùng cờ freshness, chuyển sang STALE sau 60 giây. Đó chính là kho tư liệu, với ngày tháng in ngay trên mẩu báo cắt.
API gateway nên giữ những việc gì?
Gateway giữ những gì đúng với mọi request, bất kể service nào xử lý: routing, TLS termination, CORS, rate limit và correlation ID. Nó còn xóa mọi header mà client có thể dùng để khai man danh tính. Đây là khối plugin global trong file cấu hình declarative của Kong, đã rút gọn:
plugins:
- name: correlation-id
config:
header_name: X-Correlation-ID
generator: uuid
- name: request-transformer
config:
remove:
headers:
- X-User-Id
- X-Session-Id
- X-Roles
- X-Permissions
- X-Scopes
- X-Consumer-IDNếu có service nào đọc X-Roles thì header đó buộc phải đến từ bên trong; xóa nó ngay ở cửa ngoài khiến điều đó luôn đúng, không phụ thuộc vào việc ai nhớ hay quên. Mọi thứ còn lại thuộc về service sở hữu dữ liệu: validate nghiệp vụ, chính sách phân quyền, lưu trữ và nội dung response.
Xác thực ở gateway, phân quyền ở service
Trên các route cần bảo vệ, plugin JWT của Kong từ chối token bị thiếu, sai chữ ký hoặc hết hạn. Đó là khâu soát thẻ nhà báo ở cửa ra vào, nhưng có thẻ nhà báo không có nghĩa là được đọc hồ sơ của tổng biên tập.
Phép kiểm tra ở gateway là stateless: nó không thể biết phiên đăng nhập vừa bị thu hồi một phút trước. Vì vậy mỗi service gửi bearer token sang service auth qua gRPC. Auth kiểm tra bản ghi session, trạng thái tài khoản, xem role trong token còn khớp không, rồi trả về principal đã xác minh. Lại là câu hỏi thứ ba, vì danh tính cũ thì không an toàn. Cái giá: auth sập thì mọi route được bảo vệ cũng sập.
Bên trong service, một guard lo phần còn lại. Route nào quên khai báo public thì mặc định là "phải đăng nhập", không bao giờ là "mở cửa", và mã quyền dạng <SERVICE>:<RESOURCE>_<ACTION> do chính service sở hữu tài nguyên kiểm tra.
Vì sao gateway thôi dịch JSON sang gRPC?
Thiết kế đầu tiên dùng plugin grpc-gateway của Kong để chuyển JSON từ trình duyệt thành lời gọi gRPC, dựa trên annotation trong file .proto. Nó sống được bốn ngày. Muốn nó chạy cho đàng hoàng phải viết thêm hai plugin Lua tự chế: một cái chặn field JSON lạ, một cái đổi object null-value của protobuf về lại null bình thường. Mỗi điểm kỳ quặc trong cách protobuf ánh xạ JSON đều thành điểm kỳ quặc của public API.
Phương án thay thế đơn giản hơn. Mỗi service trong mười ba service khởi động một hybrid application của NestJS: một listener HTTP và một listener gRPC trong cùng process, cùng gọi xuống một tầng application. Kong chỉ việc proxy HTTP. Bớt được một lớp dịch, và public contract là JSON viết cho client, chứ không phải sinh ra từ schema nội bộ.
Một định dạng lỗi cho cả hai giao thức
Mọi lỗi public đều được thiết kế để dùng chung một envelope: { statusCode, errorCode, message, details?, timestamp, requestId }. Mấu chốt là một kiểu lỗi dùng chung, không thuộc về giao thức nào. Use case ném ra lỗi kèm một kind, các kind cố ý chép theo status code của gRPC, và mỗi biên giới tự dịch sang ngôn ngữ của mình:
| Loại lỗi | gRPC status | HTTP status |
|---|---|---|
NOT_FOUND |
NOT_FOUND |
404 |
FAILED_PRECONDITION |
FAILED_PRECONDITION |
422 |
ABORTED |
ABORTED |
409 |
DEADLINE_EXCEEDED |
DEADLINE_EXCEEDED |
504 |
Message gốc của framework, validator, ORM hay gRPC không bao giờ lọt ra tới client. Chỗ chưa khớp còn lại: một service vẫn để filter mặc định của framework trả lời một số lỗi HTTP, nên client có thể gặp hai định dạng khác nhau. Đã ghi vào tài liệu, nhưng nhìn từ phía client thì vẫn là bug.
Gọi gRPC giữa các service thế nào cho an toàn?
Mọi lời gọi nội bộ đều đi qua một helper nhỏ, lo việc ký metadata và tính deadline tuyệt đối. Đây là một client đã rút gọn, package scope đã đổi tên:
import { ServiceUnavailableException } from '@nestjs/common';
import { invokeSignedGrpcAsync } from '@platform/common';
import {
CHECK_COVERAGE_DEADLINE_MS,
CHECK_COVERAGE_METHOD,
checkCoverageRequestSchema,
checkCoverageResponseSchema,
hashCheckCoverageRequest,
} from '@platform/contracts';
const COVERAGE_UNAVAILABLE = 'INVENTORY_COVERAGE_UNAVAILABLE';
async coveredItemIds(itemIds: readonly string[]): Promise<readonly string[]> {
const request = checkCoverageRequestSchema.parse({ itemIds });
try {
const response = await invokeSignedGrpcAsync(
{
serviceId: this.config.serviceId,
method: CHECK_COVERAGE_METHOD,
payloadDigest: hashCheckCoverageRequest(request),
sharedSecret: this.config.inventorySharedSecret,
deadlineMs: CHECK_COVERAGE_DEADLINE_MS,
},
({ metadata, deadline }) => this.invoke(request, metadata, deadline),
);
const parsed = checkCoverageResponseSchema.parse(response);
const askedFor = new Set(request.itemIds);
if (parsed.coveredItemIds.some((id) => !askedFor.has(id))) {
throw new ServiceUnavailableException(COVERAGE_UNAVAILABLE);
}
return parsed.coveredItemIds;
} catch {
throw new ServiceUnavailableException(COVERAGE_UNAVAILABLE);
}
}Có bốn chi tiết làm nên chuyện.
Đưa deadline vào contract
CHECK_COVERAGE_DEADLINE_MS nằm trong package contracts dùng chung, ngay cạnh tên method. (Bài về Nx monorepo có giải thích package này.) Đặt ở đó thì câu hỏi "bao lâu là quá lâu" trở thành một phần của contract, chứ không phải con số mỗi client tự đoán. Trong codebase này, các giá trị nằm trong khoảng từ 500 ms đến 3 giây.
Để ý chiều của các con số: gateway chờ 60 giây, lời gọi nội bộ bỏ cuộc sau 0,5 đến 3 giây. Ngân sách thời gian co lại khi đi vào trong; lời gọi bên trong mà sống lâu hơn bên gọi nó thì chính là con bug ở đầu bài. Chưa phải deadline nào cũng đã chuyển vào package, vài cái vẫn nằm riêng trong một client.
Deadline dừng việc chờ, không dừng việc làm
Phía client, invoke bọc lời gọi trong một Observable. Nếu subscriber rời đi trước khi lời gọi kết thúc, phần teardown gọi call.cancel(). Deadline cũng đi theo request, nên khi quá hạn, lời gọi phía server bị cancel.
Nhưng đọc kỹ hướng dẫn của gRPC sẽ thấy: dừng công việc là trách nhiệm của ứng dụng phía server. grpc-js có đặt call.cancelled và phát event 'cancelled', nhưng handler NestJS nào không kiểm tra thì vẫn chạy tiếp các câu query như thường. Hiện chưa handler nào ở đây kiểm tra. Cách sửa thì rẻ:
import { status, type Metadata, type ServerUnaryCall } from '@grpc/grpc-js';
import { GrpcMethod, RpcException } from '@nestjs/microservices';
@GrpcMethod('InventoryService', 'CheckCoverage')
async checkCoverage(
request: CheckCoverageRequest,
_metadata: Metadata,
call: ServerUnaryCall<CheckCoverageRequest, CheckCoverageResponse>,
): Promise<CheckCoverageResponse> {
const levels = await this.stock.loadLevels(request.itemIds);
if (call.cancelled) {
throw new RpcException({ code: status.CANCELLED, message: 'caller gave up' });
}
return this.coverage.evaluate(levels, request.itemIds);
}Phép kiểm tra này không cắt ngang được câu query đang chạy dở, nhưng nó chặn handler bước sang bước kế tiếp. Còn từng câu query thì đã có statement_timeout của Postgres giới hạn.
Ghi dữ liệu thì khó hơn. Giả sử deadline hết ngay sau khi commit: bên gọi nhận DEADLINE_EXCEEDED cho một việc thực ra đã xong. Nó không phân biệt được "chưa từng xảy ra" với "đã xảy ra sau khi mình bỏ đi". Đó đúng là lý do idempotency key tồn tại.
Ký danh tính bên gọi, nhưng vẫn phải mã hóa kênh truyền
Helper gắn vào metadata service ID của bên gọi, tên method, timestamp, một nonce, request ID và correlation ID, cùng digest SHA-256 của payload, rồi ký tất cả bằng HMAC-SHA256 với một secret mà hai service dùng chung. Bên nhận kiểm tra bên gọi và method, từ chối timestamp lệch quá 60 giây, so chữ ký trong constant time; service nào có bảng nonce thì từ chối luôn nonce đã gặp trong hai phút gần nhất. Như vậy là chặn được lời gọi giả mạo và lời gọi bị replay.
Nhưng nó không chặn được chuyện bị đọc lén. Ký không phải là mã hóa, và trong bản prototype này, các kênh gRPC trong mạng private vẫn là plaintext. TLS đã nằm trong danh sách việc cần làm, nhưng chưa xong.
Kiểm tra cả câu trả lời
Service bên kia là một codebase khác, deploy vào một ngày khác. Client parse response bằng schema dùng chung và kiểm tra rằng mọi ID trả về đều là ID nó đã hỏi. Lỗi gì cũng quy về cùng một 503 rõ ràng, còn retry thì có giới hạn và chỉ áp dụng cho thao tác an toàn hoặc idempotent.
Khi nào service nên publish event lên Kafka?
Chỉ sau khi use case sở hữu dữ liệu đã commit thay đổi và quyết định công bố nó. Decision record viết rõ: có thư viện, có topic hay có schema không chứng minh được một lệnh ghi HTTP thật sự phát event; chỉ có producer và consumer được trace từ đầu đến cuối mới chứng minh được.
Thứ khiến "sau commit" thành sự thật là transactional outbox: event là một dòng được ghi trong cùng transaction với thay đổi state, rồi một relay publish nó sau. Delivery là at-least-once, nên theo quy ước, consumer ghi mỗi event vào bảng inbox trong cùng transaction với thay đổi của chính nó, và chỉ commit Kafka offset sau bước đó.
Topic được đặt tên theo mẫu platform.<service>.<aggregate>.<past-tense-event>.v1, trong đó platform thay cho prefix thật. Event nào cũng mang chung một envelope:
{
"eventId": "0190f3a2-7c1e-7d4b-9a2f-3b8c6d1e5f70",
"eventType": "platform.inventory.receipt.confirmed.v1",
"schemaVersion": 1,
"aggregateId": "0190f3a1-2b6d-7e0a-8c4f-9d2e1a7b3c58",
"aggregateVersion": 4,
"occurredAt": "2026-07-20T08:15:30.000Z",
"producer": "inventory",
"correlationId": "0190f3a1-f0a3-7b21-a6d9-4e8c2b1f7a05",
"causationId": "0190f3a1-e9b7-7c02-b1e4-7f3a5d2c8e91",
"payload": { "status": "CONFIRMED" }
}Bốn quy tắc giữ cho bản tin đáng tin:
- Key theo aggregate ID. Kafka chỉ đảm bảo thứ tự trong phạm vi một partition. Hiện mỗi topic có đúng một partition trên một broker duy nhất. Thứ tự vì thế có sẵn, nhưng mỗi topic chỉ có một consumer hoạt động trong mỗi group. Key theo aggregate giữ thứ tự đúng vào cái ngày có người thêm partition, còn
aggregateVersionvẫn giúp consumer nhận ra event đã cũ. - Trong một version chỉ được thêm, không được sửa. Thêm một field optional mới thì được. Đổi tên field nghĩa là phải mở topic
.v2và có một khoảng thời gian chuyển đổi. - Retry có giới hạn, rồi chuyển vào dead-letter topic, kèm cảnh báo và một công cụ replay có phân quyền.
- Giữ sợi chỉ xuyên suốt.
correlationIdđi theo một request của người dùng qua gateway, qua các lời gọi gRPC và qua mọi event mà request đó gây ra.causationIdchỉ ra nguyên nhân trực tiếp. Field tùy chọnpayloadHashgiúp phát hiện cùng mộteventIdnhưng đến với nội dung khác.
Mỗi kiểu giao tiếp hỏng theo cách nào?
| Tầng | Kiểu hỏng đặc trưng | Thứ khoanh vùng nó |
|---|---|---|
| Gateway | Logic nghiệp vụ lén chui vào, mỗi lần một check nhỏ | Danh sách thành văn những gì gateway được giữ |
| REST contract | Một thay đổi làm hỏng app phát hành từ mấy tháng trước | Chỉ thêm, không sửa; version rõ ràng |
| gRPC | Lời gọi treo, retry dồn dập, sự cố lan sang bên gọi | Deadline, cancellation, retry có giới hạn |
| Kafka | Mất event, trùng lặp, sai thứ tự, poison message | Outbox, inbox, partition theo key, dead letter |
gRPC hỏng vì dính chặt vào nhau: ba lời gọi đồng bộ nối tiếp đòi bốn service cùng sống một lúc, giống một bài báo chỉ lên trang được khi cả ba nguồn tin đều nghe máy. Kafka hỏng trong im lặng: kiểu dual write sẽ đánh rơi bản tin mỗi khi process chết giữa lúc ghi database và lúc gửi lên broker, và chẳng ai biết cho tới khi một projection ra số sai.
Ba kiểu giao tiếp tốn những gì?
Ba giao thức nghĩa là ba thứ phải vận hành, ba loại contract và ba loại test. gRPC cần chính sách cho deadline, retry, TLS và trace context; Kafka cần partitioning, retention, replay, monitoring và consumer idempotent. Decision record cố ý không khẳng định cái nào nhanh hơn hay đáng tin hơn một cách chung chung.
Bằng chứng cũng quan trọng không kém. Mới chỉ có luồng auth là có một lần chạy end-to-end được ghi lại (HTTP qua gateway, cộng lời gọi gRPC kiểm tra readiness và lấy profile). Retry xuyên service, dead-letter và xử lý trùng lặp đã có code nhưng chưa được kiểm chứng, và tôi thà nói thẳng ra còn hơn để bạn tưởng đó là đảm bảo đã được test.
Với ba service và một team, ba giao thức có lẽ là quá nhiều: REST giữa các service cộng một job queue chạy trên database là đủ đi khá xa. Tách ra chỉ đáng khi các service thay đổi với tốc độ khác nhau và chi phí phối hợp release cao hơn chi phí vận hành một broker. Nếu chưa chỉ ra được consumer nào cần nghe về một thay đổi mà producer không cần biết đến sự tồn tại của nó, thì bạn chưa cần event.
Nếu làm lại, tôi sẽ làm khác gì?
- Kiểm tra cancellation phía server ngay từ handler đầu tiên. Deadline phía client mới là một nửa tính năng; phép kiểm tra cancellation và statement timeout phải có sẵn trong template service.
- Sinh type cho client từ file
.proto. Interface gRPC viết tay chính là chỗ hai bên bắt đầu lệch nhau. - Truyền correlation ID qua mọi chặng. Trong bảy chỗ gọi helper, chỉ một chỗ truyền vào; những chỗ còn lại tự sinh ID mới và cắt đứt trace ngay ở lời gọi nội bộ đầu tiên.
- Lint tên topic trong CI. Tên event đang trộn
snake_casevớikebab-case, còn dead-letter topic dùng tới hai kiểu hậu tố. - Xóa các điểm bất đối xứng. Hai integration chỉ đọc vẫn gọi endpoint HTTP của service khác mà không ký. Đã ghi là cố ý, nhưng vẫn là hai mô hình bảo mật chạy song song.
- Sửa decision record trong cùng commit với cấu hình. Decision record của tôi vẫn ghi "gRPC transcoding" là việc của gateway. Khi kế hoạch và cấu hình đang chạy nói hai kiểu, hãy tin cấu hình rồi sửa kế hoạch, trước khi người đọc sau thiết kế dựa trên một gateway không còn tồn tại.
Tóm tắt
- Timeout dừng việc chờ, không dừng việc làm. Lời gọi gRPC nào cũng cần deadline, cancel khi teardown, và server phải kiểm tra cancellation.
- Hỏi theo thứ tự: đầu bên kia nằm ngoài nền tảng (REST)? Service vừa đổi state của chính nó (Kafka)? Có thật sự cần câu trả lời mới (gRPC)? Không câu nào đúng thì đọc local projection.
- Ngân sách thời gian co lại khi đi vào trong, nên deadline bên trong phải ngắn hơn timeout bên ngoài.
- Gateway lo xác thực và xóa header có thể giả mạo. Service sở hữu tài nguyên mới là bên phân quyền.
- Client chỉ thấy JSON thuần, không bao giờ thấy proto hay topic.
- Event đi ra sau commit, qua outbox, key theo aggregate, tới những consumer luôn sẵn sàng gặp bản trùng.
Bài tiếp theo trong series: database per service và saga, khi một thao tác của người dùng phải đổi state ở nhiều service và không transaction nào đủ lớn để ôm trọn.