Pattern 09/22 · Behavioral

Command Lệnh

Gói "việc cần làm" (tham số, đối tượng bị thao tác, cách làm, cách hoàn tác) vào một object, để bạn cất nó vào hàng đợi, log lại, gửi đi, thử lại, chạy lại hoặc undo — thay vì gọi function rồi mất hút.

Hành vi●●○14 phút đọc8 bướccòn gọi: Action, Task, Transaction
undo redoqueueretryevent sourcingbehavioralmacroserializable

01 — Mở đầu bằng code đang hỏng

Vấn đề

Bạn viết một editor nhỏ. insert(at, text) và remove(at, n) sửa thẳng vào chuỗi text, nút "Gửi" gọi api.send(text). Mọi thứ chạy tốt cho tới khi ai đó nói đúng ba chữ: "phải undo được".

Bản đầu ai cũng viết giống nhau: const last = text trước khi sửa, undo thì text = last. Nó chạy. Rồi "undo 2 lần", rồi "redo", rồi "tooltip của nút undo phải hiện tên hành động sắp bị hoàn tác". last thành history: string[] — copy nguyên văn bản sau mỗi cú gõ. RAM tăng, và quan trọng hơn: lịch sử của bạn chỉ chứa ảnh chụp, không chứa việc đã làm, nên nó không thể hiện tên hành động, không gộp được 40 cú gõ thành một lần undo, không giải thích được gì cho audit log.

Cùng lúc, ba yêu cầu khác kéo tới. Nút "Gửi" phải retry ba lần khi mạng chập chờn. Khi mất mạng, user vẫn được bấm, việc sẽ chạy khi có mạng lại. Admin phải xem được "ai đổi đơn này thành huỷ, lúc nào". Và một refactor 40 file phải hoàn tác cả cụm, không phải 40 lần Ctrl+Z.

Bạn có thể viết bốn cơ chế riêng: một mảng snapshot, một vòng retry, một hàng đợi localStorage, một bảng audit. Bốn chỗ này sẽ lệch nhau ngay tuần sau, vì mỗi chỗ tự nghĩ ra một cách mô tả "việc vừa xảy ra".

Bốn yêu cầu đó là một yêu cầu: hành động phải là một object sống lâu hơn lần gọi function. Khi nó là object, bạn xếp hàng được, ghi log được, gửi qua mạng được, hoàn tác được — và cả bốn tính năng chỉ phải viết một lần, cho mọi loại hành động.

02 — Ý tưởng, chưa động vào code

Giải pháp

Command là: thay vì doThing(args), bạn dựng một object mô tả việc đó, rồi mới chạy nó. Object mang theo tham số, trỏ tới đối tượng bị thao tác, biết execute() và — nếu hoàn tác được — biết undo(). Người tạo lệnh và người chạy lệnh không còn là một.

Phần còn lại của hệ thống chỉ nói chuyện với hợp đồng đó. Invoker (nút bấm, hàng đợi, cron, worker) gọi execute() vào lúc nó muốn, không biết gì về editor hay DB. Muốn thêm tính năng "chờ 5 giây rồi chạy", "chạy lại 3 lần khi lỗi", "ghi log", bạn sửa invoker — mọi command tự có, không cái nào phải đổi.

Trong TS, một command thường là object { label, execute(), undo() }, hoặc dạng dữ liệu thuần { type, payload } như Redux action. Dạng sau quan trọng hơn nó tưởng: serialise được thì gửi qua worker, lưu vào DB, replay để dựng lại state. Redux dispatch(action), job queue (BullMQ), queueMicrotask, ProseMirror/Slate history — tất cả cùng hình dạng này.

03 — Làm thật, mỗi bước một fragment code

Từng bước một

1

Viết bản "gọi rồi mất hút" trước đã

Đây là code ai cũng viết. Nó không sai — nó chỉ không giữ lại dấu vết gì. Sau khi insert() chạy xong, không còn ai biết việc gì vừa xảy ra, ai gây ra, và làm ngược lại bằng cách nào.

tseditor-v1.ts
let text = ''
let last = ''                       // "undo" một bước

function insert(at: number, s: string) {
  last = text                       // snapshot nguyên văn bản
  text = text.slice(0, at) + s + text.slice(at)
}

