Một service NestJS build thành công. Unit test xanh. Bộ end-to-end khởi động nó lên và mọi check đều pass. Rồi container chạy, và chết ngay trước khi kịp in dòng log đầu tiên:
Error: Cannot find module '@platform/common'Giữa lần chạy xanh và lần chạy đỏ, code không đổi một dòng nào. Chỉ có thư mục chạy là khác.
Bug thứ hai của monorepo thì lặng lẽ hơn. Một commit sửa gRPC contract, sửa luôn server implement nó và cả hai service đang gọi nó. Test pass hết, vì test nào cũng compile cả bốn với cùng một phiên bản contract. Rồi các service được deploy lần lượt, và trong một khoảng thời gian, caller cũ nói chuyện với server mới. Chưa test nào từng chạy cặp đó.
Cả hai bug đều chung một gốc: commit thì atomic, còn mười ba lần deploy thì không. Bài này kể cách một nền tảng gồm mười ba service NestJS và bốn thư viện dùng chung cùng nằm trong một Nx workspace mà không để bug nào lặng lẽ lọt qua, và cái giá phải trả cho việc đó. Hệ thống vẫn là prototype, nên đây là thiết kế và các bước kiểm tra có trong repo, không phải số liệu production.
Vì sao để 13 microservice NestJS trong một Nx monorepo?
Lúc chạy, các service này độc lập: mỗi process tự khởi động, tự scale, tự sập. Nhưng lúc thiết kế thì không. Chúng dùng chung ba thứ buộc phải khớp nhau tuyệt đối:
- Contract. File
.protocho gRPC, Zod schema và event envelope có version cho Kafka. - Code nền tảng. Kiểu lỗi, cursor phân trang, idempotency key, correlation id, graceful shutdown.
- Tooling. Một lockfile, một TypeScript base config, một lint config, một phiên bản Node.
Nếu mỗi service một repo, mỗi thứ dùng chung thành một package phải publish, và mỗi thay đổi thành một lần release cộng mười ba lần bump version. Thông tin quý nhất, sửa field này thì ai gãy?, bị rải ra mười ba repo. Trong một workspace, thay đổi contract và mọi dòng code dùng nó nằm chung một diff.
Hình ảnh tôi hay dùng là một tòa chung cư. Các căn hộ dùng chung móng, khung nhà và đường ống đứng dẫn nước giữa các tầng; xây những thứ đó một lần chính là lý do tòa nhà tồn tại. Nhưng căn nào cũng có cửa riêng và đồng hồ điện nước riêng. Không ai phải đi xuyên phòng khách nhà hàng xóm để về nhà, và hóa đơn nhà bạn không phụ thuộc vào căn bên cạnh.
Monorepo cho microservice cũng vậy: cố ý dùng chung phần móng, cố ý tách riêng cửa và đồng hồ. Hai bug ở trên chính là một căn hộ lén câu điện từ ổ cắm ngoài hành lang, và một đường ống đứng bị thay trong lúc các tầng trên vẫn có người ở.
apps/ chứa gì, libs/ chứa gì?
apps/
order-service/ project.json, package.json, Dockerfile, webpack config
order-service-e2e/ khởi động service thật; phụ thuộc ngầm vào nó
(thêm 12 cặp service + e2e)
libs/
contracts/ file .proto, Zod schema, event contract, chia theo service sở hữu
common/ primitive mà nhiều service cùng dùng
config/ parse và validate biến môi trường
object-storage/ port lưu trữ object và adapter S3 (hiện chỉ một service dùng)Mỗi service khai báo các thư viện nó dùng dưới dạng dependency của workspace:
{
"name": "order-service",
"dependencies": {
"@platform/common": "workspace:*",
"@platform/config": "workspace:*",
"@platform/contracts": "workspace:*"
}
}workspace:* bảo pnpm link thẳng tới thư mục cục bộ thay vì tải một bản đã publish. Cái link đó chính là đường ống chung: sửa contracts là type checker chỉ ra ngay consumer nào gãy, trong cùng một commit.
Khu vực chung thì phải có nội quy. Trong contracts, service nào chỉ sửa file của service đó (proto/<service>/v1/ và một module TypeScript). Code chỉ được vào common khi có hơn một service cần đến và nó không chứa business rule.
Module boundary của Nx chặn service import lẫn nhau thế nào?
Nx dựng project graph từ các import và dependency trong package.json. Lint rule @nx/enforce-module-boundaries đối chiếu từng import với graph đó. Kể cả khi chưa cấu hình gì thêm, nó đã chặn ba thứ: import một application, import chọc thẳng vào project khác bằng đường dẫn tương đối, và dependency vòng giữa các project.
Đó chính là những cánh cửa. Service là application: bạn không import được nó bằng tên package, cũng không chọc vào được bằng đường dẫn tương đối. Nên đoạn này fail lint:
// apps/reporting-service/src/app/totals.ts
// lint error: "Projects cannot be imported by a relative or absolute path"
import { sumOrderLines } from '../../../order-service/src/app/order-lines';Nếu reporting cần logic đó, hoặc nó được chuyển vào một thư viện dùng chung có tên và có lý do, hoặc reporting gọi qua mạng. Hiện chưa thư mục service nào import service khác, nên cửa vẫn giữ được.
Vì sao tag wildcard không chặn được gì
Tag là lớp thứ hai. Service mang scope:<tên> và type:service; thư viện mang scope:shared cùng type:foundation, type:contract hoặc type:infrastructure. Trong depConstraints, bạn khai báo tag nào được phụ thuộc vào tag nào. Còn đây là thứ workspace thực sự khai báo:
depConstraints: [{ sourceTag: '*', onlyDependOnLibsWithTags: ['*'] }],Project nào cũng được phụ thuộc vào thư viện nào. Tag giống tấm bảng tên gắn trên cửa nhưng không có ổ khóa. Một service có danh sách tag rỗng, không project end-to-end nào có tag, và dưới cái wildcard đó chẳng ai để ý.
Cũng vì vậy mà sửa về sau khó hơn tưởng. Ngay khi có một constraint thật, project nào có tag không khớp với constraint nào sẽ bị Nx cấm phụ thuộc vào mọi thư viện. Thế là toàn bộ project chưa gắn tag cùng fail lint trong một ngày.
Vì sao sửa một thư viện dùng chung lại kéo theo build lại tất cả?
nx affected lấy hai commit, ánh xạ từng file thay đổi về project sở hữu nó, rồi đi ngược graph lên mọi project phụ thuộc vào các project đó. CI dùng nó cho lint và type check:
pnpm nx affected -t lint --base="$NX_BASE_SHA" --head="$NX_HEAD_SHA" --parallel=2
pnpm nx affected -t typecheck --base="$NX_BASE_SHA" --head="$NX_HEAD_SHA" --parallel=6Bạn có thể hỏi thẳng graph xem một thay đổi chạm tới đâu:
pnpm nx show projects --affected --files=libs/common/src/index.tsVới common, câu trả lời là tất cả. Cả mười ba service đều phụ thuộc common, config và contracts, còn mỗi project end-to-end lại phụ thuộc vào service của nó. Không phải Nx lười, mà graph đang nói thật. Sửa móng thì căn nào cũng phải kiểm tra lại. Graph hẹp tới đâu thì affected chọn lọc được tới đó, và một thư viện dùng chung phình to sẽ biến mọi thay đổi nhỏ thành việc sửa móng.
Cache chỉ biết những input bạn khai báo
Trước khi chạy một task, Nx hash các input của nó: source file, cấu hình, version của dependency, tham số. Nếu hash trùng với một lần chạy trước, Nx phát lại output đã lưu. Cache là một lời hứa, cùng input thì cùng output, và lời hứa đó chỉ đáng tin bằng danh sách input.
Webpack config của mỗi service copy các file .proto nó load vào bundle, còn build của mỗi service liệt kê file proto làm input, từng file một (trích đoạn):
"inputs": [
"default",
"{workspaceRoot}/prisma/order/**/*",
"{workspaceRoot}/libs/contracts/proto/order/v1/order.proto",
"{workspaceRoot}/libs/contracts/proto/item/v1/item.proto"
]Hai danh sách viết tay cho cùng một sự thật. Khi so hai danh sách, tôi thấy bốn service ghi tên file proto trong webpack asset mà build input không hề nhắc tới: tổng cộng bảy file, riêng order service có ba, trong đó một file được load lúc runtime để gọi sang service khác. Sửa file đó thì hash của build không đổi, và một bản build lấy từ cache sẽ mang theo contract của hôm qua.
Phạm vi ảnh hưởng hiện còn nhỏ: CI bắt đầu mỗi job với cache Nx rỗng, còn .nx bị loại khỏi Docker build context, nên chỉ máy của developer là có thể dính. Nó sẽ thành bug của CI vào ngày có người bật remote cache. Tôi tìm ra lỗ hổng này nhờ đọc code, chứ chưa phải vì đã dính lỗi.
Cách sửa sai là dặn nhau "cẩn thận hơn". Cách đúng: hoặc khai báo cả thư mục {workspaceRoot}/libs/contracts/proto/**/* như hai service đã làm (build lại nhiều hơn nhưng không bao giờ sai), hoặc sinh cả hai danh sách từ một manifest.
Từng service NestJS có deploy độc lập được không?
Quay lại bug đầu tiên. Node resolve require('@platform/common') bằng cách đi ngược lên từ thư mục của file đang require, ghé qua từng thư mục node_modules trên đường. Trong workspace, apps/order-service/node_modules/@platform/common là một symlink của pnpm trỏ vào libs/common, nên lần nào cũng tìm thấy. Chỉ copy dist/ vào image thì đi hết đường cũng chẳng thấy gì.
Có hai cách sửa nghe rất hợp lý, và cả hai đều sai. Copy cả workspace vào image thì boot được, nhưng image chở theo code của mười ba service và chẳng chứng minh được gì. Thêm tay package bị thiếu vào image thì bạn vừa mở ra một danh sách sẽ lệch ngay lần refactor đầu tiên.
Thay vào đó, quy tắc là:
Build của một service phải cho ra một artifact chạy được khi xung quanh không có workspace nào.
Nói theo kiểu chung cư: căn nào cũng phải chạy bằng đồng hồ của chính nó. build compile đúng một service bằng webpack, giữ các import từ node_modules thành lời gọi require lúc runtime. Sau đó prune chạy hai executor của Nx:
"prune-lockfile": { "executor": "@nx/js:prune-lockfile", "dependsOn": ["build"] },
"copy-workspace-modules": { "executor": "@nx/js:copy-workspace-modules", "dependsOn": ["build"] },
"prune": { "executor": "nx:noop", "dependsOn": ["prune-lockfile", "copy-workspace-modules"] }prune-lockfile ghi package.json và pnpm-lock.yaml vào dist/, chỉ chứa dependency của service này. copy-workspace-modules copy các thư viện dùng chung đã build vào dist/workspace_modules/, để artifact mang bản sao của riêng nó thay vì symlink ngược về libs/.
Sau đó phải có thứ gì đó chứng minh, và đây là bước phần lớn các setup bỏ qua. Một job CI copy từng artifact đã prune ra một thư mục tạm bên ngoài workspace, chạy pnpm install --prod --frozen-lockfile theo lockfile của chính artifact, rồi boot nó với một guard được preload. Service chỉ pass khi liveness check trả lời.
Artifact đã nằm ngoài workspace rồi, sao còn cần guard? Vì thư mục tạm vẫn ở trên cùng một máy, và workspace vẫn còn nguyên trên đĩa. Một đường dẫn tuyệt đối bị gắn cứng vào bundle lúc build, hay một symlink trỏ ngược về libs/, vẫn resolve được, và bài kiểm tra pass vì một lý do sai. Guard biến "tình cờ chạy được" thành "không thể với ngược về workspace". Bản rút gọn dưới đây bỏ vào project Node nào cũng chạy:
// guard.cjs: chạy bằng node --require ./guard.cjs main.js
const Module = require('node:module');
const path = require('node:path');
const artifactRoot = path.resolve(process.env.ARTIFACT_ROOT ?? process.cwd());
const workspaceRoot = path.resolve(process.env.WORKSPACE_ROOT ?? process.cwd());
function isInside(parent, candidate) {
const relative = path.relative(parent, candidate);
return (
relative === '' ||
(relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
);
}
const resolveFilename = Module._resolveFilename;
Module._resolveFilename = function guardedResolve(request, ...rest) {
const resolved = resolveFilename.call(this, request, ...rest);
const escapes = isInside(workspaceRoot, resolved) && !isInside(artifactRoot, resolved);
if (path.isAbsolute(resolved) && escapes) {
throw new Error(`${request} resolved outside the artifact: ${resolved}`);
}
return resolved;
};Module._resolveFilename là API nội bộ, không có tài liệu: dùng cho một bước check trong CI thì ổn, còn ship trong service thì tôi không làm. Một script khác kiểm tra mỗi artifact có đủ file proto và runtime dependency cần thiết hay không.
Phần build image lặp lại đúng công thức đó. Một Dockerfile có tham số tạo ra mười hai trên mười ba runtime image và cả mười ba migration image (đã lược phần cài corepack và cache mount):
FROM node:24-bookworm AS build
WORKDIR /workspace
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
# Layer này chỉ phụ thuộc lockfile, nên sửa source không phải tải lại package.
RUN pnpm fetch --frozen-lockfile
COPY . .
RUN pnpm install --offline --frozen-lockfile
ARG SERVICE_NAME
RUN pnpm nx run-many -t build -p common config contracts \
&& pnpm nx run "${SERVICE_NAME}:build" \
&& pnpm nx run "${SERVICE_NAME}:prune"
FROM node:24-bookworm-slim AS runtime
WORKDIR /app
RUN chown node:node /app
USER node
ARG SERVICE_NAME
COPY --from=build --chown=node:node /workspace/apps/${SERVICE_NAME}/dist/ ./
RUN pnpm install --prod --frozen-lockfile
CMD ["node", "main.js"]Migration image chỉ nhận Prisma schema và migration của đúng service đó, nên không thể đụng vào database của service khác. Image chạy ở đâu là một quyết định riêng: Docker Compose hay Kubernetes cho 13 microservice.
Đổi gRPC contract thế nào khi deploy không atomic?
Bài kiểm tra đồng hồ chứng minh từng căn chạy độc lập. Nó không nói gì về hai căn ở hai phiên bản khác nhau cùng dùng một đường ống. Compiler chỉ thấy một phiên bản của mỗi contract; production thấy hai, suốt thời gian rollout. Vì vậy quy tắc có nửa thứ hai:
Mọi thay đổi contract phải chạy được với phiên bản đang deploy của từng service ở đầu bên kia.
Quy ước event nói thẳng điều này: trong cùng một version chỉ được thêm theo kiểu tương thích ngược; thay đổi phá vỡ thì phải lên version mới và có giai đoạn chuyển tiếp. Đó là lý do proto package và Kafka topic đều mang v1. Khi đó, một thay đổi phá vỡ tốn ba lần deploy chứ không phải một commit:
- Expand. Thêm field mới bên cạnh field cũ. Server nhận cả hai.
- Migrate. Caller chuyển sang field mới, mỗi lần deploy một service.
- Contract. Khi không còn caller nào đang chạy gửi field cũ, xóa nó đi và reserve cả số lẫn tên.
Dưới đây là một ví dụ có thật trong thư viện contracts (đã đổi tên). Một field boolean được thay bằng enum, còn boolean cũ vẫn được giữ lại:
enum RecomputeMode {
RECOMPUTE_MODE_UNSPECIFIED = 0;
RECOMPUTE_MODE_USE_CURRENT = 1;
RECOMPUTE_MODE_RECOMPUTE = 2;
}
message RecomputeScoreRequest {
string subject_id = 1;
string period = 2;
bool force_recompute = 3 [deprecated = true];
string idempotency_key = 4;
RecomputeMode recompute_mode = 5;
// Bước 3, khi không còn caller nào gửi, field 3 được thay bằng:
// reserved 3;
// reserved "force_recompute";
}Cái bẫy mà tôi chỉ thấy khi đọc handler: nó chỉ đọc recompute_mode. Một caller cũ vẫn gửi force_recompute = true sẽ nhận về reply hợp lệ, nhưng yêu cầu của nó bị lờ đi và giá trị hiện tại được dùng. Không caller nào đang chạy còn gửi field cũ, nên hôm nay chưa có gì gãy. Nhưng "vẫn còn trên wire" và "vẫn được tôn trọng" là hai lời hứa khác nhau, và deprecated chỉ giữ lời hứa thứ nhất. Trong giai đoạn chuyển tiếp, server nên tự dịch:
function effectiveMode(request: RecomputeScoreRequest): RecomputeMode {
if (request.recomputeMode && request.recomputeMode !== 'RECOMPUTE_MODE_UNSPECIFIED') {
return request.recomputeMode;
}
return request.forceRecompute ? 'RECOMPUTE_MODE_RECOMPUTE' : 'RECOMPUTE_MODE_USE_CURRENT';
}Vì sao phải reserve số? Protobuf nhận diện field bằng số chứ không bằng tên, nên dùng lại một số cũ sẽ khiến peer cũ decode ra dữ liệu rác mà không báo lỗi; protobuf dos and don'ts xếp điều này gần đầu danh sách. Với JSON và event thì có quy tắc đối xứng: consumer nào từ chối field lạ sẽ biến mọi lần thêm field thành thay đổi phá vỡ.
Hiện thứ duy nhất bảo vệ chuyện này là một quy ước trên giấy cộng với code review, kiểu bảo vệ yếu nhất. Chưa có gì trong CI chạy một caller cũ với một server mới.
Monorepo hay polyrepo cho microservice?
| Câu hỏi | Một Nx workspace | Mỗi service một repo |
|---|---|---|
| Đổi một contract dùng chung | Một diff: producer, consumer, test | Publish package, bump ở khắp nơi |
| Biết ai phụ thuộc vào ai | Tính ra từ import | Một danh sách phải có người giữ |
| Chặn service import lẫn nhau | Một lint rule | Không có gì để import; coupling chuyển sang code copy |
| Ship một service | Cần prune và một bước kiểm tra cô lập | Mặc định đã vậy |
| Nâng cấp build tooling | Một lần | Mười ba lần, mỗi nơi lệch một kiểu |
Tôi sẽ không chọn cách này nếu các service thuộc về những team có nhịp release khác nhau và ít contract chung, hoặc khi chỉ có hai service, lúc đó một thư mục và một script là đủ. Còn nếu không ai chịu enforce boundary, monorepo sẽ thành một distributed monolith có mười ba Dockerfile. (Bản thân workspace này là một submodule được pin trong một meta-repo, nằm cạnh frontend; đó là một quyết định khác, được kể trong Git submodule và meta-repo.)
Cái giá phải trả
Thư viện dùng chung thành cái sảnh mà ai cũng để đồ vào. Service không import được nhau, nên coupling dồn về common, nơi giờ có hơn một nghìn câu lệnh import trỏ tới. Quy tắc nhận code của nó ghi rõ: không NestJS, không Kafka, không Prisma, không controller hay decorator, không retry. Hiện nó export một NestJS health controller, các auth decorator, một rate-limit guard, một helper tạo Kafka topic, một helper kết nối Postgres và một policy lease kèm retry cho background worker. Mỗi thứ thêm vào đều hợp lý vào đúng ngày đó. Gộp lại, service nào cũng phải cài Kafka client, và sửa một helper Kafka sẽ đánh dấu affected cả những service chưa từng publish event nào. Riêng outbox relay vẫn nằm trong từng service publish event; đó là chủ đề của bài về transactional outbox.
Thời gian CI tăng theo graph, không theo thay đổi. Unit test chạy theo một matrix cố định bốn shard, còn job artifact build, prune và boot cả mười ba service ở mọi pipeline.
Bản sao giữ bằng tay thì sẽ lệch. Danh sách proto của mỗi service nằm ở ba nơi. Công thức Dockerfile nằm ở mười bốn nơi: mỗi service một file cho stack local, cộng một file dùng chung cho CI. Chúng đã lệch nhau: migration stage trong file riêng của từng service copy cả workspace, còn file dùng chung chỉ copy schema của đúng service đó.
Nx là phần chịu lực. Build, prune và serve đều đi qua plugin và executor của Nx, được pin vào đúng một phiên bản vì chúng phải nâng cấp cùng nhau. Bỏ Nx đồng nghĩa với viết lại cả ba thứ đó cho mười ba service.
Guard chỉ thấy những gì được load. Một lệnh import() động nằm trên nhánh code ít khi chạy sẽ lọt qua guard cho tới lúc nhánh đó chạy.
Ngay cả decision record cũng ghi monorepo là một định hướng quan sát được trên prototype, chưa phải quy trình release đã kiểm chứng. Gắn nhãn như vậy là đúng.
Nếu làm lại, tôi sẽ làm khác gì?
Khóa cửa ngay từ ngày đầu, và cấm framework trong code nền tảng, để quy tắc nhận code được lint kiểm tra chứ không phải nhờ trí nhớ:
depConstraints: [
{ sourceTag: 'type:service', onlyDependOnLibsWithTags: ['scope:shared'] },
{ sourceTag: 'type:contract', onlyDependOnLibsWithTags: ['type:foundation'] },
{ sourceTag: 'type:infrastructure', onlyDependOnLibsWithTags: ['type:foundation'] },
{
sourceTag: 'type:foundation',
onlyDependOnLibsWithTags: ['type:foundation'],
bannedExternalImports: ['@nestjs/*', 'kafkajs', '@prisma/*'],
},
],Sau đó gắn tag cho các project còn thiếu. Áp dụng ngay hôm nay thì common sẽ fail, và danh sách lỗi đó chính là kế hoạch refactor.
Tách common theo thứ nó kéo theo: một lõi không phụ thuộc framework, cộng các thư viện riêng cho NestJS HTTP, messaging và database. Service nào không publish event sẽ thôi phụ thuộc Kafka, và affected tự hẹp lại.
Sinh danh sách thay vì viết tay: mỗi service một manifest proto, được webpack, build input và verifier cùng đọc; một Dockerfile dùng cho cả stack local lẫn CI.
Kiểm tra breaking change của proto trong CI. buf breaking của Buf so contract với nhánh main và fail khi có field bị xóa hay số bị dùng lại. Nó không bắt được cái boolean bị lờ đi, nhưng bớt cho người review cả một nhóm lỗi phải soi.
Cho unit test chạy theo affected ở merge request, và giữ lần chạy đầy đủ trên nhánh main.
Không điều nào ở trên thay đổi quyết định cốt lõi. Một workspace giữ cho contract luôn nhìn thấy được và tooling nhất quán; artifact đã prune và có guard giữ cho mỗi service ở yên trong căn hộ của nó.
Tóm tắt
- Commit thì atomic, deploy thì không. Hãy thiết kế cho khoảng thời gian hai phiên bản chạy song song.
- Artifact nào cũng phải boot được khi không có workspace xung quanh. Chứng minh điều đó trong CI: copy ra ngoài, cài theo lockfile riêng, boot sau một guard.
nx affectedchỉ hẹp bằng graph của bạn, và cache chỉ trung thực bằng danh sách input của bạn.- Constraint tag kiểu wildcard không chặn được gì. Thêm constraint thật trước khi các project chưa gắn tag chất đống.
- Đổi contract theo expand, migrate, contract, và kiểm tra server có thực sự tôn trọng field cũ chứ không chỉ chấp nhận nó.
Code giờ đã về một chỗ, nhưng các service vẫn phải nói chuyện với nhau; REST, gRPC hay Kafka bàn về cuộc trò chuyện nào nên đi bằng kênh nào.