Проектирование и соблюдение контрактов

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

/**
 * Stores a record and returns its assigned id.
 * @pre   record.id is unset; record passes validate()
 * @post  the record is durably persisted before this resolves;
 *        get(returnedId) returns an equal record
 * @inv   ids are never reused, even after delete
 */
interface Repository<T extends { id?: string }> {
  save(record: T): Promise<string>;
  get(id: string): Promise<T | null>;
}

Doc-комментарий — не украшение: это та часть интерфейса, на которую вызывающий на самом деле опирается. save, который возвращает управление до того, как запись стала надёжной, не изменил тип — но сломал контракт.

Соответствующая реализация и тонко нарушающая могут быть идентичны по типам — типы ловят форму, а не поведение. Вот два репозитория. Оба точно удовлетворяют интерфейс TypeScript. Один соблюдает контракт; другой усиливает предусловие и ослабляет постусловие — а это ровно запрещённое направление.

// Conforming: weaker preconditions are fine, postcondition is met.
class PgRepository<T extends { id?: string }> implements Repository<T> {
  async save(record: T): Promise<string> {
    const id = crypto.randomUUID();
    await this.db.insert({ ...record, id }); // awaits durability
    return id;                               // post: persisted before resolve
  }
  async get(id: string) { return this.db.findById(id); }
}

// Violating — yet it compiles and passes naive unit tests.
class CacheRepository<T extends { id?: string }> implements Repository<T> {
  async save(record: T): Promise<string> {
    if (!record.id) throw new Error("id required"); // STRENGTHENED precondition
    this.buffer.push(record);                        // not yet durable
    return record.id;                                // WEAKENED postcondition
  }
  async get(id: string) { return this.map.get(id) ?? null; }
}

CacheRepository требует, чтобы вызывающий передал id (базовый говорил, что не должен), и возвращает управление до того, как запись стала надёжной (базовый обещал, что станет). Вызывающий, написанный под контракт — «я могу сохранить без id и верить, что оно сохранено», — ломается в тот момент, когда ему вручают эту реализацию. Компилятор молчит, потому что с типами всё в порядке.

Закодируй в типах то, что можешь; остальное прибей общим контрактным тестом, прогоняемым против каждой реализации. Часть пунктов переезжает в систему типов: сделай id действительно необязательным на входе и обязательным на выходе (save(r: Omit<T,"id">): Promise<T & {id: string}>) — и вызывающего нельзя заставить его передать. Но надёжность, порядок, неповторное использование id — свойства поведения во времени — нельзя выразить структурным типом. Для них напиши один набор тестов, параметризованный фабрикой, и прогони его против каждой реализации. Этот набор и есть исполняемый контракт; реализация, которая дрейфует, проваливает общий тест, а не только свой собственный.

// contract.test.ts — one suite, every implementation must pass it.
export function repositoryContract(make: () => Repository<Doc>) {
  test("save assigns an id and persists before resolving", async () => {
    const repo = make();
    const id = await repo.save({ title: "x" });      // no id supplied
    expect(await repo.get(id)).toMatchObject({ title: "x" }); // durable now
  });
  test("ids are never reused after delete", async () => { /* ... */ });
}
// Each implementation opts in — drift in any one is caught here, not in prod.
describe("PgRepository",   () => repositoryContract(() => new PgRepository()));
describe("CacheRepository",() => repositoryContract(() => new CacheRepository()));

CacheRepository теперь проваливает первое утверждение (он требовал id). Контракт перестал быть комментарием, который люди бегло проглядывают, и стал воротами, которые обязана пройти каждая реализация.

Сожми контракт: «говори, а не спрашивай» и узкие интерфейсы оставляют меньше пунктов для соблюдения — и меньше для нарушения. Каждый метод и каждый геттер, который ты выставляешь, — это пункт, который реализующие обязаны выполнить правильно, и то, к чему вызывающие могут привязаться. «Говори, а не спрашивай» — дай объекту команду и позволь ему решать, вместо того чтобы вытаскивать его состояние и решать за него — убирает целые семейства предусловий («вызывай applyDiscount только когда isEligible истинно» превращается в «вызови checkout(), он сам знает»). Разделение интерфейсов делает то же структурно: толстый Repository с save/get/query/stream/migrate заставляет каждую реализацию соблюдать пункты, которые ей не нужны. Разбей его — и кэш в памяти реализует только Reader: для него нет постусловия migrate, которое можно тихо нарушить.

// Narrow contracts: each implementation honours only the clauses it actually has.
interface Reader<T> { get(id: string): Promise<T | null>; }
interface Writer<T> { save(record: Omit<T, "id">): Promise<T & { id: string }>; }
// A read-through cache is a Reader. It can't violate a Writer postcondition
// it was never asked to make.

Меньший контракт — это не просто меньше кода: это меньшая поверхность подстановимости, поэтому у реализации меньше способов оказаться тонко неправильной.

Когда подстановимость по-настоящему неопределённа, предпочитай композицию наследованию. Общий супертип — это обещание, что каждая реализация взаимозаменяема. Если ты не можешь действительно дать это обещание — классический Square extends Rectangle, где setWidth обязан нарушить инвариант независимости сторон Rectangle, или ReadOnlyList extends List, чей add обязан бросать исключение, — то навязанное наследование выпускает ложь, которой вызывающие будут доверять и которую никакой общий тест не спасёт, потому что сам контракт неудовлетворим. Senior-ход — перестать навязывать является и использовать имеет: коллекция только для чтения оборачивает список и выставляет лишь те операции, которые действительно может выполнить. Никакого ложного супертипа, никакого нарушения Лисков, никакого throw new Error("unsupported"), притаившегося за методом, который тип объявляет существующим.

// Don't: ReadOnlyList "is a" List but can't honour add()/remove().
// Do: it "has a" list and exposes only what it can truly promise.
class ReadOnlyView<T> {
  constructor(private readonly items: readonly T[]) {}
  get(i: number) { return this.items[i]; }
  get length() { return this.items.length; }
  // no add/remove to lie about
}