Ailtireacht Heicseagánach | Treoir Phraiticiúil d'Fheidhmchláir Nua-Aimseartha

Is patrún dearaidh bogearraí é ailtireacht heicseagánach a aonraíonn do chroíloighic ghnó ó chórais sheachtracha cosúil le bunachair shonraí, APIanna, agus comhéadain úsáideora. Tá an smaoineamh simplí: níor cheart do do chód fearainn brath ar bhonneagar riamh. Braitheann an bonneagar ar an bhfearann.

Thug Alistair Cockburn an patrún isteach in 2005. B’fhéidir go gcloisfeá “Ports and Adapters” á thabhairt air freisin. Déanann an dá ainm cur síos ar an gcoincheap céanna.

Cén Fáth a bhfuil Sí Ann

Tosaíonn an chuid is mó d’fheidhmchláir ar an mbealach céanna. Éiríonn loighic ghnó ina chíor thuathail le ceisteanna bunachar sonraí, láimhseálaithe HTTP, agus glaonna seirbhíse tríú páirtí. Oibríonn sé ar dtús. Ansin fásann an bonn cóid, agus tarlaíonn trí rud:

1. Éiríonn tástáil pianmhar. Ní féidir leat rialacha gnó a thástáil gan bunachar sonraí a thosú nó leath an chreata a mhocáil.
2. Tá athrú bonneagair contúirteach. Ciallaíonn soláthróir íocaíochta a mhalartú nó aistriú ó REST go GraphQL loighic ghnó a athscríobh.
3. Tá an cód deacair a thuiscint. Ní féidir le haon duine a rá cá gcríochnaíonn an fearann agus cá dtosaíonn an bonneagar.

Réitíonn ailtireacht heicseagánach na trí fhadhb seo trí riail amháin a fhorfheidhmiú: díríonn spleáchais isteach i gcónaí.

Na Bunchoincheapa

Smaoinigh ar d’fheidhmchlár mar thrí shraith chomhcheangailte.

An Fearann (Lár)

Seo do loighic ghnó. Feidhmeanna íona, eintitis, réada luacha, agus seirbhísí fearainn. Tá nialas spleáchas aige ar chreataí, bunachair shonraí, nó leabharlanna seachtracha. Labhrann sé a theanga féin.

Le haghaidh córas ríomhthráchtála, tá coincheapa cosúil le Order, Product, PricingRule, agus InventoryPolicy sa tsraith seo. Ní bhíonn a fhios ag na réada seo aon rud faoi SQL, HTTP, ná JSON.

Poirt (Meánsraith)

Is comhéadain iad poirt a shainíonn conas a idirghníomhaíonn an saol lasmuigh leis an bhfearann. Is conarthaí iad, ní cur i bhfeidhm.

Tá dhá chineál:

• Poirt isteach (tiomáint). Sainigh cad is féidir leis an bhfeidhmchlár a dhéanamh. Smaoinigh orthu mar chásanna úsáide. “Cuir ordú.” “Cealaigh suibscríbhinn.” “Gin sonrasc.”
• Poirt amach (tiomáinte). Sainigh cad a theastaíonn ón bhfeidhmchlár ón saol lasmuigh. “Sábháil ordú.” “Seol fógra.” “Faigh an ráta malairte.”

Is cuid den tsraith fearainn iad poirt. Scríobhtar i dteanga fearainn iad, ní i dteanga bonneagair. Scríobhann tú OrderRepository, ní PostgresOrderDAO.

Oiriúnóirí (Sraith Amuigh)

Is iad oiriúnóirí na cur i bhfeidhm nithiúla a nascann an fíorshaol le do phoirt.

• Aistrítear iarratais sheachtracha ina nglaonna fearainn ag oiriúnóirí isteach. Rialaitheoir REST, réiteoir GraphQL, ordú CLI, tomhaltóir scuaine teachtaireachtaí. Is oiriúnóirí isteach iad seo go léir.
• Cuireann oiriúnóirí amach na comhéadain phoirt amach i bhfeidhm. Stór PostgreSQL, seoltóir ríomhphoist SMTP, geata íocaíochta Stripe. Is oiriúnóirí amach iad seo go léir.

An léargas ríthábhachtach: braitheann oiriúnóirí ar phoirt. Ní bhraitheann poirt riamh ar oiriúnóirí. Seo a dhéanann an patrún iomlán ag obair.

Sampla Nithiúil

Abair go bhfuil gné socrú ordaithe á tógáil agat. Seo mar a bhriseann na sraitheanna síos.

Fearann (eintitis agus rialacha):

// domain/Order.ts
class Order {
  readonly id: string;
  readonly items: OrderItem[];
  readonly status: OrderStatus;

