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.

Cấu trúc●○○11 phút đọc8 bướccòn gọi: Gateway, Service boundary (đôi khi người ta gọi nhầm là "wrapper")
structuralsubsystemmodule boundaryapigod objectcheckout

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

1

Đế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ỗ.

tsserver/api/checkout.post.ts
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)
Bốn bản copy, bốn tập hợp bug khác nhau. Không test nào cover hết, vì không ai biết chúng phải giống nhau.
ChốtFacade đáng dùng khi bạn thấy cùng một trình tự bị lặp, không phải khi bạn thấy một class nhiều dòng.
2

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".

textphan-loai.ts
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 ledger
Facade giữ "thứ tự + lời hứa". Nó không giữ công thức.
ChốtNếu facade của bạn chứa một if tính toán nghiệp vụ, nó bắt đầu là god object từ hôm nay.
3

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.

tsserver/utils/checkout.ts
// 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.
Interface nhỏ là sản phẩm thiết kế. Hãy đọc nó như khách sẽ đọc.
ChốtĐếm number function của facade mỗi tuần một lần. Nó tăng nghĩa là subsystem đang rò rỉ ra ngoài.
4

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".

tsserver/utils/checkout.ts
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 }
}
Không đổi hành vi, chỉ đổi chỗ nằm. Đây là refactor, không phải rewrite.
ChốtChạy test của tất cả call site trước và sau khi move. Kết quả phải giống hệt từng byte.
5

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.

tscheckout-result.ts
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.
Một union type nhỏ ngăn được cả một họ bug "lộ nội bộ ra UI".
ChốtAPI của facade là chỗ lỗi mất chi tiết kỹ thuật và lấy lại ý nghĩa nghiệp vụ.
6

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ó.

ts3-call-sites.ts
// 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))
Ba call site, một nguồn sự thật. Retry/log/ledger không còn tuỳ hứng nữa.
ChốtAPI của facade tốt được đo bằng số dòng còn lại ở call site, không bằng số function nó expose.
7

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.

tsserver/api/reconciliation.post.ts
// 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()))
})
Vẫn dùng import trực tiếp có chủ đích, và đặt eslint-plugin-local-rules soi nếu muốn chặn đường này.
ChốtFacade tốt làm việc đúng thành việc dễ nhất, không thành việc duy nhất.
8

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".

textchecklist.ts
// 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ả
Facade mà ai cũng "sửa nhanh một dòng trong pay()" thì facade đã chết.
ChốtFacade giữ logic = god object có tên đẹp. Nó phối hợp, không suy nghĩ.

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

tsdemo.ts
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)
}
console
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 if tí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:

  1. 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?
  2. 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.
  3. 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.

tsbai-tap.ts
// 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.