Pattern 08/22 · Structural

Adapter Bộ chuyển đổi

Chèn một lớp dịch ở ranh giới: nó nhận dữ liệu và lời gọi theo hình dạng của người khác (API bên thứ ba, module cũ, DTO) rồi trả về đúng hợp đồng nội bộ, để phần lõi của hệ thống chỉ biết duy nhất kiểu dữ liệu của mình.

Cấu trúc●●○13 phút đọc8 bướccòn gọi: Wrapper, Translator, Anti-Corruption Layer (bản quy mô module)
adapterdtoapilegacyanti-corruption layersnake caserefactor

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

Vấn đề

Admin của một shop. Trang danh sách đơn: const { data } = await useFetch("/legacy/orders"), thế rồi trong template người ta viết order.created_at, order.line_items[i].unit_price. data là any — $fetch không biết gì về schema — nên TypeScript đứng ngoài cuộc. unit_price phía backend trả về là string "199000" tính bằng cent, vì năm 2019 ai đó copy từ database column.

Rồi một bạn muốn tính giá đã gồm VAT: order.unit_price * 1.1. JS thấy string thì tự ép kiểu sang số, ra 218900, và template in ra "218900đ". Con số đúng về mặt phép tính, sai 100 lần về mặt đơn vị, và không một công cụ nào báo lỗi. Đó là thứ bug chỉ lộ ra lúc sao kê cuối tháng.

Backend ra v2: created_at đổi thành createdAt, line_items đổi thành items. Bạn grep được 47 chỗ trong 19 file, sửa 44, còn 3 chỗ nằm trong template — nơi any từng che chở thì giờ không ai tìm thấy. Ba trang trắng xoá, merge tuần đó phải revert. Lý do gốc: hình dạng JSON của người khác đang đóng vai trò kiểu dữ liệu của hệ thống bạn, nên mọi thay đổi ở phía họ trở thành refactor ở phía bạn.

Payment cũng vậy. Bạn gọi thẳng stripe.paymentIntent(...) trong component checkout, rồi đưa client_secret xuống prop của nút "Thanh toán". Nay product đổi sang vendor khác: bạn phải sửa UI, và component đó không test được vì mỗi lần render là một lần gọi network. Song song đó là một util lib cũ getThing(id, cb) kiểu callback mà bạn không được sửa (3 team khác đang dùng), nên mỗi nơi gọi tự viết wrapper promise — 5 biến thể, mỗi biến thể xử lý lỗi một kiểu.

Đứng nhìn lại: kiến thức về hình dạng dữ liệu đang rải khắp nơi. Không ai trả lời được câu "một Order trong hệ thống này là gì?" — câu trả lời thật là "tuỳ API hôm nay trả gì". Và vì ranh giới không có gate, any len vào tận domain, mutation của vendor trở thành mutation trong state của Vue, và refactoring là công trình khảo cổ.

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

Giải pháp

Adapter là thành phần cài đặt hợp đồng nội bộ nhưng bên trong gọi sang cái API có hình dạng khác. Ba vai: Target là hợp đồng code bạn muốn dùng (Order, PaymentGateway), Adaptee là thứ đang tồn tại (endpoint v1, lib callback, SDK vendor), Adapter là chỗ dịch giữa hai bên. Quy tắc sắt: hình dạng của Adaptee chỉ được phép tồn tại trong một file — file adapter.

Có hai chiều. Inbound (toDomain(dto) / mapResponse) cho đường đọc, và ở TS nó còn là gate: chỗ duy nhất unknown được kiểm tra rồi hẹp lại thành domain type, nên sau ranh giới mọi thứ có type thật. Outbound (toApi(domain) / mapRequest) cho đường ghi, vì POST/PATCH cũng cần đúng tên field, đúng đơn vị, và không mang theo field nội bộ.

Giá của nó là thật: thêm một file mỗi ranh giới, thêm một bảng mapping phải giữ đồng bộ. Nó đáng khi hình dạng không thuộc quyền quyết định của bạn (API người khác, lib cũ, dữ liệu đã lưu), khi bạn cần implementation thứ hai (fake để test, vendor thứ hai), hoặc khi hai hệ thống phải cùng tồn tại lúc migrating. Nếu chỉ có một hình dạng và nó đã là hợp đồng của bạn, Adapter là thuế — đọc mục pitfalls trước khi viết.

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