function undo() { text = last }

insert(0, 'xin')
insert(3, ' chào')
undo()                              // về "xin"
undo()                              // vẫn "xin" <- chỉ có một bước undo
Snapshot toàn bộ state: tốn RAM, không tên, không redo, không gộp, không log.
ChốtNếu lịch sử của bạn chứa state thay vì hành động, bạn mất khả năng giải thích, gộp và hoàn tác một cách có ý nghĩa.
2

Hợp đồng Command: execute, và undo nếu hoàn tác được

Một interface hai method. label không bắt buộc về mặt máy móc, nhưng nó là thứ biến lịch sử thành thứ con người đọc được — tooltip của nút undo, audit log, devtools. Hãy coi nó là bắt buộc.

Chú ý undo() để tuỳ chọn (undo?()): có những việc không hoàn tác được bằng logic — gửi email, trừ tiền, gọi webhook. Giả vờ mọi thứ undo được là nguồn của bug kiểu "undo xong rồi nhưng tiền vẫn bị trừ", nên hãy khai báo thật: undo là method tuỳ chọn.

tscommand.ts
export interface Command {
  /** Đọc được bởi con người: 'insert "chào" @3', 'status o-1 -> cancelled' */
  readonly label: string
  execute(): void
  /** Bỏ trống nếu việc này không hoàn tác được (đã gửi email, đã trừ tiền). */
  undo?(): void
}
ChốtCommand tách "làm gì" khỏi "làm lúc nào và ai làm". Đó là toàn bộ lý do nó tồn tại.
3

Biến mỗi thao tác thành command: tham số đóng băng lúc tạo

Mỗi thao tác trở thành một factory trả về command. Điểm then chốt: command giữ diff (tại vị trí 3, chèn " chào"), không giữ ảnh chụp toàn bộ state. Nó rẻ, và nó mô tả đúng ý định.

before được đọc lúc dựng command, tức là lúc tham số đóng băng. Với editor một người dùng thì đúng. Khi có đồng sáng tác hoặc autosave chen vào giữa, "trạng thái cũ" bạn bắt lúc tạo lệnh có thể đã lỗi thời — lúc đó phải snapshot trong execute(), hoặc chuyển sang transform/OT/CRDT. Biết trước giới hạn này saves bạn một đêm trực.

tsinsert-command.ts
const doc = { text: '' }

export const insert = (at: number, s: string): Command => ({
  label: 'insert "' + s + '" @' + at,
  execute: () => { doc.text = doc.text.slice(0, at) + s + doc.text.slice(at) },
  undo: () => { doc.text = doc.text.slice(0, at) + doc.text.slice(at + s.length) },
})

export const remove = (at: number, n: number): Command => {
  const removed = doc.text.slice(at, at + n)   // nhớ nội dung TRƯỚC khi xoá
  return {
    label: 'remove "' + removed + '" @' + at,
    execute: () => { doc.text = doc.text.slice(0, at) + doc.text.slice(at + n) },
    undo: () => { doc.text = doc.text.slice(0, at) + removed + doc.text.slice(at) },
  }
}
ChốtCommand lưu ý nghĩ ngược của mình (inverse), không lưu toàn bộ thế giới. Đó là lý do history của editor không ngốn RAM.
4

Invoker: history + con trỏ, và luật "lệnh mới khai tử redo"

Undo/redo là hai con trỏ trên một mảng, không phải hai mảng. run push command rồi đẩy con trỏ lên; undo lùi con trỏ rồi gọi undo(); redo tiến con trỏ rồi gọi execute(). Xin đừng viết hai stack riêng — đó là nơi bug "redo mất lệnh" sinh ra.

Có đúng một quy tắc cần nhớ: khi người dùng gõ lệnh mới ở giữa history, mọi thứ phía sau con trỏ chết. Bạn undo ba bước rồi gõ tiếp — ba bước bị redo đó không còn tồn tại. Viết history.splice(cursor) một dòng, và giải thích nó cho product ngay hôm nay để tuần sau khỏi phải cãi.

tshistory.ts
const history: Command[] = []
let cursor = 0