  calculateTotal(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.price.multiply(item.quantity)),
      Money.zero()
    );
  }

  confirm(): Order {
    if (this.items.length === 0) {
      throw new EmptyOrderError();
    }
    return new Order({ ...this, status: "confirmed" });
  }
}

Port isteach (comhéadan cáis úsáide):

// ports/inbound/PlaceOrder.ts
interface PlaceOrder {
  execute(command: PlaceOrderCommand): Promise<OrderConfirmation>;
}

Poirt amach (cad a theastaíonn ón gcás úsáide):

// ports/outbound/OrderRepository.ts
interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

// ports/outbound/PaymentGateway.ts
interface PaymentGateway {
  charge(amount: Money, method: PaymentMethod): Promise<PaymentResult>;
}

// ports/outbound/NotificationSender.ts
interface NotificationSender {
  sendOrderConfirmation(order: Order): Promise<void>;
}

Seirbhís feidhmchláir (cuireann an port isteach i bhfeidhm):

// application/PlaceOrderService.ts
class PlaceOrderService implements PlaceOrder {
  constructor(
    private orders: OrderRepository,
    private payments: PaymentGateway,
    private notifications: NotificationSender
  ) {}

  async execute(command: PlaceOrderCommand): Promise<OrderConfirmation> {
    const order = Order.create(command.items);
    const confirmed = order.confirm();

    const payment = await this.payments.charge(
      confirmed.calculateTotal(),
      command.paymentMethod
    );

    if (!payment.successful) {
      throw new PaymentFailedError(payment.reason);
    }

    await this.orders.save(confirmed);
    await this.notifications.sendOrderConfirmation(confirmed);

    return OrderConfirmation.from(confirmed, payment);
  }
}

Oiriúnóirí (bonneagar):

// adapters/inbound/OrderController.ts
class OrderController {
  constructor(private placeOrder: PlaceOrder) {}

  async handlePost(req: Request): Promise<Response> {
    const command = PlaceOrderCommand.fromRequest(req.body);
    const confirmation = await this.placeOrder.execute(command);
    return Response.json(confirmation.toResponse(), { status: 201 });
  }
}

// adapters/outbound/PostgresOrderRepository.ts
class PostgresOrderRepository implements OrderRepository {
  async save(order: Order): Promise<void> {
    await this.db.query(
      "INSERT INTO orders (id, items, status) VALUES ($1, $2, $3)",
      [order.id, JSON.stringify(order.items), order.status]
    );
  }

  async findById(id: string): Promise<Order | null> {
    const row = await this.db.query("SELECT * FROM orders WHERE id = $1", [id]);
    return row ? Order.fromPersistence(row) : null;
  }
}

Tabhair faoi deara nach luann PlaceOrderService PostgreSQL, HTTP, ná aon chreat riamh. Oibríonn sé go hiomlán le coincheapa fearainn agus comhéadain phoirt.

An Riail Spleáchais

Seo an riail is tábhachtaí. Más rud é nach bhfaigheann tú aon rud eile ón alt seo, faigh é seo:

Caithfidh spleáchais cóid foinse díriú isteach i gcónaí, i dtreo an fhearainn.

• Braitheann oiriúnóirí ar phoirt. Ní riamh a mhalairt.
• Braitheann poirt ar eintitis fearainn. Ní riamh ar oiriúnóirí.
• Ní bhraitheann an fearann ar aon rud seachtrach.

Forfheidhmítear é seo trí instealladh spleáchais. Sreangaíonn d’fhréamh comhdhéanaimh (pointe iontrála an fheidhmchláir) gach rud le chéile:

// main.ts (composition root)
const orderRepo = new PostgresOrderRepository(db);
const payments = new StripePaymentGateway(stripeClient);
const notifications = new EmailNotificationSender(mailer);

const placeOrder = new PlaceOrderService(orderRepo, payments, notifications);
const controller = new OrderController(placeOrder);

Ní allmhairíonn an tsraith fearainn riamh ón tsraith oiriúnóirí. Má fheiceann tú allmhairiú ó adapters/ laistigh de domain/ nó ports/, tá rud éigin mícheart.

Struchtúr Tionscadail

Déanann struchtúr fillteán glan na teorainneacha infheicthe:

src/
  domain/
    Order.ts
    OrderItem.ts
    Money.ts
    errors/
      EmptyOrderError.ts
      PaymentFailedError.ts
  ports/
    inbound/
      PlaceOrder.ts
      CancelOrder.ts
    outbound/
      OrderRepository.ts
      PaymentGateway.ts
      NotificationSender.ts
  application/
    PlaceOrderService.ts
    CancelOrderService.ts
  adapters/
    inbound/
      http/
        OrderController.ts
      cli/
        PlaceOrderCommand.ts
    outbound/
      persistence/
        PostgresOrderRepository.ts
      payment/
        StripePaymentGateway.ts
      notification/
        EmailNotificationSender.ts
  main.ts