Từng bước một

1

Vẽ ranh giới: chỗ nào dữ liệu của người khác bước vào

Trước khi viết gì, liệt kê mọi điểm dữ liệu ngoại lai đi vào: $fetch/useFetch tới API, SDK vendor (payment, SMS, maps), message queue consumer, file import CSV/Excel, localStorage/IndexedDB, và lib cũ bạn không sửa được. Mỗi điểm là một adapter tiềm năng — hoặc một chỗ nên bỏ trắng, nếu hình dạng của nó đã là hợp đồng của bạn.

Đây là bản "before" điển hình. Để ý số lượng chỗ phải biết chi tiết của endpoint: tên snake_case, giá tính bằng cent, ngày dạng string, và một vòng items mà domain không quan tâm.

tsOrderList.vue (before)
const { data } = await useFetch("/legacy/orders")   // data: any

// XXX: data: any -> không tooling nào biết payload thật trông ra sao
// XXX: bốn "kiến thức về endpoint" đang sống ngay trong code render:
//   order.created_at                       <- tên CỦA HỌ, không phải của mình
//   order.line_items[i].unit_price         <- string "199000", đơn vị cent
//   order.customer.full_name
//   (order.vat_rate * order.unit_price)    <- JS tự ép string -> number, âm thầm

// XXX: dòng này chạy "đúng", và vẫn sai 100 lần:
const total = data.value?.orders
  .flatMap(o => o.line_items)
  .reduce((s, li) => s + li.unit_price * 1.1, 0)     // 199000 * 1.1 = 218900 "đ"
Bốn kiến thức về endpoint nằm trong code render. Đổi endpoint = sửa code render.
ChốtNếu UI biết tên field của API, thì UI đã là một phần của API đó. Adapter tồn tại để cắt sợi dây này.
2

Định nghĩa hợp đồng nội bộ trước khi viết bất kỳ dòng dịch nào

Hãy mô tả domain bằng ngôn ngữ của bạn, không bằng cột của họ. Money (VND, số nguyên), publishedAt (kiểu ngày, hoặc ISO string có chủ đích), authorName chứ không phải author_name. Đơn vị phải nằm trong tên kiểu, vì đó chính là thứ bug "100 lần" đánh cắp.

Viết type này trước khiến mọi mapping sau đó trở thành một bài toán đóng: "tôi có LegacyOrderDto, tôi cần Order, được phép throw nếu không đủ dữ liệu". Không có type đích, mapping là công việc không có định nghĩa hoàn thành.

tsdomain/order.ts
/** VND, số nguyên. Tên kiểu mang đơn vị: bug "cent vs dong" khó chui lọt hơn. */
export type Money = number & { readonly __unit: "VND" }
export const vnd = (n: number): Money => n as Money

export interface OrderLine {
  readonly sku: string
  readonly qty: number
  readonly unitPrice: Money
}

export interface Order {
  readonly id: string
  readonly customerName: string
  readonly placedAt: Date
  readonly lines: OrderLine[]
  readonly status: "new" | "cancelled"
}
readonly + unit trong tên kiểu: hợp đồng nội bộ không chỉ khác tên, nó phải khác chất lượng so với DTO.
ChốtDomain type mô tả nghiệp vụ của bạn. Nếu nó trông giống hệt JSON của đối tác (kể cả tên field), bạn chưa có hợp đồng nội bộ — bạn đang alias DTO.
3

Inbound adapter: gate từ unknown xuống domain

Adapter một chiều là một hàm thuần: vào DTO, ra domain, throw khi dữ liệu không như hợp đồng. Đừng as Order: cast không kiểm tra gì cả, nó chỉ làm compiler im lặng và biến dữ liệu rác thành lỗi ở 3 tầng gọi sau.

Phần giá trị nhất không phải dòng authorName: d.author_name — mà là phần chặn: unknown → kiểm tra → domain. Đây là lần duy nhất trong hệ thống bạn được phép tin vào một cái tên field của người khác.

tsapi/legacy-order-mapper.ts
import type { Order, OrderLine } from "~/domain/order"

