Вступление

Java называют языком программирования. С формальной точки зрения это правда. На практике картина более широкая. Я часто люблю повторять, что Java — это целая программная система для гибкой (agile) разработки. В ней можно выделить три ключевых компонента, которые предоставляются Явой:

Метод документации онтологической модели, то есть набора абстрактных концептов, которые каждый разработчик переносит к себя в голову через когнитивные ассоциации.
Система формальной верификации типов со строгими контрактами, дженериками и всей этой математикой про ковариантность и правила подстановки.
Среда выполнения с линковщиком внутри JVM, который динамически связывает символические ссылки между загруженными библиотеками.

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

Инструментов для анализа версий библиотек сейчас хватает. Они умеют проверять бинарную совместимость, смотреть исходники, сравнивать сигнатуры. Всё это давно изучено и описано. JVM-спецификация чётко говорит, когда мы получим NoSuchMethodError, а когда код продолжит работать.

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

Представьте: метод перенесли из подкласса в суперкласс. Большинство анализаторов покажут два факта:

метод удалён в подклассе;
метод добавлен в базовом классе.

Технически — правда, но по сути это ничего не обьясняет. Есть такое понятие, как Human-Centered Design — т.е. эмпатический подход к решению проблем, который ставит человеческие потребности и опыт во главу угла на протяжении всего процесса разработки продукта. Библиотеки и фреймворки есть такие же продукты, поэтому мне кажется очень важным так же применять практики человеко-ориентированного проектирования и в основной профессии Хабровчан, то есть инженерии ПО.

Поэтому я хочу рассказать про другой подход к аудиту версий Java-библиотек, который я применил при создании нового Аудитора. Инструмент, о котором пойдёт речь, умеет проверять и бинарную, и исходную совместимость, но не останавливается на этом. Он пытается распознавать рефакторинги по их смыслу и собирать человеко-читаемые отчёты на вики-страницах проекта. Цель — дать потребителям ваших библиотек и коллегам четко и лаконично понять, как эволюционировала сама модель и структура, а не просто точки линковки.

План следущий: сначала расскажу теорию, откуда происходят и что означают понятия исходной и бинарной совместимостей, обсужу, почему важен именно автоматический аудит при выпуске новых версий; затем на практическом примере java-protobuf покажу, как мой Аудитор справляется с задачами экзаменации и презентации изменений и чем он лучше других тулзов таких как japicmp, а также объясню, как грамотный подход к архитектуре решения делает его полноценным фреймворком с потенциалом для экспансии в другие ЯП.

I. Теория

Это — не только техническая статья: я хочу доказать, что инженерия гораздо шире программирования. Ради этого я дам контекст того, откуда идет методология гибкой разработки и как это связано с Явой, а только затем перейду к плотной теории типов.

От Водопада к Водовороту

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

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

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

Документация тоже не осталась в стороне. Javadoc привязал описание прямо к методам и классам, сделав документирование частью исходного кода. Теперь оно сопровождает код на всём его жизненном пути, а не пишется задним числом перед сдачей проекта.

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

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

В отличие от водопада, в водовороте границы между анализом, проектированием, реализацией, верификацией и сопровождением стёрты.

Совместимость на всех стадиях

В свете вышесказанного важно понимать: любое изменение кодовой базы в процессе эволюции проекта может бить сразу по нескольким зонам ответственности. Давайте рассмотрим каждую по отдельности с примерами.

1) Анализ

Сегодня мы работаем на экономику знаний, где основным фактором производства является информация. Мы перестали быть программистами в узком смысле и стали инженерами знания, которые управляют высоко-абстрактными концептами. Ява в этом свете, это не только виртуальная машина, а ещё и инструмент, где мы моделируем онтологии.

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

Анализ — это верхний уровень, где происходит работа со именно знаниями. Из требований мы дистиллируем сущности, пока еще не ограниченные жесткими рамками, которые накладывает материальная реальность. Например, мы можем представить кентавра, гибрид лошади и человека. Тут мы работаем с интерфейсами, где каждый метод всегда публичен и абстрактен.

2) Проектировка

Во-первых, когда мы проектируем своей проект, мы активно используем принцип полиморфизма, когда типы расширяют другие типы (классы расширяют классы, классы реализуют интерфейсы, или интерфейсы расширяют интерфейсы). Допущения о наследовании в библиотеке становятся заложены в наш собственный дизайн. Например:

Библиотека версии 1.0:

public interface IAnimal {
    public void eat() {}
}

public class Dog implements IAnimal {
    public void bark() {}
}

Наш код:

public void feed(Animal animal) {
    animal.eat();
}

// Мы вызываем:
feed(new Dog()); // норм, Dog — это Animal

Версия 2.0 библиотеки:

public class Animal {
    public void eat() {}
}

public class Dog {  // убрали extends Animal!
    public void bark() {}
    public void eat() {} // но ввели свой eat
}

Если не поменять наш код, мы не сможем скомпилировать проект:

feed(Dog) ❌ — Dog больше не Animal

В чём суть: Наш код ничего не знал про изменения. Он просто вызывает feed с собакой. А компилятор берёт новую версию библиотеки, смотрит: "В методе feed требуется Animal, а мы передаем Dog. В новой версии Dog — это просто Dog, он не является Animal, значит в коде ошибка", поэтому сборка не пройдет. Другими словами, мы получили несовместимость.

Хотя компилятор поймает эту ошибку как нарушение отношения подтипизации, корень проблемы глубже — в изменении дизайна библиотеки. Мы моделировали реальность через номинальные типы: Dog был подтипом Animal, потому что собака — это животное. Автор библиотеки разорвал эту связь, и ошибка типизации — лишь симптом того, что концептуальная модель, на которую опирался клиен��ский код, больше не работает.

Если бы проверки типов на этапе компиляции не было, и среда исполнения (runtime) просто вызывала бы старый метод eat на объекте, то программа продолжила бы работать, как и раньше, так как мы ввели свой eat, не наследуя его от Animal. Так и происходит в JavaScript. Интересно, что так же случится и случае с TypeScript, который использует структурную типизацию:

class Animal {
 eat() { }
}

class Dog {
 eat() { }
}

function test(a: Animal) { }

test(new Dog) // ок

Это лишь подтверждает, что Java — не очередной язык с поверхностной типовой проверкой для галочки, а среда концептуального моделирования с возможностью добавлять код, где типы несут онтологическую нагрузку, а поддержка кода растягивается на десятилетия именно потому, что контракты жестко зафиксированы на классах, которые помимо структурной, несут семантическую нагрузку.

2) Реализация

На предыдущем уровне, то

Во-вторых, концепты-концептами, но и программирование никто не отменял. Математические типы не могут полностью описать поведение императивной программы — хотя бы потому, что в чистой математике нет понятия «выброса исключения». Функция там не прерывается по побочному каналу, а всегда возвращает результат (или не завершается). Те, кто писал на С, знает, что такое проверка по errno. Конечно, можно было бы всегда возвращать комбинацию Result<Output, Error>, но тогда код превратится в не пойми что.

Поэтому в отличие от функциональных, язык Java создан для удобства людей. Из-за этого мы имеем throws аннотации, когда при реализации метода нам нужно четко задекларировать, что он может выбросить ошибку. По факту, не смотря на то, что это можно было бы установить из кода, язык принуждает нас самих подтвердить это, опять же помогая программисту держать в голове устойчивую модель программы.

Из-за этого, добавление новых контролируемых исключений (checked exceptions) после сигнатуры метода нарушает исходную совместимость.

Пример:

Было в версии 1.0:

public class Service {
    public void run() {
        System.out.println("running");
    }
}

Клиентский код:

Service s = new Service();
s.run(); // всё компилируется

Стало в версии 2.0:

import java.io.IOException;

public class Service {
    public void run() throws IOException {
        System.out.println("running");
    }
}

Теперь при перекомпиляции клиентский код выдаст ошибку:

error: unreported exception IOException; must be caught or declared to be thrown

Код, который успешно компилировался со старой версией, перестал компилироваться с новой. Компилятор требует обработать исключение — обернуть вызов в try-catch или добавить throws в метод клиента. Это заставит разработчика переписать его код и поможет убедится в том, что он понял и принял, что было внесено обновление, и зафиксировал его ментально.

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