Is féidir le gach forbróir ar an bhfoireann breathnú ar an gcrann seo agus tuiscint cá háit le cód nua a chur.

Buntáistí Tástála

Seo áit a n-íocann ailtireacht heicseagánach ar ais i ndáiríre.

Tástáil aonaid ar an bhfearann:

test("order calculates total correctly", () => {
  const order = Order.create([
    { product: "Widget", price: Money.eur(10), quantity: 3 },
    { product: "Gadget", price: Money.eur(25), quantity: 1 },
  ]);

  expect(order.calculateTotal()).toEqual(Money.eur(55));
});

Gan bunachar sonraí. Gan freastalaí HTTP. Gan creat mocála. Loighic íon, tástálacha íona.

Cásanna úsáide a thástáil le hoiriúnóirí bréige:

test("place order charges payment and saves", async () => {
  const orders = new InMemoryOrderRepository();
  const payments = new FakePaymentGateway({ alwaysSucceeds: true });
  const notifications = new FakeNotificationSender();

  const service = new PlaceOrderService(orders, payments, notifications);

  const result = await service.execute({
    items: [{ product: "Widget", price: 10, quantity: 2 }],
    paymentMethod: { type: "card", token: "tok_test" },
  });

  expect(result.status).toBe("confirmed");
  expect(orders.savedOrders).toHaveLength(1);
  expect(payments.charges).toHaveLength(1);
  expect(notifications.sent).toHaveLength(1);
});

Tástáileann tú an cás úsáide iomlán gan teagmháil le fíor-bhonneagar. Cuireann na hoiriúnóirí bréige na comhéadain phoirt chéanna i bhfeidhm, mar sin is féidir iad a mhalartú leis na cinn fíor.

Tástálacha comhtháthaithe le haghaidh oiriúnóirí amháin:

test("PostgresOrderRepository saves and retrieves", async () => {
  const repo = new PostgresOrderRepository(testDb);
  const order = Order.create([
    { product: "Widget", price: Money.eur(10), quantity: 1 },
  ]);

  await repo.save(order.confirm());
  const found = await repo.findById(order.id);

  expect(found).toEqual(order.confirm());
});

Faigheann gach oiriúnóir a thástáil chomhtháthaithe féin. Má éiríonn leis an oiriúnóir a thástáil, agus má éiríonn leis an gcás úsáide le hoiriúnóirí bréige, oibríonn an córas iomlán.

Cathain ba cheart Ailtireacht Heicseagánach a Úsáid

Cuireann ailtireacht heicseagánach struchtúr agus indíriú leis. Tá costas ag sin. Seo cathain is fiú é:

• Feidhmchláir fadmharthanacha. Má chothabháiltear an tionscadal ar feadh blianta, cúitíonn an infheistíocht go tapa.
• Rialacha gnó casta. Má tá loighic neamhbheagán ag d’fhearann a chaithfidh a thástáil go críochnúil.
• Pointí iontrála iolracha. Má ghlaoitear an loighic chéanna ó API gréasáin, CLI, scuaine teachtaireachtaí, agus post cron.
• D’fhéadfadh bonneagar athrú. Murar cinnte tú an bhfanfaidh tú le do bhunachar sonraí reatha, soláthróir néil, nó seirbhísí tríú páirtí.
• Forbróirí iolracha. Laghdaíonn teorainneacha soiléire coinbhleachtaí cumasc agus déanann athbhreithnithe cóid níos tapúla.

Cathain ba cheart É a Scipeáil

Ní theastaíonn an leibhéal struchtúir seo ó gach tionscadal:

• Feidhmchláir shimplí CRUD. Má tá an aip ag léamh agus ag scríobh sonraí den chuid is mó le loighic ghnó íosta, cuireann an t-indíriú costas gan bhuntáiste.
• Fréamhshamhlacha agus MVPanna. Tá luas níos tábhachtaí ná ailtireacht agus tú ag bailíochtú smaoineamh. Athfhactóraigh níos déanaí.
• Scripteanna beaga agus uirlisí. Ní theastaíonn poirt agus oiriúnóirí ó uirlis CLI 200 líne.

Braitheann an méid ceart ailtireachta ar chastacht na faidhbe. Tosaigh go simplí. Tabhair teorainneacha heicseagánacha isteach nuair a éiríonn pian an easpa díobh fíor.

Botúin Choitianta