/** Hình DẠNG CỦA HỌ: chỉ file này được phép biết nó tồn tại. */
interface LegacyOrderDto {
  id: number
  created_at: string
  customer?: { full_name?: string }
  line_items?: Array<{ sku: string, qty: number, unit_price: string }>
  state?: string
}

const isDto = (x: unknown): x is LegacyOrderDto =>
  typeof x === "object" && x !== null
  && typeof (x as LegacyOrderDto).id === "number"
  && typeof (x as LegacyOrderDto).created_at === "string"

export function toDomain(raw: unknown): Order {
  if (!isDto(raw)) throw new Error("payload không khớp LegacyOrderDto")

  const lines: OrderLine[] = (raw.line_items ?? []).map(li => ({
    sku: li.sku,
    qty: Number(li.qty),
    unitPrice: Number(li.unit_price) as OrderLine["unitPrice"], // cent -> VND: RÕ một chỗ
  }))

  return {
    id: String(raw.id),
    customerName: raw.customer?.full_name ?? "(khách lẻ)",
    placedAt: new Date(raw.created_at),
    lines,
    status: raw.state === "cnl" ? "cancelled" : "new",
  }
}
unit_price là cent hay VND giờ chỉ là câu hỏi của đúng một dòng. Ở UI không còn ai phải đoán.
ChốtAdapter inbound là nơi any chết. Sau nó, không file nào được cast, không file nào được đọc snake_case.
4

Outbound adapter: dịch ngược, và chỉ gửi những gì họ cần

Đường ghi bị bỏ quên nhiều nhất. Bạn POST nguyên một domain object, backend lạ cười vì không hiểu placedAt, và dữ liệu user vừa nhập biến mất im lặng. toApi trả đúng danh sách field endpoint cần, đúng format, đúng đơn vị.

Chiều này còn là chỗ chặn over-posting: field nội bộ (status do admin set, internalNote, marginVnd) không được phép trôi ra vendor. Một dòng loại bỏ trong adapter rẻ hơn nhiều so với một incident.

tsapi/legacy-order-mapper.ts (tiếp)
/** Domain -> DTO. Không leak field nội bộ, đúng format ngày của họ. */
export function toApi(o: Order): LegacyOrderDto {
  return {
    id: Number(o.id),
    created_at: o.placedAt.toISOString().slice(0, 19).replace("T", " "), // "yyyy-MM-dd HH:mm:ss"
    customer: { full_name: o.customerName },
    line_items: o.lines.map(li => ({
      sku: li.sku,
      qty: String(li.qty),
      unit_price: String(li.unitPrice),   // VND -> cent: ĐỐI NGƯỢC của toDomain
    })),
    // state: KHÔNG gửi. Trạng thái do backend quyết, không phải client.
  }
}

/** PATCH: chỉ gửi phần thay đổi, vẫn đi qua cùng một hợp đồng dịch. */
export const toApiPatch = (patch: Partial<Order>) => toApi({ ...defaults, ...patch })
Hai hàm cạnh nhau, cùng một file: cent → VND và VND → cent nằm gần nhau thì lệch nhau là thấy ngay.
ChốtAdapter hai chiều giữ domain sạch ở cả đọc lẫn ghi. Adapter một chiều chỉ giải quyết nửa vấn đề, và thường là nửa dễ.
5

Đặt adapter ở layer gọi API, không phải trong component

Adapter sống ở cùng chỗ gọi API — api/orders.ts, server/api/*, repository — và exported dưới dạng hàm có type của domain. Component chỉ thấy listOrders(): Promise<Order[]>. Đây là ranh giới mà bạn có thể thực thi bằng tooling: ESLint no-restricted-imports chặn useFetch trong components/, domain không được import từ api/.

Không có ranh giới file, adapter chỉ là lời khuyên. Và lời khuyên thì thua deadline.

tsapi/orders.ts
import { toDomain } from "./legacy-order-mapper"

interface ListResponse { orders: unknown[] }

/** Hợp đồng nội bộ: caller nhận Order, không bao giờ nhận unknown. */
export async function listOrders(): Promise<Order[]> {
  const res = await $fetch<ListResponse>("/legacy/orders")
  return res.orders.map(toDomain)     // gate: 1 dòng, mọi lỗi dữ liệu dồn về đây
}