Что меняется	Правило	Пример	Совместимость
Модификатор доступа	Ослабление доступа (public → protected/private)	`public void run() {}` → `private void run() {}`	❌ Несовместимо: код снаружи больше не видит метод
Модификатор доступа	Усиление доступа (private → protected/public)	`private void run() {}` → `public void run() {}`	✅ Совместимо: метод становится доступнее
final	Добавление final к методу	`void run() {}` → `final void run() {}`	❌ Несовместимо на исходном уровне: классы-наследники, переопределявшие метод, перестанут компилироваться
final	Удаление final	`final void run() {}` → `void run() {}`	✅ Совместимо: теперь метод можно переопределять
abstract	Добавление abstract (конкретный → абстрактный)	`void run() {}` → `abstract void run() {}`	❌ Несовместимо: класс теряет реализацию, наследники ломаются
abstract	Удаление abstract (абстрактный → конкретный)	`abstract void run();` → `void run() {}`	✅ Совместимо: реализация появилась
static	Добавление static к методу	`void run() {}` → `static void run() {}`	❌ Несовместимо: вызов через экземпляр перестаёт работать
static	Удаление static	`static void run() {}` → `void run() {}`	❌ Несовместимо: вызов через класс перестаёт работать
native	Добавление/удаление native	любое изменение	✅ Совместимо (для Java-кода прозрачно)
strictfp	Добавление/удаление strictfp	любое изменение	✅ Совместимо
synchronized	Добавление/удаление synchronized	любое изменение	✅ Совместимо (не влияет на контракт)

Исключения (проверяемые). С непроверяемыми (unchecked) исключениями вроде NullPointerException можно делать что угодно.

Добавление новых	`void run()` → `throws IOException`	❌ Нельзя добавлять новые: Компилятор требует обработки
Удаление	`throws IOException` → `void run()`	✅ Можно убирать: Старый код обрабатывал исключение, а теперь его нет — лишний catch не мешает

бла бла бла

3) Верификация

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

Если B <: A (B — подтип A), то везде, где ожидается A, можно передать B.

Это правило подстановки лежит в основе статической проверки корректности взаимодействий между классами. Когда класс-потомок переопределяет метод родителя, система типов должна гарантировать, что потомка можно использовать вместо родителя. Для этого работают общие правила вариантности:

Позиция в сигнатуре	Требуемое отношение	Правило	Почему
Параметры метода (входящие данные)	Контравариантность или инвариантность	Потомок может принимать более общие типы (супертипы), чем родитель	Потомок должен уметь обрабатывать всё, что умел родитель, и даже больше. Если родитель принимал `Dog`, потомок должен принимать как минимум `Dog`, а лучше любого `Animal`. Принимать более узкий тип `Beagle` нельзя.
Возвращаемый тип (исходящие данные)	Ковариантность	Потомок может возвращать более конкретные типы (подтипы), чем родитель	Тот, кто вызывает метод, ожидает получить `Animal`. Потомок может вернуть `Dog` — это всё ещё `Animal`
Исключения (throws) *	Ковариантность (в Java только для проверяемых)	Потомок может выбрасывать более конкретные исключения или не выбрасывать вообще	Никто не ждёт исключений сверх объявленных

* принцип Лискова ничего не говорит про сами исключения, речь лишь идет о совместимости типов исключений.

Следуя логике, что потомок должен уметь работать вместо родителя, то и новая версия библиотеки должна уметь работать вместо предыдущей. На практике это выражено в следующих конкретных примерах для методов и конструкторов:

Позиция	Что происходит / Правило	Пример	Совместимость
Параметры	Добавление нового метода создает перегрузку	`void set(Animal a)` + `void set(Dog d)`	✅ Это перегрузка, оба метода существуют
Параметры	Сужение Ковариантность (тип стал более конкретным — спустились вниз по иерархии)	`void set(Animal a)` → `void set(Dog a)`	❌ Запрещено Старый код мог вызвать `set(new Cat())` . Новый метод принимает только `Dog`
Параметры	Расширение Контравариантность (тип стал более общим — поднялись вверх по иерархии)	`void set(Dog a)` → `void set(Animal a)`	✅ Разрешено Старый код вызывал `set` только с `Dog`. Новый метод принимает `Animal` — значит, `Dog` туда по-прежнему можно передавать.
Возврат	Сужение Ковариантность	`Animal get()` → `Dog get()`	✅ Можно сужать. Старый код ожидает `Animal`, а получает `Dog`. `Dog` — это `Animal`
Возврат	Расширение Контравариантность	`Animal get()` → `Object get()`	❌ Несовместимо Старый код рассчитывает на методы класса `Animal`, а в `Object` их может не быть
Исключения	Переопределение Ковариантность	`throws IOException` → `throws FileNotFoundException`	✅ Можно сужать FileNotFoundException ловится как IOException
Исключения	Переопределение Контравариантность	`throws FileNotFoundException → throws IOException`	❌ Нельзя: IOException шире, старый код, ожидающий FileNotFoundException, может быть не готов к другим IOException