export function run(cmd: Command) {
  cmd.execute()
  history.splice(cursor)   // lệnh mới khai tử mọi thứ phía sau con trỏ
  history.push(cmd)
  cursor++
}

export function undo() {
  if (cursor === 0) return
  const cmd = history[--cursor]
  cmd.undo?.()
}

export function redo() {
  if (cursor === history.length) return
  const cmd = history[cursor++]
  cmd.execute()
}
ChốtInvoker không biết gì về editor. Nó chỉ biết "object này có execute() và có thể có undo()" — nên nó dùng được cho mọi loại lệnh.
5

Chạy thử: undo một macro, redo, và redo bị khai tử

Ba dòng dưới đây mô tả đủ vòng đời: gõ hai lệnh, chạy một macro bốn cú gõ nhưng undo một lần quay lại đúng chỗ cũ, redo lại, rồi lệnh mới xoá sạch nhánh redo.

tsmain.ts
run(insert(0, 'xin'))
run(insert(3, ' chào'))
run(macro('đổi tên biến', [insert(8, ' bạn'), insert(12, '!')]))
undo(); undo(); redo()
run(insert(0, '>> '))
redo()
console
run   insert "xin" @0      | xin
run   insert " chào" @3    | xin chào
run   đổi tên biến         | xin chào bạn!
undo  đổi tên biến         | xin chào
undo  insert " chào" @3    | xin
redo  insert " chào" @3    | xin chào
run   insert ">> " @0      | >> xin chào
redo  (không còn gì)       | >> xin chào
6

Macro: composite command, undo cả cụm như một lần

Vì macro cũng là Command, invoker không phân biệt được nó với một lệnh nguyên tử. Paste 400 ký tự, rename hàng loạt, "chuyển 5 đơn sang huỷ" — tất cả thành một bước undo. Đây là thứ mà history dạng snapshot không bao giờ làm đúng, vì snapshot không biết 40 thay đổi kia thuộc về một hành động.

Chỉ cần nhớ: undo phải chạy ngược thứ tự, và undo() của macro phải coi như một hành động — nếu invoker log từng lệnh con, audit log của bạn sẽ nói xạo.

tsmacro.ts
export const macro = (label: string, cmds: Command[]): Command => ({
  label,
  execute: () => cmds.forEach(c => c.execute()),
  undo: () => [...cmds].reverse().forEach(c => c.undo?.()),
})

// Composite: Command là một, Command[] là nhiều, cùng một hợp đồng.
// Vì cùng hợp đồng nên macro lồng được macro, và invoker không đổi một dòng nào.
ChốtCùng một hợp đồng cho "một" và "nhiều" — Command đội lốt Composite, và đó là cách paste 400 ký tự undo một phát.
7

Command dạng dữ liệu: serialise được thì queue, retry, replay được

Bỏ hai closure đi, giữ lại mô tả: { type, at, text }. Lúc này command là JSON: ghi xuống DB, gửi qua postMessage sang worker, đẩy vào BullMQ, cất vào localStorage khi offline. Một hàm apply(doc, cmd) duy nhất chạy nó, và invert(cmd) sinh lệnh ngược. History trở thành dữ liệu — bạn time-travel, replay, diff, stream sang thiết bị khác.

Đây chính xác là Redux: action là command dạng dữ liệu, dispatch là invoker, reducer là receiver; DevTools làm được time-travel vì action là object thuần. Nó cũng là nền của event sourcing: state = fold của danh sách command, nên bạn dựng lại state bất cứ lúc nào mà không cần lưu snapshot.

Cái giá: apply và invert trở thành API contract. Thêm field là breaking change với lệnh đã lưu trong DB. Thiết kế shape một lần, version nó.

tsdata-command.ts
type Cmd = { type: 'insert', at: number, text: string }
        | { type: 'remove', at: number, text: string }

export const apply = (doc: { text: string }, c: Cmd): void => {
  if (c.type === 'insert') doc.text = doc.text.slice(0, c.at) + c.text + doc.text.slice(c.at)
  else doc.text = doc.text.slice(0, c.at) + doc.text.slice(c.at + c.text.length)
}