export async function createOrder(o: Order): Promise<void> {
  await $fetch("/legacy/orders", { method: "POST", body: toApi(o) })
}

// OrderList.vue: const { data } = await useAsyncData("orders", listOrders)
// -> data: Order[] | undefined, autocomplete đúng, template không còn "any"
Component không còn một kiến thức nào về endpoint. Đổi API v2: sửa api/orders.ts, không sửa UI.
ChốtAdapter chỉ đáng tin khi nó nằm ở một module boundary mà lint/type có thể canh. Adapter đặt rải rác trong .vue sẽ bị copy 19 lần.
6

Adapter dạng class khi có nhiều hơn một implementation

Khi bạn cần chọn vendor lúc chạy (Stripe hôm nay, vendor B tháng sau) hoặc bản giả để test, hãy nâng lên interface. Interface là Target trong ngôn ngữ GoF; mỗi vendor một class adapter, constructor nhận credential/config, method dịch sang SDK của họ. Đây chính là nơi Singleton + DI khớp vào: vendor adapter là dependency được truyền vào service.

Class không phải yêu cầu của pattern — nó là hệ quả của việc có state (apiKey, timeout, client đã init) và nhiều method cần dịch cùng nhau.

tspayment/payment-gateway.ts
export interface PaymentGateway {
  createIntent(amount: Money, currency: "VND"): Promise<{ intentId: string, clientSecret: string }>
  capture(intentId: string, amount: Money): Promise<"succeeded" | "failed">
}

/** Adaptee = Stripe SDK. Tên kiểu của SDK KHÔNG đi ra khỏi file này. */
export class StripeAdapter implements PaymentGateway {
  constructor(private readonly stripe: Stripe, private readonly webhookSecret: string) {}

  createIntent(amount, currency) {
    return this.stripe.paymentIntents.create({
      amount: amount * 100,          // VND -> minor unit: chỗ DUY NHẤT dịch đơn vị
      currency,
    }).then(i => ({ intentId: i.id, clientSecret: i.client_secret ?? "" }))
  }

  capture(intentId, amount) {
    return this.stripe.paymentIntents.capture(intentId)
      .then(() => "succeeded", () => "failed")
  }
}

// Test / dev: cùng hợp đồng, không network
export class FakeGateway implements PaymentGateway {
  private n = 0
  createIntent: PaymentGateway["createIntent"] = async () => ({
    intentId: "pi_" + ++this.n, clientSecret: "secret",
  })
  capture: PaymentGateway["capture"] = async () => "succeeded"
}
FakeGateway là adapter cho test, cùng một hợp đồng. UI không đổi một dòng khi bạn đổi vendor.
ChốtInterface + adapter biến "đổi nhà cung cấp" từ refactor 20 file thành thêm một file và một dòng wiring.
7

Test round-trip: toApi ∘ toDomain không được mất dữ liệu

Failure mode kinh điển của adapter hai chiều: ai đó thêm field vào toDomain rồi quên toApi. Đọc thì đủ, ghi lên thì mất im lặng. Test rẻ nhất mà bắt được đúng bug này là round-trip: DTO thật → domain → DTO, rồi so sánh với giới hạn đã khai báo.

Lấy fixture từ payload thật (copy từ network tab, hoặc snapshot response ở stage), đừng gõ tay — gõ tay là bạn test trí tưởng tượng của mình. Phần field cố ý không round-trip (field do server sinh, field read-only) phải liệt kê tường minh, để mỗi lần mất thêm field là một lần phải giải thích.

tslegacy-order-mapper.test.ts
// Fixture: copy payload THẬT từ network tab, đừng gõ tay theo trí nhớ
const fixture = {
  id: 7,
  created_at: "2024-03-07 14:20:00",
  customer: { full_name: "Chị A" },
  line_items: [{ sku: "A1", qty: "2", unit_price: "199000" }],
  state: "new",
  profit_margin: 0.31,
  updated_at: "2024-03-08 09:00:00",
}

// toDomain: ai cũng nhớ. toApi: hay bị QUÊN khi có field mới.
const toDomain = (d: typeof fixture) => ({
  id: String(d.id),
  customerName: d.customer.full_name,
  lines: d.line_items.map(li => ({
    sku: li.sku, qty: Number(li.qty), unitPrice: Number(li.unit_price),
  })),
})
const toApi = (o: ReturnType<typeof toDomain>) => ({
  id: Number(o.id),
  customer: { full_name: o.customerName },
  line_items: o.lines.map(li => ({ sku: li.sku, qty: String(li.qty) })), // unit_price bị QUÊN
})