Полиморфизм полей не поддерживается (используйте геттеры):

Сужение/Расширение	Пример	Совместимость	Комментарий
Сужение	`Animal a → Dog a`	❌ Несовместимо	Старый код, который присваивал `Cat` полю `a`, больше не компилируется.
Расширение	`Dog a → Animal a`	❌ Несовместимо	Старый код, который использовал `a` как `Dog`, теперь может видеть любое `Animal`, методы `Dog` могут быть недоступны.

Правила при изменении списка интерфейсов / суперклассов:

Позиция	Изменение	Пример	Совместимость / LSP	Комментарий
Класс (extends)	Сужение	`class A extends Animal → class A extends Dog`	❌ Нарушает LSP	Старый код, использующий `A` как `Animal`, может ломаться.
Класс (extends)	Расширение	`class A extends Dog → class A extends Animal`	✅ Совместимо	Старый код, использующий `A` как `Dog`, всё ещё работает как `Animal`.
Интерфейс (implements)	Убрали интерфейс	`class A implements X,Y → class A implements X`	❌ Нарушает LSP	Старый код, использующий `Y`, теперь не компилируется.
Интерфейс (implements)	Добавили интерфейс	`class A implements X → class A implements X,Y`	✅ Совместимо	Старый код работает, новый функционал добавлен.
Интерфейс (extends)	Сужение	`interface X extends C,D → interface X extends D`	❌ Нарушает LSP	Старый код, который ожидал методы `C`, теперь их может не найти.
Интерфейс (extends)	Расширение	`interface X extends D → interface X extends C,D`	✅ Совместимо	Старый код всё ещё видит методы `D`, новые методы из `C` добавлены безопасно.

Отдельно рассмотрим дженерики. Важно различать область подстановки параметра типа и домен квантора* (тот что указан после ?). При обновлении версий эти области могут сужаться или расширяться, что определяет, будет ли старый код компилироваться или нет. При этом неважно, участвует ли тип в параметре или возврате метода, как раньше.

Изменение	Пример	LSP / Вариантность	Комментарий
Параметр типа ужесточен	`class Box<T>` → `class Box<T extends Animal>`	❌ Сужение области ограничения параметра	Старый код с `Box<String>` больше не компилируется. Подстановка невозможна.
Параметр типа ослаблен	`class Box<T extends Animal>` → `class Box<T>`	✅ Расширение области ограничения параметра	Старые объекты можно подставлять. Подстановка сохраняется.
Wildcard `? extends` ужесточен	`List<? extends Animal>` → `List<? extends Dog>`	❌ Сужение домена ковариантного квантора	Старый код с `List<Cat>` ломается.
Wildcard `? extends` ослаблен	`List<? extends Dog>` → `List<? extends Animal>`	✅ Расширение домена ковариантного квантора	Старый код с `List<Dog>` продолжает работать.
Wildcard `? super` ужесточен	`List<? super Dog>` → `List<? super Bulldog>`	❌ Сужение домена контравариантного квантора	Старый код с `List<Animal>` больше не компилируется.
Wildcard `? super` ослаблен	`List<? super Bulldog>` → `List<? super Dog>`	✅ Расширение домена контравариантного квантора	Старый код с `List<Animal>` продолжает работать.

При этом тип квантора (напр., с super на extends) менять нельзя:

Изменение	Пример	LSP / Вариантность	Комментарий
Wildcard ? super → ? extends	`List<? super Bulldog> → List<? extends Dog>`	❌ Нарушает подстановку	Старый код ломается. Нельзя менять контравариантный список в ковариантный.
Wildcard ? extends → ? super	`List<? extends Bulldog> → List<? super Dog>`	❌ Нарушает подстановку	Старый код ломается. Нельзя менять ковариантный список в контравариантный.