Bonneagar a sceitheadh isteach san fhearann. Má tá maisitheoir @Column nó modh toJSON() ag d’eintiteas Order, tá bonneagar tar éis sceitheadh isteach. Coinnigh d’eintitis fearainn glan.

Poirt a chruthú a léiríonn bonneagar. Sáraíonn port ar a dtugtar SqlQuery an cuspóir. Ba cheart do phoirt cur síos ar a dteastaíonn ón bhfearann i dteanga fearainn, ní conas a oibríonn an bonneagar.

Ró-theibíu. Ní gá port do gach rud. Má tá feidhm fóntais agat a fhormáidíonn dátaí, úsáid go díreach í. Coinnigh poirt le haghaidh fíor-theorainneacha bonneagair.

An fhréamh chomhdhéanaimh a scipeáil. Gan áit shoiléir ina sreangaítear spleáchais le chéile, briseann an patrún. Ba cheart gach spleáchas a instealladh, ní a allmhairiú go díreach.

Heicseagánach vs. Patrúin Eile

Seans go n-iarrfá conas a bhaineann ailtireacht heicseagánach le patrúin eile:

• Clean Architecture (Robert C. Martin): An-chosúil. Cuireann Clean Architecture sraitheanna breise leis (eintitis, cásanna úsáide, oiriúnóirí comhéadain, creataí) ach tá an croí-smaoineamh mar an gcéanna: díríonn spleáchais isteach.
• Onion Architecture (Jeffrey Palermo): An-chosúil freisin. Úsáideann Onion Architecture fáinní comhcheangailte leis an bhfearann sa lár. Difríonn an téarmaíocht, ach tá an riail spleáchais mar an gcéanna.
• Layered Architecture (N-tier): An cur chuige traidisiúnta ina gcarnann sraitheanna go hingearach (cur i láthair, gnó, sonraí). An difríocht ríthábhachtach: in ailtireacht sraitheach, braitheann an tsraith ghnó de ghnáth ar an tsraith sonraí. In ailtireacht heicseagánach, tá an spleáchas sin inbhéartaithe.

Roinneann na trí phatrún nua-aimseartha (heicseagánach, glan, oinniún) an prionsabal bunúsach céanna. Ní bhraitheann an fearann ar bhonneagar. Difríonn siad go príomha i gcoinbhinsiúin ainmnithe agus i líon na sraitheanna a ordaíonn siad.

Ag Tosú

Más mian leat ailtireacht heicseagánach a chur i bhfeidhm ar thionscadal atá ann, ná bain triail as gach rud a athfhactóiriú ag an am céanna. Tosaigh le comhthéacs teoranta amháin nó gné amháin:

1. Aithin an chroíloighic ghnó sa ghné sin. Bain amach í isteach i bhfeidhmeanna nó ranganna íona gan spleáchais creata.
2. Sainigh poirt do na spleáchais sheachtracha a úsáideann an ghné sin. Cruthaigh comhéadain i dteanga fearainn.
3. Bog an cód bonneagair atá ann isteach i ranganna oiriúnóra a chuireann na comhéadain sin i bhfeidhm.
4. Sreangaigh gach rud le chéile i bhfréamh chomhdhéanaimh ag úsáid instealladh spleáchais.
5. Scríobh tástálacha don fhearann agus do chásanna úsáide ag úsáid oiriúnóirí bréige.

Déan arís don chéad ghné eile. Le himeacht ama, leathnóidh na teorainneacha heicseagánacha ar fud an bhoinn cóid go nádúrtha.

Smaointe Deiridh

Ní bhaineann ailtireacht heicseagánach le teimpléad docht a leanúint. Baineann sé le smaoineamh simplí amháin: cosain do loighic ghnó ó chíor thuathail an tsaoil lasmuigh. Athraíonn bunachair shonraí. Téann creataí as faisean. Déantar APIanna a dhíchoisiú. Ba cheart do do rialacha gnó maireachtáil tríd an iomlán sin.

Oibríonn an patrún toisc go n-oireann sé don chaoi a bhforbraíonn bogearraí i ndáiríre. Athraíonn riachtanais go leanúnach. Athraíonn bonneagar go tréimhsiúil. Ach is gnách gurb iad croí-rialacha do ghnó an chuid is cobhsaí den chóras. Tóg timpeall ar an gcobhsaíocht sin.

Má tá táirge á thógáil agat a chaithfidh maireachtáil, is ceann de na hinfheistíochtaí is fearr is féidir leat a dhéanamh i do bhonn cóid é ailtireacht heicseagánach.

---

An dteastaíonn cabhair chun ailtireacht d’fheidhmchláir a dhearadh nó a athfhactóiriú? Déan teagmháil linn. Cuidímid le foirne bogearraí a thógáil a fhanann incothabháilte de réir mar a fhásann sé.