// Field cố ý không quay về (server sinh): khai báo ở đây, thêm field khác là fail
const readOnly = new Set(["state", "updated_at", "profit_margin"])
const again = toApi(toDomain(fixture))
const lost = Object.keys(fixture)
  .filter(k => !readOnly.has(k)
    && JSON.stringify((fixture as any)[k]) !== JSON.stringify((again as any)[k]))

console.log("mất ở cấp đơn:", lost.length ? lost.join(",") : "không có")
const lostLine = Object.keys(fixture.line_items[0])
  .filter(k => !(k in (again.line_items[0] as object)))
console.log("mất ở line_item:", lostLine.join(","))
console
mất ở cấp đơn: created_at,line_items
mất ở line_item: unit_price
Test này fail có chủ đích: nó chỉ đúng hai chỗ lệch pha. Trong repo, nó xanh và báo ngay khi ai đó thêm field vào toDomain mà quên toApi.
ChốtAdapter là boundary, mà boundary thì test một lần ăn tới mãi. Test domain phía sau adapter mà không test adapter là test trên giả định.
8

Biết điểm dừng: khi adapter chỉ là tầng vô ích

Adapter rỗng là phản pattern. Đây là dạng phổ biến nhất — một file "api" chỉ return await $fetch(...) và đặt tên kết quả là Order bằng cast. Nó không dịch gì, chỉ tạo ảo giác an toàn: type nói Order, dữ liệu thật vẫn là DTO, và giờ bạn không còn tìm ra ranh giới để mà sửa.

Đừng viết adapter khi: chỉ có một implementation và bạn không dự kiến có cái thứ hai; hình dạng của API đã là hợp đồng bạn muốn; và không cần biến đổi (không unit, không default, không validation). Lúc đó một interface OrderDto exported từ file api/ là đủ. Adapter đáng giá khi có thứ để dịch hoặc implementation thứ hai.

tsapi/adapter-rỗng.ts
// ✗ "Adapter" không dịch gì: chỉ là cast, và là một LỜI NÓI DỐI có type
export async function listOrders(): Promise<Order[]> {
  const res = await $fetch("/legacy/orders")
  return res.orders as Order[]      // DTO snake_case đang mặc áo Order
}

// ✓ Thẳng thắn: một hình dạng, một kiểu, không biến đổi -> không cần adapter
export interface OrderDto { id: number, created_at: string, line_items: LineItemDto[] }
export const listOrdersRaw = () => $fetch<ListResponse>("/legacy/orders")

// ✓ Adapter thật khi có ÍT NHẤT một trong ba: nhiều vendor, có biến đổi
//   (unit/default/format), hoặc cần gate dữ liệu từ unknown.
Một file adapter không có dòng mapping nào thì nên bị xoá, không nên được "tái sử dụng".
ChốtAdapter tồn tại vì có sự chênh lệch. Không chênh lệch thì đó là indirection thuần, và indirection thuần là chi phí đọc code cho mọi người sau.

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

Cấu trúc

  • TargetHợp đồng nội bộ mà code bạn muốn dùng: type `Order`, interface `PaymentGateway`. Do bạn đặt tên, do bạn owning.
  • AdapteeThứ đang tồn tại và không sửa được: endpoint v1, SDK vendor, lib callback, file import. Hình dạng của nó là **không thuộc quyền bạn**.
  • AdapterNơi dịch: `toDomain`/`toApi` cho dữ liệu, hoặc method-call cho service. File **duy nhất** được phép biết cả hai thế giới.
  • ClientDomain/service/component. Chỉ nhìn thấy Target, không import DTO, không biết vendor nào đang đứng sau.
  • Fixture/Golden testPayload thật + test round-trip, giữ adapter sát với hợp đồng của đối tác khi đối tác đổi.
   ┌───────────────────────────────┐        ┌──────────────────────────────┐
   │ DOMAIN (Target)               │        │ ADAPTEE (hình của người khác) │
   │  Order, OrderLine, Money      │        │  { created_at, unit_price,    │
   │  PaymentGateway               │        │    line_items[], state }      │
   └───────────────▲───────────────┘        └───────────────▲──────────────┘
                   │ type của BẠN                            │ type CỦA HỌ
                   │                                          │
        ┌──────────┴──────────────────────────────────────────┴─────────┐
        │ ADAPTER  (api/legacy-order-mapper.ts)   ← file DUY NHẤT       │
        │   toDomain(raw: unknown): Order    + gate, default, unit      │
        │   toApi(o: Order): LegacyOrderDto  + format, loại field nội bộ│
        └──────────────────────────┬────────────────────────────────────┘
                                   │ listOrders(): Promise<Order[]>
                                   ▼
                    ┌───────────────────────────────┐
                    │ CLIENT: service / component   │
                    │  không thấy snake_case,       │
                    │  không thấy cent, không "any"  │
                    └───────────────────────────────┘

   Vendor thứ hai? Thêm adapter mới cùng Target. Client không đổi một dòng.

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