Любая инвариантность в дженериках несовместима, что логично:

Изменение	Пример	LSP / Вариантность	Комментарий
Инвариантный параметр типа	`List<Dog> → List<Animal>`	❌ Несовместимо	Нельзя подставить `List<Dog>` вместо `List<Animal>`. Полная инвариантность.
Wildcard ? extends инвариантный	`List<? extends String> → List<? extends Number>`	❌ Несовместимо	Типы не связаны иерархически, подстановка невозможна.
Wildcard ? super инвариантный	`List<? super String> → List<? super Number>`	❌ Несовместимо	Типы не связаны, подстановка невозможна.

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

Лисков: в предложении, слово "пингвин" всегда можно заменить на "птица", но не всегда "птицу" можно заменить на "пингвина".

4) Сопровождение

В дополнение к проверкам исходной совместимости, которые выполняются при компиляции клиентского кода к новому API, существует и другой уровень — бинарная совместимость. Она проявляется в рантайме, когда уже скомпилированные классы загружаются в JVM и линкуются с новыми версиями .class файлов библиотеки. Я отношу такую совместимость к "сопровождению", так как распространитель бинарников берет на себя ответственность убедится, что его обновления не ломают существующих клиентов (без предупреждения).

И тут правила уже совсем другие, не имеющие ничего общего с Лисковской математикой — в дело вступает чистая инженерия. JVM смотрит только на

Наличие класса/метода/поля с тем же именем
Совпадение сигнатуры (имя + параметры + возвращаемый тип)
Модификаторы доступа (public метод должен оставаться public)

Никаког�� "подтип подходит вместо супертипа" на уровне линковки нет. Если метод ожидал Animal, а в новой версии параметр стал Object — бинарная совместимость сломается, потому что сигнатура set(Animal) и set(Object) — это разные сигнатуры для JVM. Старый вызов будет искать set(Animal) и не найдёт. Поэтому бинарная совместимость жёстче исходной в этом смысле — она требует точного сохранения сигнатур, а не просто подтипизации.

Есть пара моментов, о которых стоит помнить:

Дженерики стираются — в байт-коде сигнатура считается по сырым типам. Это значит, что set(List<String>) → set(List<Integer>) — бинарно совместимы, хотя типы внутри <> разные (List как был List, так и остался).
При перемещении метода вверх по иерархии бинарная совместимость сохраняется, потому что сигнатура метода та же (bark()V) — JVM ищет метод сначала в классе Dog, не находит — идёт в родителя Animal, находит там.
JVM линковка не учитывает throws, поэтому бинарно клиентский код продолжает работать.

Из-за того, что сигнатура считается по erasure, можно вводить типовые параметры для метода, и он останется бинарно совместим:

void method(String)               // method(Ljava/lang/String;)V
→
<T extends String> void method(T) // method(Ljava/lang/String;)V

При этом erasure высчитывается по первой верхней границе дженерика. Если указан просто параметр <T>, то его верхняя граница — Object.

Также интересно, что тип возвращаемого значения можно менять при переопределении на подтип:

class Base { Number get() { return 1; } }
class Derived extends Base { // класс существовал ранее, но
  Integer get() { return 2; }  // добавим новый метод
}

Хотя и новый метод get() перезаписал родительский get (а не создал перегрузку) из-за замены Number на Integer, уже скомпилированный клиент все равно сможет найти метод по старой сигнатуре get()Ljava/lang/Number;, потому что Java создает синтетические мосты:

public Number get() { return this.get(); } // вызывает get()Ljava/lang/Integer;

Подытог

В предыдущих 4 частях мы рассмотрели (вроде) все возможные изменения, которые могут привести к потери совместимости. При наличии исходных несовместимостей, мы получим ошибки компилятора после обновления библиотеки. Это лучший вариант, т.к. здесь мы сразу узнаем, что нужно изменить в наших клиентах. Бинарные несовместимости так или иначе дадут о себе знать, когда начнут выскакивать runtime ошибки. Остается последний

II. Практика

Аудитор: Человеко-Ориентированный Трекер Эволюции Библиотек