Pattern 11/22 · Structural
Facade Mặt tiền
Thu một cụm API lặt vặt của subsystem về MỘT API đặt theo ngôn ngữ nghiệp vụ: client gọi một hàm, còn thứ tự gọi, tham số, retry và log là việc của facade.
01 — Mở đầu bằng code đang hỏng
Vấn đề
Đơn hàng đầu tiên cần thanh toán. Bạn mở server/api/checkout.post.ts và viết đủ sáu bước: validate đơn, taxOf(), shipOf(), gateway.charge() kèm retry vì gate hay trả 5xx, ledger.record(), rồi publish("order:paid"). Mười hai dòng. Chạy đúng. Xong.
Tuần sau team mobile cần đúng luồng đó — họ copy mười hai dòng. Team admin làm "tạo đơn hộ khách" — copy mười hai dòng. Batch import đơn từ file CSV — copy mười hai dòng nhưng cố tình bỏ logger.info, "vì import hàng loạt thì log làm gì". Bây giờ bạn có bốn bản của cùng một quy trình, và không bản nào là bản gốc.
Tháng sau gate bắt buộc thêm idempotencyKey. Bạn sửa checkout.post.ts, build pass, test của page đó xanh. Production thì đơn từ mobile fail 100%, vì bản copy của nó vẫn thiếu tham số đó. Không test nào bắt được, vì chính bạn cũng không nhớ có bao nhiêu bản copy.
Có kiểu hỏng thứ hai, tinh vi hơn: một đồng nghiệp "gom cho tiện" bằng cách cho component gọi thẳng gateway.charge() vì "đỡ phải truyền ba tầng tham số". Sáu tháng sau không ai trả lời được câu "subsystem thanh toán gồm những file nào", và mỗi lần đổi signature là một lần grep toàn repo cầu nguyện.
Vấn đề không phải "thiếu một class". Vấn đề là client đang phải mang kiến thức của subsystem: gọi cái gì trước, tham số nào đi cặp với nhau, lỗi nào retry được, lỗi nào là đơn rác. Kiến thức đó nằm ở N nơi, và N tăng theo số page — trong khi nó chỉ nên nằm ở một nơi.
02 — Ý tưởng, chưa động vào code
Giải pháp
Facade là: một API cho cả subsystem. Một module export vài function đặt tên theo nghiệp vụ (pay(order), refund(ref, amount), statusOf(ref)), bên trong nó gọi đủ các bước theo đúng thứ tự. Client chỉ cần biết "thanh toán" — không cần biết tax engine nào đang chạy, gate nào đang được dùng, retry mấy lần.
Có hai chiều cần nói rõ, vì người ta hay làm sai cả hai. Một: facade giấu chứ không cấm — ai cần gate thấp (route đối soát, webhook của gate) vẫn import subsystem trực tiếp được, facade không dựng hàng rào. Hai: facade không phải lớp 1-1 — nếu mỗi function của nó chỉ forward tới đúng một function của subsystem thì đó là Adapter hoặc code thừa, không phải Facade. Giá trị của nó nằm ở chỗ gom nhiều call thành một, và nó biết nghiệp vụ, subsystem thì không.
Trong TypeScript, facade hầu như không cần class: một module server/utils/checkout.ts với export function pay() là đủ, vì bạn không cần nhiều instance của "quy trình thanh toán". Facade ở đây là một biên giới module có tên, không phải một object. Dùng class khi nó cần giữ config hoặc cần inject để test.
03 — Làm thật, mỗi bước một fragment code
Từng bước một
Đếm số bản copy của cùng một trình tự gọi
Facade không khởi đầu bằng "class này to quá". Nó khởi đầu bằng grep. Cùng một trình tự gọi xuất hiện ở ≥ 2-3 chỗ, và mỗi chỗ bắt đầu lệch nhau một chút (chỗ thiếu log, chỗ thiếu retry) — đó là tín hiệu.
Đây là code đang chạy và "không có gì sai" về mặt syntax. Hãy nhìn đúng chỗ hỏng: không phải độ dài, mà là kiến thức nằm sai chỗ.
export default defineEventHandler(async (event) => {
const order = await readOrder(event)
if (!order.items.length) throw createError({ statusCode: 400, statusMessage: 'empty order' })
const total = order.subtotal + taxOf(order) + shipOf(order)
const ref = await withRetry(() => gateway.charge(total, order.idempotencyKey), 3)
await ledger.record(order.id, total, ref)
logger.info('order paid', { id: order.id, total, ref })
await queue.publish('order:paid', { id: order.id, ref })
return { ref }
})
// Mười hai dòng y hệt còn nằm ở:
// mobile/checkout.ts (thiếu publish -> webhook không chạy)
// admin/manual-order.ts (thiếu retry -> fail khi gate 5xx)
// import-batch.ts (tự viết retry riêng, 3 lần -> 5 lần)Chẻ mười hai dòng đó ra: dòng nào là của ai?
Trước khi chuyển code, cầm bút chỉ từng dòng. Mười hai dòng kia là bốn trách nhiệm bị đóng gói nhầm trong một handler: quy tắc của đơn, tính tiền, I/O ra gate, và observability. Ba cái sau thuộc về subsystem, cái đầu thuộc về checkout.
Việc phân loại này quyết định chất lượng facade. Facade tốt không chứa công thức tính thuế — nó gọi taxOf(). Nó chứa thứ tự và lời hứa: "đơn phải được ghi ledger trước khi publish", "gate lỗi thì retry 3 lần rồi mới fail".
validate(order) -> quy tắc của đơn -> Ở LẠI với checkout
taxOf / shipOf -> tính toán thuần -> subsystem pricing
gateway.charge + retry -> I/O, trượt được -> subsystem payment
ledger / logger / queue-> observability, bất biến -> subsystem ledgerif tính toán nghiệp vụ, nó bắt đầu là god object từ hôm nay.Thiết kế API bằng ngôn ngữ nghiệp vụ, không bằng tên subsystem
Chốt API trước khi viết body. Ba câu hỏi: client gọi mấy lần một phiên, lỗi nào client cần phân biệt, và cái gì tuyệt đối không được thò ra ngoài (gateway, taxRuleId).
Chú ý tên: pay(order) chứ không phải charge(order) hay callGateway(). Client là page/mobile/batch, họ nghĩ bằng "thanh toán", không nghĩ bằng "gate". Đặt tên theo phía gọi là cách rẻ nhất để API không phình.
// Toàn bộ "mặt tiền" của subsystem thanh toán là 3 function này.
export function pay(order: OrderDraft): Promise<PaymentResult>
export function refund(paymentRef: string, amount: number, reason: string): Promise<PaymentResult>
export function statusOf(paymentRef: string): Promise<PaymentStatus>
// MẤI CÁI NÀY KHÔNG BAO GIỜ xuất hiện ở mặt tiền:
// gateway.charge / gateway.verify3ds / taxRule.pick / ledger.connect
// Ai thật sự cần thì import thẳng từ subsystem (xem Bước 7), không đi qua đây.Dời body vào trong facade, giữ nguyên thứ tự
Bây giờ mới move. Move từng dòng một, không tiện tay viết lại logic: refactor này mà đổi hành vi thì bạn sẽ không phân biệt được bug cũ hay bug do mình.
Mọi dependency đều là import trực tiếp hoặc tham số — facade không tự quyết định "dùng gate nào", nhận từ config/injection. Đó là chỗ nó khác một "Service God".
export async function pay(order: OrderDraft): Promise<PaymentResult> {
if (!order.items.length) return { ok: false, reason: 'empty-order' }
const total = order.subtotal + taxOf(order) + shipOf(order)
const ref = await withRetry(() => gateway.charge(total, order.idempotencyKey), 3)
.catch(() => null)
if (!ref) return { ok: false, reason: 'gateway-unavailable' }
await ledger.record(order.id, total, ref) // ledger TRƯỚC publish: lời hứa của facade
logger.info('order paid', { id: order.id, total, ref })
await queue.publish('order:paid', { id: order.id, ref })
return { ok: true, ref, total }
}Dịch lỗi của subsystem thành lỗi của nghiệp vụ
Facade lộ lỗi của gate (ECONNRESET, 402 card_declined) ra ngoài nghĩa là client phải biết gate là gì — và bạn vừa đào lỗ hổng leak thông tin. Facade dịch: client chỉ nhận những khả năng mà UI hành động được.
Dùng union type thay vì throw lung tung. TypeScript sẽ bắt mọi call site xử lý đủ các nhánh, kể cả bản copy mà bạn chưa biết tồn tại.
export type PaymentResult =
| { ok: true, ref: string, total: number }
| { ok: false, reason: 'empty-order' } // khách sửa được
| { ok: false, reason: 'declined' } // khách chọn thẻ khác
| { ok: false, reason: 'gateway-unavailable' } // thử lại sau, giữ đơn
// 'ECONNRESET', '402', stack trace của gate: dừng ở đây, chỉ vào log.
// Client render message theo reason, không bao giờ render message thô từ gate.Call site còn đúng một dòng
Bốn nơi copy giờ còn một dòng. Khi gate đòi thêm idempotencyKey, bạn sửa một file và không còn kịch bản "mobile fail im lặng" nữa.
Lưu ý chiều ngược lại: facade không được bắt client phải "hỏi lại" nó là ai. pay(order) nhận đủ thứ từ order, không đọc useRequest() bên trong — nếu không, batch job và test sẽ không gọi được nó.
// page checkout
const r = await pay(order)
if (!r.ok) showToast(r.reason)
// mobile
const r = await pay(order)
// import hàng loạt: dùng lại đúng một đường, không copy quy trình
for (const order of batch) results.push(await pay(order))Giữ cửa phía sau: facade giấu, không chặn
Route đối soát cần gateway.listCharges(date) với field mà facade không expose. Đúng. Nó import subsystem trực tiếp. Facade phục vụ client phổ biến, nó không phải người gác cổng duy nhất, và cố biến nó thành độc quyền là cách nhanh nhất để mọi người bắt đầu // @ts-ignore.
Hệ quả thực tế của "không chặn": facade không bảo đảm mọi đường đi đều qua nó. Nó giảm chi phí làm đúng, chứ không làm điều sai thành bất khả thi. Đừng bán cho team cái ảo giác đó — dùng lint rule nếu thật sự cần chặn.
// Facade không có listCharges(), và không nên có: client phổ biến không cần nó.
import { listCharges } from '~/server/subsystems/payment/gateway'
export default defineEventHandler(async () => {
const charges = await listCharges(yesterday()) // gate thấp, có chủ đích
return reconcile(charges, await ledger.rowsOf(yesterday()))
})eslint-plugin-local-rules soi nếu muốn chặn đường này.Ca trực: facade không được lớn lên
Facade hỏng theo một cách rất dễ nhận: nó bắt đầu quyết định thay vì phối hợp. Hôm nay if (order.kind === "b2b") trong pay(), sáu tháng sau nó là 400 dòng và không ai dám xoá.
Ba câu hỏi định kỳ: facade có state không (không được có)? có công thức tính toán không (gọi subsystem)? có hàm nào > 30 dòng không (tách ra, hoặc tách subsystem)? Khi nó phình, câu trả lời đúng thường là "có hai subsystem đang nằm chung một file".
// Mùi 1: facade giữ logic tính toán
if (order.kind === 'b2b') total = total * 0.9 // <- tax/pricing engine ở đâu?
// Mùi 2: facade giữ state
private cache = new Map() // <- facade giờ là singleton có trí nhớ, test toi
// Mùi 3: facade 1-1 với subsystem
export const charge = (n) => gateway.charge(n) // <- đây là Adapter, xoá đi
// Mùi 4: facade = barrel file
export * from './gateway'; export * from './tax' // <- không giấu gì cả04 — Ai nói chuyện với ai
Cấu trúc
- FacadeAPI công khai của subsystem, đặt tên theo nghiệp vụ (`pay`, `refund`). Giữ thứ tự gọi và lời hứa, không giữ công thức.
- SubsystemCác module thật làm việc: pricing, gateway, ledger. Không biết facade tồn tại, vẫn dùng trực tiếp được.
- ClientPage, mobile, batch job, cron. Gọi 1-2 function, chỉ nhận lỗi nghiệp vụ (`reason: "declined"`).
- Low-level consumerRoute đối soát, webhook của gate. Cố tình bỏ qua facade để lấy field chi tiết — facade không chặn.
Client Facade Subsystem
------ ------ ---------
page ┐
mobile ├── pay(order) ┌──────────────┐
batch import ┘ ────────────► │ checkout.ts │──► pricing: taxOf, shipOf
│ 1 API │──► payment: charge+retry
đối soát / webhook ────────────►│ theo nghiệp │──► ledger: record
│ vụ │
(và còn import gateway └──────────────┘
trực tiếp được — không cấm)05 — Sửa tuỳ ý, chạy ngay tại đây
Chạy thử: sáu bước subsystem, một lời gọi từ client
type Order = { id: string, subtotal: number, weightKg: number }
// --- Subsystem: mấy bước rời rạc, thứ tự gọi là kiến thức quan trọng ---
const validate = (o: Order) => {
if (!o.id || o.subtotal <= 0) throw new Error('don khong hop le: ' + o.id)
}
const taxOf = (o: Order) => Math.round(o.subtotal * 0.1)
const shipOf = (o: Order) => (o.weightKg > 5 ? 60_000 : 30_000)
const audit = (line: string) => 'AUDIT ' + line
// Gate gia lap: lan goi dau tien luon truot, de retry co viec
let gatewayCalls = 0
const charge = (total: number) => {
gatewayCalls++
return gatewayCalls === 1 ? null : 'CH-' + total
}
class CheckoutFacade {
pay(order: Order): string {
validate(order)
const total = order.subtotal + taxOf(order) + shipOf(order)
const ref = this.retry(total, 3) ?? 'FAILED'
console.log(audit(order.id + ' total=' + total + ' ref=' + ref))
return ref
}
private retry(total: number, max: number): string | null {
for (let i = 0; i < max; i++) {
const ok = charge(total)
if (ok) return ok
}
return null
}
}
const checkout = new CheckoutFacade()
checkout.pay({ id: 'DH-01', subtotal: 500_000, weightKg: 2 })
checkout.pay({ id: 'DH-02', subtotal: 250_000, weightKg: 9 })
try {
checkout.pay({ id: 'BAD', subtotal: 0, weightKg: 1 })
}
catch (e) {
console.log('REJECTED ' + (e as Error).message)
}AUDIT DH-01 total=580000 ref=CH-580000 AUDIT DH-02 total=335000 ref=CH-335000 REJECTED don khong hop le: BAD
Cùng code này chạy được bằng Bun: bun run demo.ts. Output in ra được kiểm tự động trong quá trình build site.
06 — Thành thật về cái giá
Khi nào dùng, khi nào đừng
Dùng khi
- Cùng một trình tự gọi (validate → tính → I/O → log → publish) bị lặp ở ≥ 2-3 nơi, và các bản copy đang bắt đầu lệch nhau.
- Client là các phía rất khác nhau (web, mobile, batch, cron) nhưng đều cần cùng một quy trình nghiệp vụ.
- Bạn muốn subsystem đổi bên trong (đổi gate, đổi tax engine, thêm retry) mà không sửa bất kỳ file client nào.
- Có một API phức tạp/rối (legacy, SDK bên thứ ba, ORM nhiều bước) mà 90% client chỉ dùng đúng một kịch bản.
- Cần một chỗ hợp pháp để đặt lời hứa về thứ tự ("ghi ledger trước khi publish") thay vì tin từng call site tự nhớ.
Đừng dùng khi
- Facade lớn lên thành god object. Chỉ cần nó giữ một
iftính toán là nó bắt đầu hút mọi logic tiện thể. Fix: facade không công thức, không state, không quá ~30 dòng mỗi function. - Facade 1-1: mỗi function chỉ forward tới một function subsystem, đổi tên. Đó không phải Facade, đó là lớp middleware không làm gì — xoá đi, nó chỉ thêm stack trace.
- Facade = barrel file:
export * from "./gateway"rồi gọi đó là facade. Barrel file gom export, nó không giấu gì và không giữ lời hứa nào. Facade phải rút gọn surface, không phải đổi chỗ nó. - Nhầm với Adapter / DI container. Adapter: một API đã có, hình dạng sai, bạn sửa hình dạng cho một client cụ thể. Facade: nhiều API, bạn thu về một API dễ dùng cho mọi client. DI container: quyết định instance nào được tạo; facade quyết định client được biết những gì. Hai cái độc lập, dự án thật thường có cả hai.
- Over-engineering. Một client, subsystem ba function, API đã rõ? Không cần facade — gọi thẳng. Facade đáng giá khi số call site của quy trình lớn hơn số bước của quy trình.
07 — Bạn đã gặp nó rồi, chỉ là không gọi tên
Trong code thật
Server route trong Nuxt/Express
Một POST /api/checkout đứng trước validate + pricing + gateway + ledger + queue chính là facade, và đó là lý do client không bao giờ được ghép các bước đó ở trình duyệt. Router handler là chỗ rẻ nhất để đặt facade trong ứng dụng fullstack TS.
fetch() của browser
Bạn gọi một hàm với một URL. DNS, TCP, TLS, cookie, redirect, gzip, HTTP/2 multiplexing, cache HTTP đều ở phía sau. Đây là facade đúng nghĩa: API nhỏ, stable, che một subsystem cực phức tạp — và bạn vẫn xuống được tầng dưới (XMLHttpRequest, interceptor) nếu thật sự cần.
navigator.clipboard.writeText()
Một function che quy tắc focus, permission prompt, encoding, và different OS clipboard backend. Facade kiểu này cũng cho thấy mặt trái: khi bạn cần behaviour thấp hơn, bạn phải xin API khác, không "xin qua facade".
API layer của framework: useFetch()
Một function che fetch SSR, serialize payload sang client, dedupe key, hydration và retry. Nó là facade cộng thêm nhiều thứ khác, và nó chứng thực luôn hai điều: facade làm DX tốt hơn, và facade làm bạn khó thấy chi phí thật nếu không đọc tài liệu.
08 — Tự tay làm
Bài tập
Sáu trang admin cùng copy bốn bước: `loadUser(id)`, `can(actor, "user:read")`, map sang `UserViewModel`, `audit.log(...)`. Hãy rút về một facade `userView.ts` và chỉ ra ít nhất hai thứ facade **không** nên expose, cùng một thứ rất dễ bị nhét vào facade và biến nó thành god object.
Gợi ý, mở từng cái một:
- API nghiệp vụ là gì? Một hay hai function? Tên nào mô tả ý định của người gọi thay vì tên subsystem?
- Lỗi nào client cần phân biệt (not found vs forbidden vs not verified)? Mô hình chúng bằng union type.
- Field nhạy cảm (
passwordHash,salt, token reset) nên nằm ở đâu: trong ViewModel, trong facade, hay trong repository?
Một facade hai function: loadUserView(id, actor) và loadUserViews(ids, actor). Nó gọi repository, gọi can(), log audit, map sang ViewModel không chứa field nhạy cảm, và trả union UserViewResult. Repository, audit sink, passwordHash và PrismaClient đều không nằm ở mặt tiền. Thứ dễ làm facade mục là logic filter/permission theo vai trò: nó thuộc can()/policy, facade chỉ gọi.
// app/utils/user-view.ts <- đây là toàn bộ mặt tiền
export type UserViewResult =
| { ok: true, view: UserViewModel }
| { ok: false, reason: 'not-found' | 'forbidden' | 'not-verified' }
export async function loadUserView(id: string, actor: Actor): Promise<UserViewResult> {
const user = await userRepo.findById(id)
if (!user) return { ok: false, reason: 'not-found' }
if (!can(actor, 'user:read', user)) return { ok: false, reason: 'forbidden' }
if (!user.verifiedAt) return { ok: false, reason: 'not-verified' }
audit.log('user.view', { id, actor: actor.id })
return { ok: true, view: toViewModel(user) } // toViewModel KHÔNG copy passwordHash
}09 — Đọc cặp để hiểu bản chất
Pattern liên quan
- AdapterAdapter sửa **hình dạng** một API đã có cho khớp một client cụ thể (1-1). Facade thu **nhiều** API về một API đơn giản. Adapter không biết nghiệp vụ, Facade sống bằng nghiệp vụ.
- MediatorMediator là quan hệ hai chiều: các module gọi mediator và mediator gọi lại chúng. Facade một chiều: subsystem không biết facade tồn tại.
- SingletonFacade thường chỉ cần một instance nên hay bị viết thành module singleton. Hai chuyện không liên quan — đừng vì "facade là singleton" mà coi đó là lý do tồn tại của nó.
- ProxyProxy giữ **cùng** interface với object thật để kiểm soát truy cập; Facade **đổi** interface để đơn giản hoá. Đọc cặp này để thấy "đứng trước một object" có hai mục đích rất khác.