Chạy thử: cùng một domain code, hai adapter từ hai thế giới khác nhau

tsdemo.ts
type Article = { id: number, title: string, authorName: string, viewCount: number, publishedAt: string }

interface LegacyDto {
  id: number
  title: string
  author_name: string
  view_count: number
  created_at: string
}
interface VendorDto {
  articleId: string
  fields: { name: string, reads: number, author: { display: string }, published: string }
}

// Adapter 1: CMS cũ, snake_case + "yyyy-MM-dd HH:mm:ss" — dịch HAI chiều
const legacyAdapter = {
  toDomain: (d: LegacyDto): Article => ({
    id: d.id, title: d.title, authorName: d.author_name, viewCount: d.view_count,
    publishedAt: d.created_at.replace(' ', 'T') + 'Z',
  }),
  toApi: (a: Article): LegacyDto => ({
    id: a.id, title: a.title, author_name: a.authorName, view_count: a.viewCount,
    created_at: a.publishedAt.slice(0, 10) + ' ' + a.publishedAt.slice(11, 19),
  }),
}

// Adapter 2: vendor khác, shape khác hẳn -> domain không đổi một dòng nào
const vendorAdapter = {
  toDomain: (d: VendorDto): Article => ({
    id: Number(d.articleId.slice(2)), title: d.fields.name, authorName: d.fields.author.display,
    viewCount: d.fields.reads, publishedAt: d.fields.published,
  }),
}

// Domain code: chỉ nhìn thấy Article, không biết DTO tồn tại
const headline = (a: Article) => a.title + ' — ' + a.authorName + ' · ' + a.viewCount + ' · ' + a.publishedAt

const legacy: LegacyDto = { id: 7, title: 'Adapter là gì', author_name: 'khoa', view_count: 1284, created_at: '2024-03-07 14:20:00' }
const vendor: VendorDto = { articleId: 'ID7', fields: { name: 'Adapter là gì', reads: 1284, author: { display: 'khoa' }, published: '2024-03-07T14:20:00Z' } }

console.log('1 legacy   :', headline(legacyAdapter.toDomain(legacy)))
console.log('2 vendor   :', headline(vendorAdapter.toDomain(vendor)))
console.log('3 roundtrip:', JSON.stringify(legacyAdapter.toApi(legacyAdapter.toDomain(legacy))) === JSON.stringify(legacy))
console.log('4 domain   :', Object.keys(legacyAdapter.toDomain(legacy)).join(','))
console
1 legacy   : Adapter là gì — khoa · 1284 · 2024-03-07T14:20:00Z
2 vendor   : Adapter là gì — khoa · 1284 · 2024-03-07T14:20:00Z
3 roundtrip: true
4 domain   : id,title,authorName,viewCount,publishedAt

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

  • API bên thứ ba có hình dạng không thuộc quyền quyết định của bạn: snake_case, ngày dạng string, tiền theo minor unit, một lớp envelope { data: { result } }.
  • Cần nhiều implementation cho cùng một hợp đồng: Stripe + vendor B, SMS + email, S3 + disk, hoặc fake gateway để test UI mà không có network.
  • Sống chung với legacy: lib callback-style, service cũ, module của team khác mà bạn không được phép sửa — adapter là nơi đặt lời nói dối dễ thương.
  • Migrating API của chính bạn: v1 còn consumer, v2 đã chạy. Adapter cho phép domain code đứng yên trong khi server đổi hình.
  • Hai miền khác nhau về chất chứ không chỉ về tên: cent ↔ đồng, state: "cnl" ↔ status: "cancelled", string ↔ Date. Đây là lúc adapter vừa dịch vừa bảo vệ domain khỏi dữ liệu rác.
  • Cùng một logic phải chạy trên platform khác API: browser (fetch, File System Access) vs Node (fs), IndexedDB vs SQLite — một Target, hai adapter.