/** Lệnh ngược, cũng là dữ liệu -> undo được cả sau khi reload. */
export const invert = (c: Cmd): Cmd =>
  c.type === 'insert'
    ? { type: 'remove', at: c.at, text: c.text }
    : { type: 'insert', at: c.at, text: c.text }

// JSON.stringify(cmd) -> hàng đợi / worker / offline queue / event store
ChốtCommand có closure thì chạy nhanh, command là dữ liệu thì sống sót qua restart và đi được qua network. Chọn theo chỗ bạn cần lệnh sống bao lâu.
8

Invoker phiên bản production: retry, offline, và lệnh không undo được

Đây là chỗ Command trả tiền. Toàn bộ đống dưới nằm trong invoker: mọi command có retry, backoff, giới hạn lịch sử, và log audit mà không command nào phải viết lại mấy dòng đó. Thêm "chạy khi có mạng" = thêm 5 dòng invoker, không phải 40 patch rải rác.

Nhưng hãy thành thật về undo. Lệnh đã gửi email, đã trừ tiền, đã gọi webhooks của đối tác thì không có inverse. Đừng bịa undo() để hoàn thành interface; dùng compensation (một lệnh mới trung hoà tác động) và để undo trống. Một undo() biết "chạy ngược" giả là một bug đã được thiết kế sẵn.

tsinvoker.ts
const MAX_HISTORY = 100   // history là RAM, phải có trần

export async function runWithRetry(cmd: Command, attempts = 3): Promise<boolean> {
  for (let i = 1; i <= attempts; i++) {
    try {
      cmd.execute()
      history.push(cmd)
      if (history.length > MAX_HISTORY) history.shift()
      return true
    }
    catch (e) {
      if (i === attempts) return false   // log cmd.label, KHÔNG log cmd.undo
    }
  }
  return false
}
ChốtTrước khi Command hoá, tự hỏi: lệnh này có cần sống lâu hơn lần gọi function không? Nếu không, một function là đủ, và nó rẻ hơn.

04 — Ai nói chuyện với ai

Cấu trúc

  • CommandHợp đồng: `label` + `execute()`, và `undo()` nếu hoàn tác được. Không biết gì về UI, DB, hay lệnh khác.
  • ConcreteCommand`insert`, `remove`, `updateStatus`, `macro`. Giữ tham số đã đóng băng lúc tạo và trỏ tới receiver.
  • ReceiverVật bị thao tác thật: `doc.text`, một row trong DB, danh sách đơn hàng. Không biết lệnh tới từ nút nào.
  • InvokerNút bấm, hàng đợi, cron, worker, DevTools. Chọn **thời điểm** chạy, lo retry/offline/history. Không chọn **cách làm**.
  • History / CaretMảng command + con trỏ. Quyết định undo/redo còn gì, và khai tử nhánh redo khi có lệnh mới.
   ┌───────────────┐  run(cmd)   ┌─────────────────────────┐
   │ Invoker       │────────────►│ Command                 │
   │ nút, queue,   │◄────────────│  + execute()            │
   │ cron, worker  │  ok / error │  + undo()   (tuỳ chọn)  │
   └──────┬────────┘             └────────────┬────────────┘
          │ push(cmd)                         │ chạm vào
          ▼                                   ▼
  history: [c1, c2, c3, c4]            Receiver: doc.text, row
                ▲
             caret ── undo: caret--  rồi cmd.undo()
                    ── redo: cmd.execute()  rồi caret++

  Lệnh mới khi caret ở giữa history -> splice(caret), redo chết.

05 — Sửa tuỳ ý, chạy ngay tại đây

Chạy thử: undo/redo với macro một lần undo

tsdemo.ts
type Command = { readonly label: string, execute(): void, undo(): void }

const doc = { text: '' }
const history: Command[] = []
let cursor = 0

const insert = (at: number, s: string): Command => ({
  label: 'insert "' + s + '" @' + at,
  execute: () => { doc.text = doc.text.slice(0, at) + s + doc.text.slice(at) },
  undo: () => { doc.text = doc.text.slice(0, at) + doc.text.slice(at + s.length) },
})

