Абстракция данных Барбары Лисков: как строить надёжные API

Почему вклад Барбары Лисков всё ещё важен для проектирования API

Барбара Лисков — учёный в области информатики, чьи идеи незримо сформировали то, как современные команды строят ПО, которое не разваливается. Её исследования по абстракции данных, сокрытию информации и позднее — Принципу подстановки Лисков (LSP) — повлияли и на языки программирования, и на повседневное понимание API: определяй понятное поведение, защищай внутренности и делай так, чтобы другим было безопасно полагаться на твой интерфейс.

«Надёжные интерфейсы» в терминах продукта

Надёжный API — это не просто «теоретически корректный» интерфейс. Это интерфейс, который помогает продукту двигаться быстрее:

• Новые фичи выпускаются без ломки существующих клиентов.
• Интеграции продолжают работать между версиями.
• Количество инцидентов на он‑колле снижается, потому что отказы предсказуемы.
• Команды могут менять внутренности без марафона согласований.

Эта надёжность — это опыт: для разработчика, вызывающего API, для команды, которая его поддерживает, и для конечных пользователей, зависящих от него косвенно.

Как абстракция данных сокращает баги (и совещания)

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

Когда вы скрываете детали представления, вы устраняете целые классы ошибок: никто не может «случайно» опереться на поле в базе, которое не предназначалось для публичного доступа, или мутировать общий стейт так, что система не справится. Не менее важно, что абстракция снижает накладные расходы на координацию: команды не нуждаются в разрешениях на рефакторинг внутренностей, если публичное поведение остаётся неизменным.

Что вы сможете применить после прочтения

К концу статьи у вас будут практические приёмы, чтобы:

• Описывать поведение API как понятные обещания (включая пограничные случаи).
• Держать интерфейсы маленькими и стабильными по мере эволюции систем.
• Проектировать предсказуемые режимы отказов, которые вызывающие стороны смогут корректно обрабатывать.

Если нужен краткий пересказ позже, перейдите к /blog/a-practical-checklist-for-designing-reliable-apis.

Абстракция данных, объяснённая без жаргона

Абстракция данных — простая идея: вы взаимодействуете с чем‑то по тому, что оно делает, а не по тому, как это устроено.

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

«Что оно делает» vs «Как это работает»

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

Разделение этих уровней — путь к API, которые остаются стабильными, пока система эволюционирует. Вы можете переписать внутренности, поменять библиотеки или оптимизировать хранение — при этом интерфейс останется тем же для пользователей.

Абстрактные типы данных (ADT) за минуту

Абстрактный тип данных — это «контейнер + допустимые операции + правила», описанные без привязки к конкретной внутренней структуре.

Пример: Стек (последним пришёл — первым вышел).

• push(item): добавить элемент
• pop(): удалить и вернуть последний добавленный элемент
• peek(): посмотреть верхний элемент, не удаляя

Ключевое обещание: pop() возвращает последний push(). Используется массив, связный список или что‑то ещё — это приватно.

Как это соотносится с реальными API

Та же идея везде применима:

• REST‑endpoint’ы: POST /payments — это интерфейс; проверки на мошенничество, ретраи и записи в базу — реализация.
• SDK‑методы: client.upload(file) — интерфейс; чанкинг, компрессия и параллельные запросы — реализация.
• UI‑компоненты: «DatePicker» открывает props/events; DOM‑структура и доступность — реализация.

Проектируя с абстракцией, вы фокусируетесь на контракте, на который опираются пользователи, и покупаете себе свободу менять всё за кулисами без их ломки.

Инварианты: скрытые правила, сохраняющие корректность системы

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

Как выглядят инварианты (без математики)

Инвариант — это «форма реальности» для вашего типа:

• Cart не может содержать отрицательные количества.
• UserEmail всегда валиден как адрес электронной почты (не «проверяется позже»).
• Reservation имеет start < end, и оба времени в одной временной зоне.

Если эти утверждения перестают быть верными, система становится непредсказуемой: каждая фича начинает догадываться, что означает «сломанные» данные.

Как инварианты направляют валидацию и обработку ошибок

Хорошие API обеспечивают инварианты на границах:

• При создании: отклонять неверные входы рано (возвращать понятную ошибку).
• При обновлениях: допускать только изменения, которые сохраняют инвариант.
• При парсинге/IO: считать внешние данные недоверенными; валидировать до сохранения.

Это улучшает обработку ошибок: вместо расплывчатых сбоев позже («что‑то пошло не так») API может объяснить, какое правило нарушено («end должен быть позже start»).

Не допускайте утечек инвариантов в интерфейс

Вызывающие не должны запоминать внутренние правила типа «этот метод работает только после вызова normalize()». Если инвариант зависит от специального ритуала — это не инвариант, а ловушка.

Спроектируйте интерфейс так, чтобы:

• Невалидные состояния были не представлены или их сложно представить.
• Методы автоматически сохраняли инвариант.

Практический чеклист для документации

При документировании типа API пропишите:

1. Формулировки инвариантов (на простом языке, тестируемые)
2. Где они обеспечиваются (конструктор, сеттеры, endpoint’ы)
3. Что происходит при нарушении (тип/сообщение ошибки, статусный код)
4. Какие методы их сохраняют (и есть ли исключения)
5. Примеры валидных и невалидных входов (коротко, конкретно)

Контракты: делайте поведение понятным для вызывающих и поддерживающих

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

Что нужно прописать в контракте

Минимум — документируйте:

• Предусловия: что должно быть верно перед вызовом (диапазоны, права, ожидания по потокобезопасности).
• Постусловия: что будет верно после успешного вызова (значение возврата, изменения состояния).
• Побочные эффекты: что ещё меняется (записи на диск, сетевые вызовы, изменение переданных объектов).

