Pattern 22/22 · Behavioral
Visitor Khách thăm
Đặt operation mới lên một cây node đã cố định mà không sửa node nào: mỗi node chỉ tự khai báo "tôi là loại gì", còn toàn bộ logic của operation nằm trong visitor.
01 — Mở đầu bằng code đang hỏng
Vấn đề
Bạn viết calculator cho ô công thức trong spreadsheet. Cây expression có ba loại node: Num, Neg, Add. Mỗi node một method evaluate(). Sạch, gọn, test xong trong một buổi.
Tuần sau cần in lại công thức để hiển thị cho người dùng. Bạn mở ba class, thêm toString(). Tháng sau cần validate (biến chưa khai báo, chia cho 0): mở lại ba class. Quý sau cần transpile sang SQL: mở lại ba class. Mỗi operation mới buộc bạn đụng vào toàn bộ tập node đã đóng băng, chạy lại test của những node không liên quan, và re-review những file mà diff không đổi gì về cấu trúc.
Bạn thử đảo hướng: mỗi operation một file, bên trong là switch (node.kind). Tốt hơn thật — logic của một operation giờ nằm một chỗ, đọc được. Nhưng giờ bài toán lật sang chiều khác: ai đó thêm node Mul, sửa validate.ts và quên export-sql.ts. Nếu node đến từ package khác (plugin system, format file bên ngoài), không có union đóng nào để compiler dò giúp bạn, và bug nằm im tới đúng lúc chạy production.
Vấn đề sâu hơn: cây node là phần ổn định, operation là phần đổi liên tục, nhưng code đang để hai thứ nằm cạnh nhau. Bạn muốn thêm operation = thêm file, không phải sửa năm file đã ổn định. Nói cách khác, bạn muốn Open/Closed theo trục operation, và code hướng node đang đóng theo trục đó.
Còn một cái giá nữa của "nhét nghiệp vụ vào node": mỗi node phải biết hết mọi ngóc ngách nghiệp vụ — định dạng tiền tệ, quy tắc validate, cách sinh SQL. Cấu trúc dữ liệu biến thành chỗ chứa nghiệp vụ, và không dùng lại được ở ngữ cảnh khác: cùng một AST phải được đi khác nhau bởi codegen, bởi linter, bởi formatter, bởi công cụ dịch chuyển phiên bản.
02 — Ý tưởng, chưa động vào code
Giải pháp
Visitor đảo quyền sở hữu operation: operation không nằm trong node, nó nằm trong một object riêng. Mỗi node chỉ còn đúng một method — accept(visitor) — và method đó gần như không bao giờ đổi: nó gọi lại method của visitor tương ứng với loại của chính node. Node trả lời "tôi là loại gì", visitor trả lời "làm gì với loại đó". Hai lần chọn động này là double dispatch, thứ TypeScript và JavaScript không có sẵn.
Kết quả: thêm operation chỉ tốn một visitor mới, node không đổi một dòng. Cái giá — và phải trả có ý thức — là thêm node loại mới buộc bạn sửa interface Visitor và mọi visitor hiện có. Đây là Expression Problem: trong TS/Java không cấu trúc nào mở cả hai chiều miễn phí. Bạn chọn chiều thay đổi nhiều hơn: node cố định + operation nở ra → Visitor. Node nở ra + operation cố định → discriminated union với switch.
Nói thẳng điều ít ai nói: trong app JS/TS, phần lớn cây nên dùng union + switch với default never, vì nó cho bạn exhaustiveness ngay tại compile-time mà không cần một dòng ceremony nào. Visitor thắng trong ba tình huống cụ thể: operation được đóng góp từ bên ngoài (plugin, package khách), operation cần state khi đi cây, và khi một cây bị đi bởi rất nhiều operation bạn muốn dùng chung traversal. Ngoài ba tình huống đó, đừng dùng Visitor chỉ vì nó là một pattern có tên.
03 — Làm thật, mỗi bước một fragment code
Từng bước một
Cây node kiểu "nghiệp vụ nằm trong node"
Phiên bản đầu tiên của mọi cây đều giống nhau: mỗi node biết tự tính, tự render chính nó. Operation thứ nhất luôn ổn. Operation thứ hai là lúc hoá đơn tới.
export class Num {
constructor(readonly value: number) {}
evaluate(): number { return this.value }
}
export class Neg {
constructor(readonly inner: Expr) {}
evaluate(): number { return -this.inner.evaluate() }
}
export class Add {
constructor(readonly left: Expr, readonly right: Expr) {}
evaluate(): number { return this.left.evaluate() + this.right.evaluate() }
}
export type Expr = Num | Neg | Add
new Add(new Num(2), new Neg(new Num(3))).evaluate() // -1toString() nghĩa là mở lại cả ba class.evaluate() không sai. Sai là khi bạn cần method thứ hai, thứ ba — và mỗi lần thêm phải mở mọi node.Phản ứng tự nhiên: discriminated union + switch (và vì sao nó mạnh)
Trước khi học Visitor, hãy thấy rõ lựa chọn thay thế, vì nó thắng phần lớn trường hợp. TypeScript mô tả cây bằng union đóng, và một switch với default gán vào never buộc mọi switch phải xử lý loại node mới — quên case là lỗi build, không phải lỗi runtime.
Vậy Visitor còn gì để bán? Ba thứ, nói ở bước 8: operation từ bên ngoài không nằm trong build của bạn, state khi đi cây, và traversal dùng chung. Nếu không có ba thứ đó, dừng ở bước này là quyết định đúng.
export type Expr =
| { kind: 'num', value: number }
| { kind: 'neg', inner: Expr }
| { kind: 'add', left: Expr, right: Expr }
function assertNever(x: never): never {
throw new Error('case chua xu ly: ' + JSON.stringify(x))
}
export function evaluate(e: Expr): number {
switch (e.kind) {
case 'num': return e.value
case 'neg': return -evaluate(e.inner)
case 'add': return evaluate(e.left) + evaluate(e.right)
default: return assertNever(e) // <- thêm loại node mà quên đây = LỖI BUILD
}
}never chặn được "quên case" khi tập node đóng và bạn build được toàn bộ source. Visitor tồn tại cho phần còn lại.Hợp đồng Visitor: một method cho mỗi loại node
Visitor là một operation, diễn đạt bằng một method cho mỗi loại node. Tham số generic R là kiểu kết quả của operation đó: evaluate trả number, print trả string, typeCheck trả danh sách lỗi.
Vì sao R quan trọng: nó cho phép visitor trả kết quả lên trên thay vì ghi vào node. Không state mutable giấu trong cây nghĩa là visitor gọi lại được, test được, và chạy song song được.
import type { Add, Neg, Num } from './expr'
/** Mot operation = mot interface, mot method cho moi loai node. */
export interface Visitor<R> {
num(n: Num): R
neg(n: Neg): R
add(a: Add): R
}
/** Hop dong cua node: chi mot method, va no khong bao gio doi. */
export interface Expr {
accept<R>(v: Visitor<R>): R
}Double dispatch: node tự chọn method theo loại của nó
Mỗi node implement accept bằng cách gọi ngược lại visitor với this làm đối số. Node không chứa nghiệp vụ; nó chỉ tự khai danh tính.
Hai lần dispatch diễn ra: lần một, polymorphism của OO chọn đúng Num.accept thay vì Add.accept; lần hai, accept chọn v.num thay vì v.add. Visitor đơn độc không làm được lần một (nó không biết node là loại gì), node đơn độc không làm được lần hai (nó không biết operation là gì). Ghép lại mới thành dispatch theo cặp (node, operation).
import type { Expr, Visitor } from './visitor-contract'
export class Num implements Expr {
constructor(readonly value: number) {}
accept<R>(v: Visitor<R>): R { return v.num(this) }
}
export class Neg implements Expr {
constructor(readonly inner: Expr) {}
accept<R>(v: Visitor<R>): R { return v.neg(this) }
}
export class Add implements Expr {
constructor(readonly left: Expr, readonly right: Expr) {}
accept<R>(v: Visitor<R>): R { return v.add(this) }
}accept() là dòng duy nhất node phải viết, và nó sẽ không bao giờ đổi. Node mất hoàn toàn kiến thức nghiệp vụ.Visitor đầu tiên: Evaluate
Visitor đệ quy bằng cách gọi lại accept() trên node con. Cây con được xử lý bằng đúng cơ chế đã xử lý node cha — không vòng lặp thủ công, không switch, không instanceof.
import type { Visitor } from './visitor-contract'
export const evaluate: Visitor<number> = {
num: n => n.value,
neg: n => -n.inner.accept(evaluate),
add: a => a.left.accept(evaluate) + a.right.accept(evaluate),
}
// Client: không cần biết cây có bao nhiêu loại node.
// new Add(new Num(2), new Neg(new Num(3))).accept(evaluate) // -1child.accept(thisVisitor). Nếu traversal có logic riêng (enter/leave, cutoff), nó nằm ở đây — một chỗ, không rải trên các node.Visitor thứ hai: thêm operation mà không sửa node
Operation thứ hai là bài test thật của pattern. Viết print: Visitor<string> — và nhìn lại expr.ts, evaluate-visitor.ts: không file nào bị sửa. Người dùng thư viện của bạn cũng làm được vậy, mà không cần fork.
Ở phiên bản node-chứa-nghiệp vụ, thêm operation nghĩa là mở N class. Ở Visitor, nó là một file mới và một object. Đó là Open/Closed trên trục operation.
import type { Visitor } from './visitor-contract'
export const print: Visitor<string> = {
num: n => String(n.value),
neg: n => '-' + n.inner.accept(print),
add: a => '(' + a.left.accept(print) + ' + ' + a.right.accept(print) + ')',
}
// git status:
// new file: print-visitor.ts
// (không có thay đổi nào khác)
//
// new Add(new Num(2), new Neg(new Num(3))).accept(print) // "(2 + -3)"Chiều ngược lại của đánh đổi: thêm một loại node
Bây giờ thêm node Mul. Bạn phải sửa interface Visitor (thêm mul(m: Mul): R) và sửa mọi visitor đã tồn tại, không trừ cái nào. Với generic R, compiler sẽ liệt kê đủ danh sách chỗ phải sửa — đó là điểm tử tế của thiết kế này, nhưng nó không làm công việc thay bạn.
Có escape hatch: thêm method fallback unknown(node: Expr): R vào hợp đồng. Giá của nó là bạn mất đúng thứ mình đã mua — exhaustiveness im lặng trở thành fallback chạy lúc runtime. Hãy chỉ mở khi node thật sự đến từ plugin.
// 1) Node mới
export class Mul implements Expr {
constructor(readonly left: Expr, readonly right: Expr) {}
accept<R>(v: Visitor<R>): R { return v.mul(this) } // <- Visitor phải có thêm method mul (xem bước 3)
}
// 2) Hợp đồng Visitor phải mở:
// export interface Visitor<R> { num; neg; add; mul(m: Mul): R }
// 3) MỌI visitor phải thêm method — compiler báo động này cho bạn:
// evaluate: { ..., mul: m => m.left.accept(evaluate) * m.right.accept(evaluate) }
// print: { ..., mul: m => '(' + ... + ' * ' + ... + ')' }
// typeCheck:{ ..., mul: m => ... }Khi nào không dùng Visitor: union + switch, và 3 điều kiện Visitor thắng
Bản này làm được hầu hết mọi việc của Visitor với ít khái niệm hơn, ít file hơn, và exhaustiveness vẫn do compiler giữ:
type Expr =
| { kind: 'num', value: number }
| { kind: 'neg', inner: Expr }
| { kind: 'mul', left: Expr, right: Expr }
const evalExpr = (e: Expr): number => {
switch (e.kind) {
case 'num': return e.value
case 'neg': return -evalExpr(e.inner)
case 'mul': return evalExpr(e.left) * evalExpr(e.right)
default: return assertNever(e)
}
}
// Một tree "operation" dưới dạng object vẫn luân chuyển mà không cần accept():
const printExpr = (e: Expr): string => e.kind === 'num' ? String(e.value)
: e.kind === 'neg' ? '-' + printExpr(e.inner)
: '(' + printExpr(e.left) + ' * ' + printExpr(e.right) + ')'04 — Ai nói chuyện với ai
Cấu trúc
- VisitorMột operation, khai báo thành một method cho mỗi loại node. Generic `R` là kiểu kết quả của operation.
- ConcreteVisitor`evaluate`, `print`, `typeCheck`. Giữ state của riêng nó (nếu cần), không đụng vào node.
- Element (Expr)Khai báo `accept(visitor)`. Đây là điểm mở duy nhất cho operation.
- ConcreteElement`Num`, `Neg`, `Add`. Chứa **cấu trúc** + một dòng dispatch. Không chứa nghiệp vụ.
- ObjectStructureCây node (gốc và con), thường là Composite. Visitor đi qua nó bằng `accept` đệ quy.
Client ── tree.accept(evaluate) ──► node (Num | Neg | Add)
│
│ accept(v): "toi la loai gi"
│ → goi v.<loai>(this)
▼
┌────────────────────────────────┐
│ Visitor<R> │
│ num(n): R │
│ neg(n): R │
│ add(a): R │
└────────────────────────────────┘
dispatch lan 1: node ty loai (polymorphism cua OO)
dispatch lan 2: visitor chon hanh vi (operation nam NGOAI node)
────────────────────────────────────────────────────────────
Them OPERATION → them 1 file visitor node khong doi
Them LOAI NODE → sua Visitor + MOI visitor (Expression Problem)05 — Sửa tuỳ ý, chạy ngay tại đây
Chạy thử: ba visitor trên cùng một cây, node không đổi
interface Visitor<R> {
num(n: Num): R
neg(n: Neg): R
add(a: Add): R
}
interface Expr { accept<R>(v: Visitor<R>): R }
class Num implements Expr {
constructor(readonly value: number) {}
accept<R>(v: Visitor<R>): R { return v.num(this) }
}
class Neg implements Expr {
constructor(readonly inner: Expr) {}
accept<R>(v: Visitor<R>): R { return v.neg(this) }
}
class Add implements Expr {
constructor(readonly left: Expr, readonly right: Expr) {}
accept<R>(v: Visitor<R>): R { return v.add(this) }
}
// Operation 1
const evaluate: Visitor<number> = {
num: n => n.value,
neg: n => -n.inner.accept(evaluate),
add: a => a.left.accept(evaluate) + a.right.accept(evaluate),
}
// Operation 2
const print: Visitor<string> = {
num: n => String(n.value),
neg: n => '-' + n.inner.accept(print),
add: a => '(' + a.left.accept(print) + ' + ' + a.right.accept(print) + ')',
}
// Operation 3: thêm vào đây, ba class node trên không đổi một dòng nào.
const size: Visitor<number> = {
num: () => 1,
neg: n => 1 + n.inner.accept(size),
add: a => 1 + a.left.accept(size) + a.right.accept(size),
}
const tree = new Add(new Num(2), new Neg(new Num(3)))
console.log('công thức: ' + tree.accept(print))
console.log('giá trị: ' + tree.accept(evaluate))
console.log('số node: ' + tree.accept(size))công thức: (2 + -3) giá trị: -1 số node: 4
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ấu trúc cây tương đối đóng (AST của một ngôn ngữ, schema form, format file có version) nhưng số operation thì nở mãi: lint, format, transpile, type-check, tối ưu, dịch ngược.
- Operation được đóng góp từ bên ngoài codebase của bạn: plugin ESLint/Babel/PostCSS, package của team khác. Họ không sửa được switch trong source của bạn — nhưng viết được một visitor.
- Operation cần state khi đi cây: scope stack, breadcrumb path, accumulator, collection lỗi. Visitor là object nên nó giữ state một cách tử tế; function thuần thì không.
- Cây heterogeneous (Composite) và bạn muốn một traversal engine dùng chung, thay vì mỗi operation tự viết đệ quy của nó — chỗ traversal có điều kiện (ngắt nhánh, thứ tự ưu tiên) nằm lại một nơi.
- Operation khác nhau trả kiểu khác nhau (
number,string,Diagnostic[]) và bạn muốn từng operation tự kiểm soát kiểu trả về — genericRlàm được việc này. - Cần chạy nhiều operation trên cùng một cây trong một lượt đi (visitor pipeline) — chi phí traversal chỉ trả một lần.
Đừng dùng khi
- Expression Problem. Thêm loại node mới = sửa interface Visitor + mọi visitor. Nếu cây của bạn thêm loại node thường xuyên (schema form, protocol payload), Visitor là một cái tax trả theo tuần. Switch/union mới là bản thắng.
- Visitor phá vỡ encapsulation của node: muốn làm việc, nó cần truy cập node con, field, metadata. Kết quả là node bị ép public hoá mọi thứ — hoặc bạn phải thêm API
children()riêng, và thế là ceremony chồng ceremony. - Trông là pattern "chuyên nghiệp", nhưng đây là một trong những GoF pattern ít cần nhất ở tầng app. Ba loại node, hai operation, một repo: union +
switch+neverngắn hơn, dễ debug hơn, và không file nào gọi là "visitor". - Đừng gom kết quả bằng cách mutate node (
node.result = ...) hay module-level mutable state. Dùng giá trị trả về (R) hoặc một object context truyền xuống — nếu không, visitor không reentrant và test của bạn phụ thuộc thứ tự chạy. - Mỗi visitor tự viết đệ quy, nên logic traversal bị trùng giữa các visitor. Ngay khi traversal có điều kiện thật (ngắt subtree, thứ tự đặc biệt), hãy rút thành một traversal engine rồi cho visitor chỉ nhận node.
- Generic
Rmột-visitor-một-kiểu khiến việc ghép nhiều operation trong một lượt đi trở nên awkward. Thiết kế riêng (danh sách visitor, context chia sẻ) nếu bạn cần đúng cái đó — đừng nhét ba operation vào một visitor "cho tiện".
07 — Bạn đã gặp nó rồi, chỉ là không gọi tên
Trong code thật
Babel plugin
Một Babel plugin là một visitor object: module.exports = () => ({ visitor: { CallExpression(path) { ...}, Identifier(path) { ...} } }). Babel giữ traversal, bạn khai báo hành vi theo loại node. Thêm transform mới không đụng tới package @babel/types.
ESLint rule
Rule export create(context) trả về map method theo loại node ESTree: Literal(node) {...}, "Program:exit"(node) {...}. ESLint đi cây một lần và gọi đúng method — visitor thuần, và đó là lý do hàng nghìn rule bên ngoài tồn tại mà lõi ESLint không biết gì về chúng.
estree-walker (Svelte, Vite plugin)
walk(ast, { enter(node), leave(node) }) tách traversal khỏi hành vi: enter/leave chính là hai method của một visitor, áp dụng cho mọi loại node. Bản "generic visitor" này là lý do compiler Svelte thêm transform mà không sửa walker.
PostCSS plugin
Plugin PostCSS khai báo visitor theo loại node CSS (Declaration, AtRule, Rule, Once, OnceExit) và PostCSS lo việc đi cây. Viết plugin đổi tên custom property chỉ là một object một method — không phải fork PostCSS.
TypeScript compiler API
ts.forEachChild(node, visit) / ts.visitNode là hướng ngược lại: không đóng gói operation thành object, chỉ cho bạn một hàm đi cây và bạn tự quyết trong callback. Nó nhắc bạn rằng traversal và visitor là hai quyết định độc lập.
08 — Tự tay làm
Bài tập
Cho cây form schema `Field | Group | Repeat`. Viết hai operation `validate(node): string[]` và `toText(node): string` bằng Visitor. Sau đó thêm operation `toJSONSchema` **không sửa node**, rồi thêm loại node `Divider` và liệt kê chính xác những file phải sửa.
Gợi ý, mở từng cái một:
- Bắt đầu từ hợp đồng:
interface Visitor<R> { field(f): R; group(g): R; repeat(r): R }. ChọnRcho từng operation —string[]cho validate,stringcho toText. - Node giữ
children(hoặcinner) và gọichild.accept(v)để đệ quy. Đừnginstanceofbên trong visitor — đó là dấu hiệu bạn đang quay lạiswitch. - Với
Divider, đếm cho đủ: 1 file node + 1 interface Visitor + mỗi visitor một method. Con số đó chính là bài học.
Ba method trong interface, ba node implement accept, mỗi operation là một object khớp Visitor<R> và đệ quy bằng accept. Thêm toJSONSchema = một file mới. Thêm Divider = sửa interface Visitor cộng thêm một method vào từng visitor đã có — đúng chiều đắt của Expression Problem.
interface Visitor<R> {
field(f: Field): R
group(g: Group): R
repeat(r: Repeat): R
divider(d: Divider): R
}
type SchemaNode = Field | Group | Repeat | Divider
class Field {
constructor(readonly name: string, readonly required = false) {}
accept<R>(v: Visitor<R>): R { return v.field(this) }
}
class Group {
constructor(readonly title: string, readonly children: SchemaNode[]) {}
accept<R>(v: Visitor<R>): R { return v.group(this) }
}
class Repeat {
constructor(readonly of: SchemaNode) {}
accept<R>(v: Visitor<R>): R { return v.repeat(this) }
}
class Divider {
accept<R>(v: Visitor<R>): R { return v.divider(this) }
}
// Operation 1: tìm field required bên trong
const missingRequired: Visitor<string[]> = {
field: f => (f.required ? [] : [f.name]),
group: g => g.children.flatMap(c => c.accept(missingRequired)),
repeat: r => r.of.accept(missingRequired),
divider: () => [],
}
// Operation 2: in cây dạng text
const toText: Visitor<string> = {
field: f => 'field ' + f.name,
group: g => g.title + ' { ' + g.children.map(c => c.accept(toText)).join('; ') + ' }',
repeat: r => 'repeat(' + r.of.accept(toText) + ')',
divider: () => '---',
}
// Operation 3: KHÔNG động vào node, cũng không động vào 2 visitor trên
const labelCount: Visitor<number> = {
field: () => 1,
group: g => g.children.reduce((n, c) => n + c.accept(labelCount), 0),
repeat: r => r.of.accept(labelCount),
divider: () => 0,
}
const form = new Group('checkout', [new Divider(), new Field('email', true), new Repeat(new Field('line'))])
console.log('thieu required: ' + JSON.stringify(form.accept(missingRequired)))
console.log(form.accept(toText))
console.log('so label: ' + form.accept(labelCount))09 — Đọc cặp để hiểu bản chất
Pattern liên quan
- CompositeVisitor hầu như luôn đi kèm Composite: cây node đồng nhất về hợp đồng nhưng khác nhau về hành vi, và Visitor là cách "thêm hành vi từ ngoài" cho cây đó mà Composite không tự chứa nghiệp vụ.
- IteratorCả hai tách "đi qua cấu trúc" khỏi "làm gì đó". Iterator trả từng phần tử cho client (trình điều khiển là client); Visitor nhận object operation và tự đi hết (trình điều khiển là cấu trúc).
- StrategyVisitor là Strategy cho **cả cây** thay vì cho một node: một object operation được chọn lúc chạy. Khác nhau ở chỗ Visitor cần double dispatch để chọn đúng method theo loại node.
- Template MethodTemplate Method giữ traversal trong base class và mở một bước; Visitor đẩy **toàn bộ** operation ra ngoài cây. Muốn sửa traversal, Template Method; muốn thêm operation, Visitor.