Проведение границ модулей

Хорошая граница запирает вероятное изменение за маленьким устойчивым интерфейсом. Весь смысл края модуля — в изменении, которое тебе не придётся делать: вызывающие по ту сторону продолжают работать, потому что зависят от интерфейса, а не от реализации. Поэтому ты проводишь границу вокруг того, что вероятнее всего будет варьироваться, — платёжного провайдера, налогового правила, бэкенда хранилища — и выставляешь самую узкую поверхность, которая вызывающим реально нужна.

// payments/index.ts — граница. Вызывающие видят только это.
export interface PaymentGateway {
  charge(amountCents: number, token: string): Promise<ChargeResult>;
}
export type ChargeResult = { ok: true; id: string } | { ok: false; reason: string };

За этим швом StripeGateway может стать AdyenGateway, могут появиться ретраи и ключи идемпотентности, а код оформления заказа никогда не изменится — он всегда знал только charge. Интерфейс маленький (один метод) и устойчивый (он описывает что, а это редко двигается), тогда как реализация большая и изменчивая (она описывает как, а это двигается постоянно). Эта асимметрия — маленькая устойчивая поверхность, большое изменчивое тело — и есть подпись границы, ради которой стоит её проводить.

Связность — сила, решающая, что живёт внутри границы: что меняется вместе, то и принадлежит вместе. Модуль связен, когда его части служат одной цели и меняются по одной причине. Операционный тест — тот самый из призмы стоимости изменения: когда движется одно требование, сколько модулей ты открываешь? Один — значит связность совпала с изменением. Много — значит граница была проведена поперёк изменения, а не вокруг него.

// ВЫСОКАЯ связность: всё, что нужно «оформлению заказа», в одном месте
checkout/
  checkout.handler.ts    // HTTP вход/выход для checkout
  pricing.ts             // правило ценообразования checkout
  checkout.repo.ts       // персистентность checkout
  checkout.types.ts      // формы, общие только внутри checkout

Добавление купона в checkout — это правки в одном каталоге. Части связаны друг с другом — но это нормально: они всегда собирались меняться вместе, поэтому внутренняя связанность — это просто модуль, делающий свою работу. Ошибка — путать эту безвредную внутримодульную связанность с вредной, межмодульной.

У связанности есть направление, и направление решает всё: входящая против исходящей. Входящая связанность (Ca) считает, кто зависит от модуля, — его входящие стрелки, его fan-in. Исходящая связанность (Ce) считает, от кого зависит модуль, — его исходящие стрелки, его fan-out. Их отношение даёт нестабильность: I = Ce / (Ca + Ce), от 0 (я ни от кого не завишу; все зависят от меня — максимально устойчив) до 1 (я завишу от всего; от меня не зависит никто — максимально нестабилен).

// Листовая деталь: высокая Ce, низкая Ca → I ≈ 1 (нестабилен, свободен меняться)
//   StripeGateway зависит от Stripe SDK, конфига, логирования, интерфейса PaymentGateway
//   …и (почти) ничто не зависит от StripeGateway напрямую.

// Ядровая абстракция: низкая Ce, высокая Ca → I ≈ 0 (устойчив, дорого менять)
//   PaymentGateway не зависит ни от чего; checkout, возвраты, выставление счетов — все зависят от него.

Устойчивость здесь — это не «хороший код», это утверждение о радиусе поражения. Модуль, от которого зависит многое (высокая Ca, низкая I), дорого менять, потому что изменение расходится наружу, поэтому ему лучше быть абстракцией, которой это редко нужно. Модуль, от которого не зависит ничто (низкая Ca, высокая I), дёшево менять, потому что вниз по течению ничего не ломается, — и именно туда ты хочешь поместить изменчивую деталь.

Принцип устойчивых зависимостей: завись в направлении возрастающей устойчивости. Стрелки должны указывать от нестабильного к устойчивому — I должна убывать вдоль каждой стрелки зависимости. Изменчивая деталь зависит от устойчивой абстракции; никогда наоборот. Причина механична: если бы устойчивый модуль зависел от изменчивого, каждое подёргивание изменчивой детали вынуждало бы менять то, от чего зависят все остальные, и рябь разорвала бы систему. Указать стрелку в другую сторону — значит запереть изменчивость в листьях, где её радиус поражения равен нулю.

// ПРАВИЛЬНО: деталь → абстракция. Нестабильность убывает вдоль стрелки.
//   checkout (I≈0.6)  →  PaymentGateway (I≈0.0)  ←  StripeGateway (I≈1.0)
//   И политика, и деталь зависят от устойчивого интерфейса посередине.

// НЕПРАВИЛЬНО: абстракция → деталь. checkout импортирует StripeGateway напрямую.
//   import { StripeGateway } from "../payments/stripe";   // устойчивый вызывающий теперь обвенчан с изменчивой деталью

Правая форма — это просто инверсия зависимостей, сформулированная как закон границы: изменчивый StripeGateway и изменчивая политика checkout оба указывают внутрь, на устойчивый PaymentGateway. Когда появляется режим отказа — устойчивый модуль тянется к конкретному, быстро меняющемуся, — ты посадил зависимость, которая бежит в гору против устойчивости, и она будет ломаться куда сильнее, чем должна.

Разбивай по фичам, а не по слоям — и распознавай разбиение по слоям как высокую связанность, переодетую в организацию. Разбиение по слоям группирует файлы по техническому виду: controllers/, services/, repositories/. Оно выглядит упорядоченным, потому что все файлы одного вида вместе. Но требования приходят не по слою — они приходят по фиче. «Добавить подарочные карты» — это один запрос на изменение, который при разбиении по слоям вынуждает править controllers/, services/, repositories/ и dto/ одновременно: дробящая хирургия, каждый раз. Папки связны по неправильной оси (вид), а это значит, что они связаны вдоль оси, которая реально варьируется (фича).

разбиение по слоям  (низкая связность на фичу)    разбиение по фичам (высокая связность на фичу)
  controllers/  checkout.ctrl, refund.ctrl          checkout/   handler, pricing, repo, types
  services/     checkout.svc, refund.svc            refunds/    handler, policy, repo, types
  repositories/ checkout.repo, refund.repo          payments/   gateway (граница), stripe, adyen
  одна фича = правка в каждой папке                 одна фича = одна папка

Разбиение по фичам — не вопрос стиля; оно выравнивает границу с осью изменения, так что частое изменение локально, а межмодульная поверхность сжимается до намеренных устойчивых швов (вроде payments/). Когда не применять его: подлинно сквозная забота, у которой нет дома-фичи — middleware авторизации, адаптер логирования, общие типы-значения, — действительно принадлежит общему/платформенному модулю. Запихивание их в папку-фичу просто переселяет связанность. Сначала фичи, с маленьким честным «общим ядром» для того, что по-настоящему охватывает несколько фич.