/** Macro = composite: 4 cú gõ, nhưng người dùng chỉ undo một lần. */
const macro = (label: string, cmds: Command[]): Command => ({
  label,
  execute: () => cmds.forEach(c => c.execute()),
  undo: () => [...cmds].reverse().forEach(c => c.undo()),
})

const log = (op: string, what: string) => console.log(op.padEnd(6) + what.padEnd(21) + '| ' + doc.text)

function run(cmd: Command) {
  cmd.execute()
  history.splice(cursor) // lệnh mới khai tử mọi thứ phía sau con trỏ
  history.push(cmd)
  cursor++
  log('run', cmd.label)
}
function undo() {
  if (cursor === 0) return log('undo', '(hết lịch sử)')
  const cmd = history[--cursor]; cmd.undo(); log('undo', cmd.label)
}
function redo() {
  if (cursor === history.length) return log('redo', '(không còn gì)')
  const cmd = history[cursor++]; cmd.execute(); log('redo', cmd.label)
}

run(insert(0, 'xin'))
run(insert(3, ' chào'))
run(macro('đổi tên biến', [insert(8, ' bạn'), insert(12, '!')]))
undo(); undo(); redo()
run(insert(0, '>> '))
redo()
console
run   insert "xin" @0      | xin
run   insert " chào" @3    | xin chào
run   đổi tên biến         | xin chào bạn!
undo  đổi tên biến         | xin chào
undo  insert " chào" @3    | xin
redo  insert " chào" @3    | xin chào
run   insert ">> " @0      | >> xin chào
redo  (không còn gì)       | >> xin chào

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ần undo/redo, hoặc cần hoàn tác nhiều thay đổi như một hành động (paste, refactor hàng loạt, "huỷ 5 đơn cùng lúc").
  • Việc cần làm phải chờ: job queue, offline queue, retry với backoff, rate-limit, chạy theo lịch, chạy trong worker.
  • Bạn cần ghi lại chính xác việc đã xảy ra để audit, replay, hoặc dựng lại state (event sourcing, migration, sync đa thiết bị).
  • Lệnh được tạo ở một nơi, chạy ở nơi khác: UI tạo, worker chạy, server thực thi. Object hoá là cách duy nhất gửi nó đi.
  • UI cần biết lệnh có chạy được không trước khi chạy (canExecute) để bật/tắt nút, hoặc cần preview thay đổi trước khi apply.

Đừng dùng khi

  • Over-engineering. Một hàm pure, gọi ngay, không undo, không queue, không log? Viết function. Command chỉ đáng giá khi hành động cần sống lâu hơn lượt gọi — nếu không, bạn đang trả giá của một abstraction không dùng tới.
  • Không phải mọi lệnh đều có inverse. Gửi email, trừ tiền, webhook cho đối tác: đừng nhét undo() giả vào interface. Khai báo undo?() và dùng compensation (một lệnh mới trung hoà tác động) thay vì hoàn tác.
  • Command giữ reference và vị trí cũ. Trong môi trường có đồng sáng tác, autosave, hoặc người khác sửa giữa lúc tạo lệnh và lúc undo, at: 3 có thể trỏ vào chỗ khác. Undo an toàn cần transform (OT/CRDT), không phải inverse đơn giản.
  • History là memory leak hợp pháp: một nghìn command to = RAM của user. Giới hạn độ sâu (editor thật đều làm vậy), hoặc lưu diff/inverse thay vì snapshot.
  • Command đã gửi lên server thì undo cục bộ là vô nghĩa — state thật ở server. Lúc đó command trở thành API contract giữa hai bên, và đổi shape của nó là breaking change với lệnh đã nằm trong DB.

07 — Bạn đã gặp nó rồi, chỉ là không gọi tên

Trong code thật

Redux / Pinia: dispatch(action)

Action là command dạng dữ liệu thuần { type, payload }; reducer là receiver; dispatch là invoker. Nhờ action là object serialise được, Redux DevTools mới làm time-travel, replay và diff action — ba thứ chỉ khả thi khi "việc cần làm" là dữ liệu chứ không phải closure.

Job queue trong Node: BullMQ, graphile-worker, queueMicrotask

