Ranh giới (Boundaries)

❌ Dùng trực tiếp - kiểu thư viện rò khắp dự án

// file: src/services/payment.ts
import Stripe from 'stripe'; // kieu Stripe ro ra ngoai

export async function charge(amount: number): Promise<Stripe.PaymentIntent> {
  const stripe = new Stripe(process.env.STRIPE_KEY!);
  return stripe.paymentIntents.create({ amount, currency: 'vnd' });
  // Tra ve kieu Stripe.PaymentIntent - caller phai import Stripe de dung
}

// file: src/routes/checkout.ts
import Stripe from 'stripe'; // phai import lai - ro ra them mot lan nua

async function handleCheckout(amount: number) {
  const intent: Stripe.PaymentIntent = await charge(amount);
  // Doi sang BrainTree? Phai sua payment.ts VA checkout.ts VA moi file khac
  console.log(intent.status);
}

✅ Adapter - phần còn lại dự án chỉ biết interface của mình

// Buoc 1: dinh nghia interface THEO NHU CAU MINH (khong phai 1:1 voi Stripe)
interface PaymentGateway {
  charge(amount: number, currency: string): Promise<{ id: string; status: string }>;
  refund(paymentId: string): Promise<void>;
}

// Buoc 2: adapter boc Stripe - chi mot file nay biet den Stripe
import Stripe from 'stripe';
class StripeAdapter implements PaymentGateway {
  private client: Stripe;
  constructor(apiKey: string) {
    this.client = new Stripe(apiKey);
  }
  async charge(amount: number, currency: string) {
    const intent = await this.client.paymentIntents.create({ amount, currency });
    // Anh xa sang kieu cua minh - caller khong biet Stripe.PaymentIntent
    return { id: intent.id, status: intent.status };
  }
  async refund(paymentId: string) {
    await this.client.refunds.create({ payment_intent: paymentId });
  }
}

// Buoc 3: phan con lai du an dung interface - khong import Stripe
async function handleCheckout(gateway: PaymentGateway, amount: number) {
  const result = await gateway.charge(amount, 'vnd');
  // Doi sang BrainTree? Chi viet BrainTreeAdapter - checkout.ts khong doi gi
  console.log(result.status);
}

Learning test - xác nhận hiểu biết về thư viện, không phải về code mình

// learning-tests/json-parse.test.ts
// Muc dich: hoc cach JSON.parse xu ly cac truong hop bien
// Chay lai sau moi lan cap nhat dep de bat breaking change

import { describe, it, expect } from 'vitest';

describe('JSON.parse - learning tests', () => {
  it('parse object hop le', () => {
    // Xac nhan: truong so va truong string deu duoc anh xa dung
    const result = JSON.parse('{"name":"Meo Con","age":3}');
    expect(result.name).toBe('Meo Con');
    expect(result.age).toBe(3);
  });

  it('null trong JSON thanh null trong JS', () => {
    // Hoc: JSON null -> JS null (khac undefined)
    const result = JSON.parse('{"val":null}');
    expect(result.val).toBeNull();
    expect(result.val).not.toBeUndefined();
  });

  it('JSON sai cu phap throw SyntaxError', () => {
    // Hoc: loai exception cu the de boc dung kieu loi
    expect(() => JSON.parse('{bad}')).toThrow(SyntaxError);
  });
});

Stub cho code chưa tồn tại - code song song không cần chờ

// Buoc 1: dinh nghia interface the hien dieu MINH CAN (khong phai dieu doi phuong co)
interface InventoryService {
  checkStock(productId: string): Promise<number>;
  reserveItems(productId: string, qty: number): Promise<boolean>;
}

// Buoc 2: stub don gian - du lieu cung, implement interface dung
class FakeInventoryService implements InventoryService {
  async checkStock(productId: string): Promise<number> {
    // Toa cung: 100 cai kho hang - du de code va test phan cua minh
    return 100;
  }
  async reserveItems(productId: string, qty: number): Promise<boolean> {
    console.log(`[FAKE] Da dat cho ${qty} san pham ${productId}`);
    return true; // luon thanh cong - de test hanh phuc
  }
}

// Phan cua minh: viet va test hoan toan doc lap voi team khac
async function placeOrder(
  inventory: InventoryService, // nhan qua tham so - de doi sau
  productId: string,
  qty: number
): Promise<void> {
  const stock = await inventory.checkStock(productId);
  if (stock < qty) throw new Error(`Het hang: chi con ${stock}, can ${qty}`);
  const reserved = await inventory.reserveItems(productId, qty);
  if (!reserved) throw new Error('Dat cho that bai');
  console.log('Don hang thanh cong');
}

// Chay thu voi fake - khong phu thuoc team khac hay server that
await placeOrder(new FakeInventoryService(), 'SP001', 5);
// Don hang thanh cong