Такая ясность делает поведение предсказуемым: вызывающие знают, какие входы безопасны и какие исходы обрабатывать, а тесты проверяют обещание, а не догадываются о намерении.

Контракты уменьшают «племенное знание»

Без контрактов команды полагаются на память и неформальные нормы: «не передавай null», «вызов иногда ретраится», «в случае ошибки возвращает пустое». Эти правила теряются при онбординге, рефакторах или инцидентах.

Письменный контракт превращает скрытые правила в общий ресурс. Он также служит стабильной целью для ревью кода: обсуждение становится «удовлетворяет ли изменение контракту?» вместо «у меня работает».

Хорошая и расплывчатая формулировка (примеры)

Расплывчато: «Создаёт пользователя.»

Лучше: «Создаёт пользователя с уникальным email.

• Предусловия: email должен быть валидным адресом; вызывающий должен иметь право users:create.
• Постусловия: возвращает новый userId; пользователь сохранён и сразу доступен для чтения.
• Механизмы отказа: возвращает 409, если email уже существует; возвращает 400 при неверных полях; частичный пользователь не создаётся.»

Расплывчато: «Получает элементы быстро.»

Лучше: «Возвращает до limit элементов, отсортированных по createdAt по убыванию.

• Побочные эффекты: отсутствуют.
• Консистентность: может быть до 60 секунд устаревшей.
• Пагинация: используйте nextCursor для следующей страницы; курсоры истекают через 15 минут.»

Сокрытие информации: держите внутренности приватными, API — стабильным

Сокрытие информации — практическая сторона абстракции данных: вызывающие должны полагаться на что делает API, а не на как он это делает. Если пользователи не видят внутренности, вы можете менять их без превращения каждого релиза в ломающее изменение.

Публикуйте операции, а не представление

Хороший интерфейс публикует небольшой набор операций (create, fetch, update, list, validate) и держит представление — таблицы, кеши, очереди, файловые раскладки, границы сервисов — приватным.

Например, «добавить товар в корзину» — это операция. «CartRowId» из вашей базы — деталь реализации. Когда вы экспонируете деталь, вы приглашаете пользователей строить свою логику вокруг неё, что замораживает возможность изменений.

Почему скрытие внутренностей делает рефакторы безопасными

Когда клиенты зависят только от стабильного поведения, вы можете:

• поменять базу данных или формат хранения
• распилить монолит на сервисы
• добавить кеширование или изменить индексацию
• реорганизовать внутренние модели

…и API остаётся совместимым, потому что контракт не сдвинулся. Это настоящая выгода: стабильность для пользователей и свобода для поддерживающих.

Распространённые паттерны утечек

Немного способов, как внутренности случайно просачиваются:

• Возврат внутренних идентификаторов, значимых лишь в вашей системе (auto‑increment, ключ шарда).
• Экспонирование изменяемых структур (например, возврат «сырого» объекта, который клиенты могут патчить и отправлять обратно), что связывает клиентов с вашими полями.
• Разрешение клиентам конструировать внутреннее состояние, например, status=3 вместо понятного имени или отдельной операции.

Проектирование ответов, которые остаются стабильными

Предпочитайте ответы, которые описывают смысл, а не механику:

• Используйте публичные идентификаторы, которые стабильны и непрозрачны (например, "userId": "usr_…") вместо номеров строк.
• Возвращайте копии или read‑only представления коллекций вместо структур, порядок или поля которых клиенты «случайно» используют.
• Добавляйте поля обратно‑совместимо; не меняйте смысл существующих полей.

Если деталь может измениться, не публикуйте её. Если пользователям она нужна — сделайте её частью интерфейса явно и документированно.

Принцип подстановки Лисков как обещание интерфейса

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

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

LSP как «не удивляй вызывающего»

Вызывающие опираются на то, что говорит API — не на то, что он случайно делает сейчас. Если интерфейс говорит «вы можете вызвать save() с любым валидным документом», то каждая реализация должна принимать такие документы. Если интерфейс говорит «get() возвращает значение или ясный результат «не найдено»», то реализации не должны внезапно бросать новые ошибки или возвращать частичные данные.

Безопасное расширение означает, что вы можете добавлять реализации (или менять провайдеров) без переписывания клиентского кода. Это практический смысл LSP: интерфейсы остаются взаимозаменяемыми.

Распространённые нарушения LSP в API

Два частых способа нарушить обещание:

• Уже входы (строже предусловия): новая реализация отклоняет входы, которые интерфейс позволял. Пример: интерфейс принимает любую UTF‑8 строку как id, а одна реализация требует только числовые id.

• Слабее выходы (ослабленные постусловия): новая реализация возвращает меньше, чем обещано. Пример: интерфейс обещал отсортированные, уникальные и полные результаты, а реализация возвращает несортированные данные или дубликаты.

Третье, тонкое нарушение — изменение поведения при ошибках: если одна реализация возвращает «не найдено», а другая бросает исключение для той же ситуации, клиенты не смогут безопасно подменять одно на другое.

Проектирование плагинов без сюрпризов

Чтобы поддерживать «плагины», опишите интерфейс как контракт:

• Укажите какие входы валидны и держите этот набор постоянным для всех реализаций.
• Опишите что означают выходы (включая порядок, значения по умолчанию и пограничные случаи).
• Стандартизируйте режимы отказов: какие ошибки возможны и что они обозначают.

Если реализация действительно нуждается в более строгих правилах, не прячьте это за тем же интерфейсом. Либо (1) определите отдельный интерфейс, либо (2) сделайте ограничение явной возможностью (например, supportsNumericIds()), чтобы клиенты сознательно на это соглашались.