Một job là command đã serialise: tên lệnh + tham số. Worker ở process khác execute() nó, còn retry/backoff/attempts/offline nằm hết ở invoker. Cùng cấu trúc ở quy mô vi mô: queueMicrotask(fn), requestIdleCallback(fn), setTimeout(fn) — bạn đưa lệnh cho invoker chạy lúc khác.

History của editor: ProseMirror, Slate, Monaco/CodeMirror

ProseMirror mỗi Step có invert(doc); plugin history giữ transaction để undo/redo. Slate tính inverse của Operation. CodeMirror/Monaco quản lý ChangeSet/edit ops. Ctrl+Z hoàn tác cả một lần paste nhiều dòng vì nhiều op được gộp thành một command — chính là macro command.

document.execCommand(commandId)

API cũ của trình duyệt mà cái tên nói lên tất cả: bạn gửi một mô tả lệnh ("bold", "insertImage") cho trình duyệt — receiver là editor nội bộ của browser, invoker là browser, và undo do browser giữ. Nó đã bị khai tử vì quá nhiều thứ bị trừu tượng hoá khỏi tầm kiểm soát của bạn — một bài học về Command khi bạn không sở hữu receiver.

08 — Tự tay làm

Bài tập

Viết command `updateStatus(id, next)` cho trang admin: `execute()` đổi trạng thái đơn hàng, `undo()` trả về trạng thái **cũ**, `label` đủ rõ để làm tooltip nút undo. Sau đó cho nó chạy chung history với các lệnh text ở trên và chứng minh một macro `updateStatus` undo cả cụm.

Gợi ý, mở từng cái một:

  1. Trạng thái cũ phải đọc lúc nào: lúc dựng command hay lúc execute()? Mỗi lựa chọn đúng trong một tình huống nào?
  2. label nên chứa id và cả giá trị cũ lẫn mới. Tooltip undo tốt là tooltip nói được "quay lại thành gì".
  3. Macro không cần biết updateStatus — nó chỉ cần mảng Command[]. Đó là lý do hai loại lệnh khác nhau nằm vừa history.

Factory updateStatus(id, next) đọc before khi được gọi (tham số đóng băng), trả về command với execute ghi giá trị mới, undo ghi lại before. Vì nó khớp hợp đồng Command, history và macro nhận nó mà không cần đổi dòng nào. Nếu có người khác sửa song song, hãy chuyển việc đọc before vào trong execute() và lưu vào closure của chính lần chạy đó.

tsbai-tap.ts
type Order = { id: string, status: string }
const db = new Map<string, Order>([['o-1', { id: 'o-1', status: 'new' }]])

const updateStatus = (id: string, next: string): Command => {
  const before = db.get(id)?.status ?? '(không tồn tại)'   // đóng băng lúc tạo
  return {
    label: id + ': ' + before + ' -> ' + next,
    execute: () => { db.set(id, { id, status: next }) },
    undo: () => { db.set(id, { id, status: before }) },
  }
}

run(updateStatus('o-1', 'paid'))              // o-1: new -> paid
run(updateStatus('o-1', 'shipped'))           // o-1: paid -> shipped
undo()                                        // về paid
run(macro('huỷ hàng loạt', [
  updateStatus('o-1', 'cancelled'),
  updateStatus('o-2', 'cancelled'),
]))
undo()                                        // cả cụm quay lại, một lần bấm

09 — Đọc cặp để hiểu bản chất

Pattern liên quan

  • MementoMemento lưu **trạng thái** để quay về; Command lưu **hành động** để làm/hoàn tác. `undo()` của Command thường cầm một Memento bên trong — hai pattern này hay là cặp bài trùng.
  • CompositeMacro command là Composite đúng nghĩa: một lệnh và một danh sách lệnh cùng hợp đồng, nên invoker đối xử như nhau và macro lồng được macro.
  • StrategyStrategy trả lời "làm việc này **bằng cách nào**" và được chọn rồi chạy. Command trả lời "việc gì, với tham số nào" và có thể không bao giờ chạy (bị huỷ, bị replay).
  • BuilderCả hai gom thứ gì đó thành object để dùng sau. Builder tích luỹ **dữ liệu** rồi build một lần; Command tích luỹ **hành vi** và có thể chạy nhiều lần, xếp hàng, hoặc hoàn tác.