Đừng dùng khi

  • Adapter rỗng (.ts chỉ cast, chỉ pass-through) là tầng vô ích và còn tệ hơn không có: nó tạo ảo giác đã có ranh giới, nên lần refactor sau không ai tìm ra chỗ thật để sửa. Không có dòng mapping nào thì xoá file, đừng "tái sử dụng".
  • Tax của mapping là thật. Một admin app CRUD mà mỗi endpoint có XxxDto + Xxx + toDomain + toApi là 4 artefact cho mỗi bảng, và nobody wins: DTO chính là domain. Phiên bản phải chăng: một type, một hàm parse ở ranh giới, chỉ tách khi có chênh lệch thật sự hoặc implementation thứ hai.
  • Adapter hai chiều lệch pha: toDomain được cập nhật, toApi thì không → PATCH mất field im lặng. Hoặc adapter leak: hàm trả Order & { raw: any }, hoặc domain giữ nguyên tên field snake_case — nhiễm vẫn hoàn nhiễm, chỉ khác chỗ đứng. Test round-trip là thuốc duy nhất đáng tin.
  • Nhét nghiệp vụ vào adapter (tính giảm giá, suy status, cộng VAT) vì "adapter thì không có logic". Adapter chỉ diễn đạt lại, không quyết định. Một khi toDomain tính tiền, không ai review nó như review nghiệp vụ nữa.
  • Interceptor global đổi snake↔camel cho mọi response (axios/ofetch interceptor) trông rất rẻ và sai một cách hệ thống: nó đổi luôn key bên trong payload free-form (metadata: {"user_id": ...} thành userId mà bạn không ngờ), làm mapping grep không ra, và khi API trả thứ không theo convention thì bạn có một bug chỉ tái hiện trên production data.
  • Tin adapter mà không gate dữ liệu: res.data.map(toDomain) với DTO kiểu any nghĩa là toDomain không chặn gì cả — type đúng, runtime rác. Gate nằm ở unknown + type guard, không nằm ở chữ ký hàm.

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

Trong code thật

util.promisify (Node)

Adapter đúng nghĩa, đóng gói sẵn trong Node: biến API callback (err, data) => ... thành Promise. fs.readFile không đổi, chỉ có hình đổi. Tương tự: stream.Readable.fromWeb() / Readable.toWeb() là adapter chính thức giữa Node stream và Web stream.

Vue/Nuxt: useFetch({ transform }) và ofetch instance

useFetch có tuỳ chọn transform — chỗ tự nhiên để đặt toDomain ngay tại ranh giới fetch, và createFetch({ onRequest, onResponse }) cho phép dựng một client đã gắn auth + unwrap envelope. Nó là adapter có chủ đích khi transform thật sự biến đổi; là adapter rỗng khi bạn chỉ đổi tên biến.

Repository/ORM: Prisma model → entity

Prisma trả OrderGetPayload<...> với _count, quan hệ lồng và ngày theo driver. Các codebase TS tách một hàm toOrder(row) ở repository: domain nhận entity, còn hình của schema DB đứng lại ở file repository — nơi duy nhất import { Prisma } xuất hiện.

zod / io-ts: parser là adapter một chiều

OrderSchema.transform(...) vừa validate vừa map: unknown vào, domain type ra, sai thì throw. Đây là bản inbound adapter mà phần gate được viết bằng schema thay vì if, và nó hết đúng khi API đổi — vì phần gate không làm bằng trí nhớ của bạn.

SDK vendor: axios vs fetch, Stripe vs vendor B

