Pattern 13/22 · Creational
Builder Trình dựng
Dựng object nhiều tham số bằng một object trung gian tích luỹ dần (đa số optional), rồi chốt ở build() — nơi duy nhất validate mọi ràng buộc và tạo ra object cuối cùng đã chắc chắn hợp lệ.
01 — Mở đầu bằng code đang hỏng
Vấn đề
Component slider của bạn có 8 thông số: width, step, disabled, showTicks, trackColor, value, min, max. Buổi sáng đầu tiên, bạn viết:
Bài toán của Builder bắt đầu từ một dòng code trông có vẻ vô hại, và nó hỏng theo cách rất cụ thể. Gọi new Slider(300, 20, true, false, "#000", 1) thì người đọc phải mở constructor mới biết true là gì, false là gì, và 1 là value hay là min. Tệ hơn: hai tham số boolean nằm cạnh nhau, hoán đổi cho nhau thì code vẫn chạy, vẫn type-check xanh, chỉ khác là ticks bị ẩn và slider bị disable. Không test nào bắt được, vì chẳng ai nghĩ đó là bug.
TypeScript không cứu được bạn ở đây, và nên nói rõ lý do: máy kiểm tra thứ tự và kiểu, còn ở đây các kiểu trùng nhau. Đổi chỗ hai number, đổi chỗ hai string — hợp lệ cả. Constructor nhiều tham số cùng kiểu là điểm mù cố hữu của mọi ngôn ngữ có positional arguments.
Bản vá ai cũng nghĩ ra: options object. new Slider({ width: 300, step: 20, disabled: true, trackColor: "#000" }) kèm default cho phần còn thiếu. Vấn đề đọc code hết ngay lập tức, và tôi muốn nói thẳng: 80% số ca "cần Builder" kết thúc đúng ở đây và nên kết thúc ở đây.
Nhưng rồi invariant kéo đến. min phải nhỏ hơn max; value phải nằm trong [min, max]; step phải chia hết khoảng; precision và format tự do mâu thuẫn nhau; logarithmic: true thì hợp lệ với min > 0 còn min = 0 thì không. Options object cho phép bạn dựng ra một object sai ở bất kỳ đâu trong codebase. Đem hết validation nhét vào constructor thì lại sinh vấn đề khác: mọi field phải đến cùng một lúc, trong khi team config dựng min/max từ file theme, còn value thì job đồng bộ dữ liệu gán vào sau.
Và có những object không có "một lúc" nào để validate. Client HTTP: set baseURL, rồi headers, rồi timeout, rồi ký request, rồi gửi — sau khi gửi thì cấm sửa thêm. Query builder: from trước, rồi where, rồi orderBy, rồi limit, rồi execute. Options literal không có khái niệm "khi nào" và "cái gì được gọi sau cái gì". Builder tồn tại cho đúng hai thứ: ràng buộc liên-trường, và quá trình dựng trải qua nhiều bước.
02 — Ý tưởng, chưa động vào code
Giải pháp
Tách làm hai object. Builder: mutable, cho phép ở trạng thái chưa hợp lệ, nhiệm vụ duy nhất là gom cấu hình. Product (Slider): readonly, không tự dựng được từ bên ngoài, và mọi instance của nó được đảm bảo là hợp lệ. Chỗ duy nhất nối hai thế giới là build(), và đó là nơi bạn đặt toàn bộ validation — một lần, gần với nơi nó được vi phạm nhất.
Setter trả về this để bạn đọc cấu hình như một câu: new SliderBuilder().min(0).max(100).step(5).value(20).build(). Mỗi setter cũng có thể giữ luôn luật cục bộ của nó (step(-1) chết ngay tại chỗ gọi, thay vì chết ở build() sau 20 dòng gọi tiếp), còn build() lo các ràng buộc liên trường mà một setter không thể biết.
Phần còn lại của trang này là về việc không dùng Builder. Vì trong TypeScript, builder là pattern dễ bị dùng sai nhất trong họ creational: nó trông có vẻ chuyên nghiệp, viết thì vui tay, và chi phí của nó (state mutable sống lâu, một object thừa, một tầng gián tiếp) là chi phí âm — bạn chỉ cảm nhận được khi debug. Nếu sản phẩm của bạn không có ràng buộc liên-trường và không có quá trình dựng nhiều giai đoạn, thì hàm 12 dòng ở bước cuối là bản đúng. Builder là công cụ của invariant, không phải công cụ của "nhiều tham số".
03 — Làm thật, mỗi bước một fragment code
Từng bước một
Viết bản thảm hoạ, và chỉ mặt đúng hai bug
Đây là điểm xuất phát thật của đa số slider, tooltip, table config:
class Slider {
constructor(
width: number, step: number, disabled: boolean,
showTicks: boolean, trackColor: string, value: number,
min: number, max: number,
) { /* ... */ }
}
const a = new Slider(300, 20, true, false, "#000", 1, 0, 100)
const b = new Slider(300, 20, false, true, "#000", 1, 0, 100) // intended
// Bug thật sự: ở file thứ 47, ai đó viết value trước min:
const c = new Slider(300, 20, false, true, "#000", 0, 1, 100)c dựng slider với value=0 và min=1 — hợp lệ với TS, vô nghĩa với người dùng.Options object + default: hết mù tham số, và thường là đủ
Trước khi dựng builder, hãy làm bước này. Một object tham số, required đứng riêng, optional đi kèm default:
interface SliderOpts {
min: number // bắt buộc: TS ép bạn truyền
max: number
step?: number
value?: number
disabled?: boolean
showTicks?: boolean
trackColor?: string
}
const DEFAULTS = { step: 1, value: 0, disabled: false, showTicks: true, trackColor: "#888" }
class Slider {
constructor(opts: SliderOpts) {
const o = { ...DEFAULTS, ...opts }
// ...
}
}Liệt kê invariant — câu hỏi sống còn của pattern
Cầm giấy, viết hết các câu luật dạng "field A thì liên quan field B". Đây là danh sách thật của một slider sau 6 tháng sống:
1. min < max
2. min <= value <= max
3. (max - min) chia hết cho step
4. logarithmic => min > 0
5. precision chỉ có nghĩa khi format = "number"
6. format custom => phải có formatter, và ngược lại
7. disabled => value bị khoá (không được set sau đó)
=> Có ràng buộc LIÊN TRƯỜNG = Builder có lý do.
=> Chỉ có default cho từng field = Options object là đủ.Tách phần tích luỹ khỏi phần bất biến
Hai class, hai số phận. Builder thì mutable và được phép chưa hợp lệ — đó là tính năng, không phải lỗi: nó là nơi bạn chứa trạng thái đang dựng dở. Product thì readonly và chỉ được sinh ra từ một cửa.
class Slider {
constructor(
readonly min: number,
readonly max: number,
readonly step: number,
readonly value: number,
) {}
// Không có setter. Muốn đổi: build lại một cái mới.
}
class SliderBuilder {
#min = 0
#max = 100
#step = 1
#value = 0
// Trạng thái trung gian: CHƯA cần hợp lệ.
}Slider trên tay, mọi luật ở bước 3 đã đúng — không cần kiểm tra lại.Setter trả về this, mỗi setter giữ luật cục bộ của nó
Fluent không phải để cho đẹp: nó cho phép một cấu hình dài đọc như một câu, và cho bạn quyền chết sớm ở luật cục bộ. step(-1) sai một mình, không cần field nào khác — chặn ngay tại setter, báo lỗi ngay tại dòng gọi:
class SliderBuilder {
#min = 0
#max = 100
#step = 1
min(v: number) { this.#min = v; return this }
max(v: number) { this.#max = v; return this }
step(v: number) {
if (v <= 0) throw new Error("step phải lớn hơn 0") // luật đơn field
this.#step = v
return this
}
}build() vì lúc đó mới đủ dữ kiện.build() là cánh cổng duy nhất, và là nơi validate thật
Toàn bộ validation liên trường nằm ở đây, theo thứ tự từ lỗi dễ gặp nhất. Đây cũng là lúc bạn nhét default cuối cùng và cắt các kết hợp vô nghĩa:
class SliderBuilder {
// ... các field và setter ở bước trước
build(): Slider {
if (this.#min >= this.#max) throw new Error("min phải nhỏ hơn max")
if (this.#value < this.#min || this.#value > this.#max)
throw new Error("value " + this.#value + " nằm ngoài [" + this.#min + ", " + this.#max + "]")
if ((this.#max - this.#min) % this.#step !== 0)
throw new Error("step " + this.#step + " không chia hết khoảng " + (this.#max - this.#min))
return Slider.from({ min: this.#min, max: this.#max, step: this.#step, value: this.#value })
}
}Type-state: khi trình tự các bước là một luật
Có những builder mà thứ tự là nghiệp vụ: query chưa from thì where vô nghĩa; request đã send() thì không được setHeader() nữa. Validation lúc chạy chỉ bắt được sau khi ai đó chạy test. Type-state bắt được lúc viết code, bằng cách để method tồn tại trên type hay không tuỳ state:
class SelectQ<HasFrom = false> {
#sql: string[] = []
from(this: SelectQ<false>, table: string): SelectQ<true> {
this.#sql.push("from " + table)
return this as SelectQ<true>
}
where(this: SelectQ<true>, cond: string): SelectQ<true> {
this.#sql.push("where " + cond)
return this
}
execute(this: SelectQ<true>): string { return this.#sql.join(" ") }
}
new SelectQ().from("user").where("id = 1").execute() // OK
new SelectQ().where("id = 1") // lỗi biên dịchthis:. Kysely và các query builder typed dùng biến thể của đúng chiêu này.Bản 12 dòng, và bốn câu hỏi trước khi cam kết
Đây là phần mà đa số bài viết về Builder không có. Đa số "builder" trong dự án TS thật ra là một hàm thuần tuý + một hàm assert, và bản đó tốt hơn vì nó không có state, không allocation thừa, và đọc hết trong 12 dòng:
type SliderOpts = { min: number, max: number, step?: number, value?: number }
function assertValid(o: Required<SliderOpts>) {
if (o.min >= o.max) throw new Error("min phải nhỏ hơn max")
if (o.value < o.min || o.value > o.max) throw new Error("value ngoài khoảng")
if ((o.max - o.min) % o.step !== 0) throw new Error("step không chia hết khoảng")
}
export function buildSlider(opts: SliderOpts): Slider {
const o = { step: 1, value: opts.min, ...opts } as Required<SliderOpts>
assertValid(o)
return new Slider(o.min, o.max, o.step, o.value)
}04 — Ai nói chuyện với ai
Cấu trúc
- BuilderGiữ cấu hình mutable, expose setter trả về `this`, cho phép trạng thái chưa hợp lệ.
- Product (Slider) readonly, không setter, **chỉ** đi qua được `build()`. Mọi instance của nó đều hợp lệ.
- DirectorGoF có cái này (một quy trình dựng cố định). Trong JS/TS gần như không tồn tại — nếu bạn viết Director, thường là bạn đang viết lại một function.
- ClientChuỗi setter rồi `build()`. Sau bước này client chỉ cầm Product, không cầm Builder.
- ValidatorKhông phải class, nhưng là nhân vật chính: tập luật liên trường đặt trong `build()` (hoặc một `parse()` riêng).
Client
│ new SliderBuilder().min(0).max(100).step(5).value(20)
▼
┌────────────────────────────────┐
│ SliderBuilder (MUTABLE) │ trạng thái CHƯA hợp lệ: được phép
│ #min #max #step #value │
│ + min(v): this │
│ + build(): Slider │ <- validate liên trường, 1 lần
└───────────────┬────────────────┘
│ duy nhất được phép tạo Slider
▼
┌──────────────────────────────┐
│ Slider (READONLY) │ đã hợp lệ, không sửa được nữa
└──────────────────────────────┘
Phản ví dụ: nếu Client cầm Builder đi qua 3 tầng,
Builder thành tham số ẩn -> bug không ai lần ra.05 — Sửa tuỳ ý, chạy ngay tại đây
Chạy thử: ba lần build, hai lần bị chặn ở cổng
type Config = { min: number, max: number, step: number, value: number, label: string }
class Slider {
private constructor(private readonly c: Config) {}
static from(c: Config) { return new Slider(c) }
toString() {
return 'Slider(' + this.c.label + ' min=' + this.c.min + ' max=' + this.c.max
+ ' step=' + this.c.step + ' value=' + this.c.value + ')'
}
}
class SliderBuilder {
#min = 0
#max = 100
#step = 1
#value = 0
#label = 'slider'
min(v: number) { this.#min = v; return this }
max(v: number) { this.#max = v; return this }
step(v: number) { if (v <= 0) throw new Error('step phải lớn hơn 0'); this.#step = v; return this }
value(v: number) { this.#value = v; return this }
label(s: string) { this.#label = s; return this }
build(): Slider {
if (this.#min >= this.#max) throw new Error('min phải nhỏ hơn max')
if (this.#value < this.#min || this.#value > this.#max)
throw new Error('value ' + this.#value + ' nằm ngoài [' + this.#min + ', ' + this.#max + ']')
if ((this.#max - this.#min) % this.#step !== 0)
throw new Error('step ' + this.#step + ' không chia hết khoảng ' + (this.#max - this.#min))
return Slider.from({ min: this.#min, max: this.#max, step: this.#step, value: this.#value, label: this.#label })
}
}
function attempt(tag: string, fn: () => Slider) {
try { console.log('OK ' + tag + ' -> ' + fn()) }
catch (e) { console.log('CHAN ' + tag + ' -> ' + (e as Error).message) }
}
attempt('hop le', () => new SliderBuilder().min(0).max(100).step(5).value(20).label('Volume').build())
attempt('value', () => new SliderBuilder().max(100).value(150).build())
attempt('step', () => new SliderBuilder().min(0).max(100).step(7).build())OK hop le -> Slider(Volume min=0 max=100 step=5 value=20) CHAN value -> value 150 nằm ngoài [0, 100] CHAN step -> step 7 không chia hết khoảng 100
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
- Nhiều field optional (từ ~4 trở lên) và có ràng buộc liên field — tức là có những tổ hợp giá trị bị cấm.
- Bạn muốn Product bất biến và mọi instance đang tồn tại đều hợp lệ, để phần còn lại của code không phải re-check.
- Quá trình dựng trải ra nhiều bước hoặc nhiều nơi: middleware A set timeout, module B set headers, rồi một chỗ khác mới gửi.
- Thứ tự thao tác là nghiệp vụ: chưa
fromthì chưawhere, đãsend()thì không sửa được nữa (type-state). - Bạn expose API cho team khác và muốn họ không có cách nào tạo object sai — builder lúc này là tài liệu biết chạy, thay vì một trang wiki.
- Cần nhiều biến thể từ cùng một cấu hình gốc (clone rồi đổi 2 field): giữ builder sống có chủ đích, rồi
build()nhiều lần.
Đừng dùng khi
- Over-engineering là lỗi mặc định của pattern này, và nó tinh vi vì code builder trông rất có nghề. Chỉ vì constructor nhiều tham số KHÔNG phải lý do. Không có invariant liên field, không có quá trình dựng nhiều giai đoạn thì
build()chỉ làreturn new X(...)đội lốt: bạn vừa thêm 40 dòng mutable state, một allocation thừa, và một tầng gián tiếp giữa reader và sự thật. Options object 12 dòng thắng. - Fluent API che một cái bẫy kinh điển: setter trả
thisnghĩa là object bị sửa âm thầm.const b = new Builder().min(0); const a = b.max(10); const c = b.max(20)—avàclà cùng một object, vàavừa bị đổi thành 20. Hoặc setter clone rồi trả bản mới (zod làm vậy), hoặc chấp nhận và viết tài liệu to đùng. - Đừng để Builder đi du lịch qua nhiều tầng. Service nhận builder rồi "tiện tay" set thêm một field là tham số ẩn: hành vi của function không còn đọc được từ chữ ký, và bạn sẽ debug hai ngày cho một dòng
.set()nằm sai chỗ. Builder nên sống và chết trong một hàm. - Đóng constructor bằng
privatecủa TypeScript chỉ là an toàn lúc biên dịch:(Slider as any)hoặc JS thuần đi vòng qua dễ dàng. Nếu bạn thật sự cần guarantee, đừng export class — chỉ export builder và type, đóng ở ranh giới module. - Một chuỗi fluent 15
.withX()không đọc hơn options object, nó chỉ đọc khác đi; và vừa đủ là bạn phải ngắt chuỗi bằngif, lúc đó fluent mất hết lý do. Validation input từ user/HTTP vẫn phải nằm ở ranh giới bằng schema (zod/valibot) — Builder không thay thế validation của dữ liệu không tin cậy được.
07 — Bạn đã gặp nó rồi, chỉ là không gọi tên
Trong code thật
Query builder typed: Kysely, Drizzle, Prisma.sql
Kiểu mẫu quen nhất trong hệ Node/TS: db.selectFrom("user").where("id", "=", 1).limit(1).execute(). Trạng thái tích luỹ dần, và execute()/compile() là build() — chỉ lúc đó SQL mới được sinh ra và chỉ lúc đó SQL được kiểm tra. Các thư viện typed còn dùng generic để method chưa hợp lệ không tồn tại trên type, tức là type-state đúng nghĩa.
Commander / Cac: program.option(...).parse(process.argv)
CLI builder đúng nghĩa trong Node: bạn thêm option, thêm subcommand, mô tả, default — và parse() là cổng chốt, nơi tham số được ép kiểu, default được áp và giá trị sai bị từ chối. Người dùng không bao giờ chạm được vào object config chưa hoàn thiện.
Zod: schema.refine(...).transform(...).parse(input)
Fluent nhưng immuttable: mỗi lần .refine()/.optional() trả về schema mới chứ không sửa cái cũ — chính là cách né cái bẫy aliasing ở pitfalls. parse() là build(): mọi ràng buộc liên field (superRefine) được thi hành một lần, ở một chỗ.
Phản ví dụ: Prisma findMany và defineNuxtConfig
prisma.user.findMany({ where, orderBy, take }) và defineNuxtConfig({ ... }) là hàng nghìn chỗ gọi mỗi ngày, toàn bộ dùng options object phẳng với default, không có builder nào. Chúng sống khoẻ. Đó là bằng chứng thực tế rằng "nhiều tham số optional" một mình nó không phải lý do để dựng builder.
08 — Tự tay làm
Bài tập
Viết `RetryPolicy` với 4 tham số: `attempts`, `baseMs`, `maxMs`, `jitter`. Ràng buộc: `attempts >= 1`, `baseMs > 0`, `maxMs >= baseMs`, `jitter` trong `[0, 1]`. Làm ba bản: (1) constructor 4 tham số vị trí, (2) options object + default + `buildSlider`-style validator, (3) `RetryPolicy.builder().attempts(5).baseMs(100).build()`. Sau đó **chọn** một bản và viết lý do bằng một câu.
Gợi ý, mở từng cái một:
- Ràng buộc nào là liên field? (
maxMs >= baseMs,jittertrong khoảng.) Ràng buộc nào một field tự biết? - Luật một field chặn ở setter để lỗi trỏ đúng dòng sai. Luật liên field chặn ở
build()vì lúc đó mới đủ dữ kiện. - Bản 2 và bản 3 của bạn khác nhau chỗ nào, nếu
build()chỉ gọi đúng một hàm validate? Trả lời thành thật câu đó chính là bài tập.
Cả ba bản đều pass bài toán validate. Bản 1 loại ngay vì new RetryPolicy(3, 200, 5000, 0.2) không đọc được. Phần lớn dự án nên chọn bản 2: một hàm createRetryPolicy(opts) với default + validate, không state, không allocation thừa. Chọn bản 3 khi cấu hình bị dựng ở nhiều nơi (lib A đặt baseMs, app B đặt attempts, CI đặt maxMs) hoặc khi bạn muốn attempts() fail ngay tại dòng sai. Nói rõ bạn chọn gì là một nửa bài tập — người không phân biệt được hai bản này là người sẽ dựng builder cho mọi thứ.
type RetryOpts = { attempts?: number, baseMs?: number, maxMs?: number, jitter?: number }
class RetryPolicy {
private constructor(
readonly attempts: number,
readonly baseMs: number,
readonly maxMs: number,
readonly jitter: number,
) {}
static builder() { return new RetryPolicyBuilder() }
static create(opts: RetryOpts = {}): RetryPolicy {
const o = { attempts: 3, baseMs: 200, maxMs: 5000, jitter: 0.2, ...opts }
if (o.attempts < 1) throw new Error("attempts phải >= 1")
if (o.baseMs <= 0) throw new Error("baseMs phải > 0")
if (o.maxMs < o.baseMs) throw new Error("maxMs phải >= baseMs")
if (o.jitter < 0 || o.jitter > 1) throw new Error("jitter phải trong [0, 1]")
return new RetryPolicy(o.attempts, o.baseMs, o.maxMs, o.jitter)
}
}
class RetryPolicyBuilder {
#o: RetryOpts = {}
attempts(n: number) { if (n < 1) throw new Error("attempts phải >= 1"); this.#o.attempts = n; return this }
baseMs(n: number) { if (n <= 0) throw new Error("baseMs phải > 0"); this.#o.baseMs = n; return this }
maxMs(n: number) { this.#o.maxMs = n; return this }
jitter(n: number) { this.#o.jitter = n; return this }
build() { return RetryPolicy.create(this.#o) } // luật liên field ở đây
}
const p = RetryPolicy.builder().attempts(5).baseMs(100).maxMs(2000).jitter(0.1).build()
console.log("attempts=" + p.attempts + " baseMs=" + p.baseMs + " maxMs=" + p.maxMs)
console.log("default: " + JSON.stringify(RetryPolicy.create()))09 — Đọc cặp để hiểu bản chất
Pattern liên quan
- Factory MethodCùng họ creational và hay lồng nhau: Factory Method trả lời "dựng loại nào", Builder trả lời "dựng nó như thế nào". Builder của bạn rất nên được gọi từ một factory function.
- PrototypeCặp bài trùng khi bạn cần nhiều biến thể: thay vì build lại từ đầu, clone một cấu hình gốc rồi đổi vài field rồi build tiếp.
- FacadeCả hai đều che độ phức tạp, nhưng Facade che bằng cách **rút gọn API** (gọi 1 lần là xong), Builder che bằng cách **trải dài** việc dựng object qua nhiều bước.
- FlyweightNgược nhau về mục đích: Builder sinh ra nhiều object hợp lệ từ cấu hình khác nhau, Flyweight chia sẻ một instance dùng chung. Đọc cặp này để biết khi nào nên dựng thêm object và khi nào không.