Hầu hết SDK wrap XMLHttpRequest/fetch sau một hợp đồng dễ dùng hơn — adapter về hình của function, không phải về dữ liệu. Cùng pattern đó ở tầng nghiệp vụ: service nhận PaymentGateway, dev/test chạy FakeGateway, production chạy StripeAdapter.

08 — Tự tay làm

Bài tập

Vendor SMS của bạn đổi từ `SmsV1` (trả `{ message_id, status_code: "00" }`, số điện thoại không dấu `+`) sang `SmsV2` (trả `{ id: { provider: number, external: string }, state: 1 }`). Viết interface `SmsGateway` (Target) với `send(phone, text): Promise<{ id: string, ok: boolean }>` và hai adapter `SmsV1Adapter`, `SmsV2Adapter`, rồi gọi cùng một hàm `notify(gw, ...)` cho cả hai.

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

  1. Target phải không chứa chi tiết của vendor nào: không status_code, không state, không object lồng. Hãy viết interface SmsGateway trước, hai adapter sau.
  2. SmsV1 dùng "00" là thành công; SmsV2 dùng state === 1. Hai bảng dịch đó nằm trong adapter, không nằm trong notify.
  3. ID của v2 là object lồng (id.provider + id.external) — adapter phải trả một string ổn định, ví dụ provider + ":" + external, và quyết định đó phải được test.

Interface chung, mỗi vendor một adapter dịch tên + dịch cả ngữ nghĩa ("00"/state:1 → ok), và normalize ID về một dạng. notify chỉ biết SmsGateway, nên nó chạy nguyên vẹn cho cả hai.

tsbai-tap.ts
interface SmsResult { id: string, ok: boolean }
interface SmsGateway { send(phone: string, text: string): Promise<SmsResult> }

// ---- vendor 1 ----
interface V1Response { message_id: string, status_code: string }
const v1Send = async (phone: string, text: string): Promise<V1Response> =>
  ({ message_id: "m-7", status_code: text === "" ? "99" : "00" })

export const SmsV1Adapter = (): SmsGateway => ({
  send: async (phone, text) => {
    const r = await v1Send(phone, text)
    return { id: "1:" + r.message_id, ok: r.status_code === "00" }
  },
})

// ---- vendor 2 ----
interface V2Response { id: { provider: number, external: string }, state: number }
const v2Send = async (phone: string, text: string): Promise<V2Response> =>
  ({ id: { provider: 2, external: "m-7" }, state: text === "" ? 0 : 1 })

export const SmsV2Adapter = (): SmsGateway => ({
  send: async (phone, text) => {
    const r = await v2Send(phone, text)
    return { id: r.id.provider + ":" + r.id.external, ok: r.state === 1 }
  },
})

// ---- client: không biết vendor, không biết "00", không biết "state" ----
async function notify(gw: SmsGateway, phone: string, name: string) {
  const r = await gw.send(phone, "Chao " + name)
  return (r.ok ? "OK " : "FAIL ") + r.id
}

;(async () => {
  console.log(await notify(SmsV1Adapter(), "+8490123456", "Khoa"))
  console.log(await notify(SmsV2Adapter(), "+8490123456", "Khoa"))
  console.log(await notify(SmsV2Adapter(), "+8490123456", ""))
})()

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

Pattern liên quan

  • FacadeCùng gói một thứ gì đó, nhưng Facade **làm API dễ dùng hơn** (gộp nhiều call thành một hàm), còn Adapter **làm API khớp một hợp đồng đã có**. Facade không cần biết Target; Adapter bắt buộc có Target.
  • BridgeBridge tách abstraction khỏi implementation **ngay từ đầu** để hai bên độc lập tiến hoá; Adapter nối hai thứ đã viết xong, thường là muộn hơn. Bridge là thiết kế trước, Adapter là chữa sau — cùng một cơ chế composition.
  • ProxyProxy giữ **cùng** hợp đồng với đối tượng nó đứng thay (thêm lazy, cache, quyền). Adapter **đổi** hợp đồng. Một class có thể làm cả hai, nhưng hãy gọi tên đúng cái nó làm.
  • DecoratorDecorator thêm hành vi và trả về đúng kiểu cũ (`withRetry(gw)` vẫn là `PaymentGateway`); Adapter trả về kiểu **khác**. Cặp này hay lồng nhau: adapter của vendor, bọc bởi decorator retry/log.