serialVersionUID в Java: совместимость версий классов

Вы сохранили объект в файл, добавили в класс один метод — и старый файл больше не читается: readObject() бросает java.io.InvalidClassException: local class incompatible. Виноват serialVersionUID, который вы не объявили.

serialVersionUID — это номер версии сериализуемого класса: поле private static final long serialVersionUID. Номер записывается в поток вместе с объектом, а при десериализации JVM сравнивает его с номером класса в classpath. Номера совпали — объект читается, даже если класс немного изменился. Не совпали — InvalidClassException. Если поле не объявлено, JVM вычисляет номер сама, и он меняется почти при любой правке класса.

Урок продолжает тему сериализации и десериализации в Java: там описаны Serializable, ObjectOutputStream и transient. Здесь разберём, как пережить изменение класса и не потерять уже сохранённые данные.

1. Что такое serialVersionUID

serialVersionUID — идентификатор версии класса для механизма сериализации. JVM учитывает его, только если он объявлен строго так: static final long с именем serialVersionUID. Модификатор доступа может быть любым, но рекомендуется private: поле относится только к своему классу и не наследуется.

import java.io.Serial;
import java.io.Serializable;

public class Cat implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

    private String name;
    private int age;

    public Cat(String name, int age) {
        this.name = name;
        this.age = age;
    }

    @Override
    public String toString() {
        return "Cat{name='" + name + "', age=" + age + "}";
    }
}

Аннотация @Serial (Java 14+) необязательна. Она помечает поле как часть механизма сериализации, чтобы IDE и компилятор (javac с флагом -Xlint:serial в новых JDK) могли проверить объявление. Это полезно: если объявить поле как int или без static, JVM его просто проигнорирует и молча вычислит номер сама.

Обычно статические поля не сериализуются: они принадлежат классу, а не объекту. serialVersionUID — исключение: он попадает в поток, но не как часть состояния объекта, а как часть описания класса (class descriptor), которое ObjectOutputStream пишет перед данными объекта.

2. Как JVM проверяет версию класса

При десериализации ObjectInputStream сначала читает из потока описание класса: имя, serialVersionUID и список полей с типами. Затем находит класс с тем же именем в classpath и сравнивает номера:

1. Номера не совпали — чтение прерывается с InvalidClassException: local class incompatible. Поля даже не сравниваются.
2. Номера совпали — JVM сопоставляет поля по имени. Поле есть и в потоке, и в классе — получает значение из потока. Поле есть только в классе — получает значение по умолчанию (null, 0, false). Поле есть только в потоке — его значение пропускается.
3. Если у одноимённого поля изменился тип, чтение снова завершается ошибкой (подробности — в разделе 5).

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

3. Что будет, если не объявить serialVersionUID

Если поля нет, JVM вычисляет номер по умолчанию: берёт хеш SHA-1 от структуры класса. В расчёт входят:

• имя класса и его модификаторы;
• имена реализованных интерфейсов;
• все поля, кроме private static и private transient (имя, модификаторы, тип);
• наличие статического блока инициализации;
• все не-private конструкторы и методы (имя, модификаторы, сигнатура).

Поэтому номер меняется от правок, которые никак не затрагивают сохранённые данные: добавили публичный метод, сделали класс final, добавили интерфейс. Кроме того, номер зависит от синтетических членов, которые компилятор генерирует для вложенных и анонимных классов, — javac и компилятор Eclipse могут вычислить разные значения для одного и того же исходника.

Проверим. Класс без serialVersionUID:

public class Cat implements Serializable {
    private String name;
    private int age;
    // конструктор и toString() - как выше
}

Сохраняем объект:

import java.io.*;

public class SaveCat {
    public static void main(String[] args) throws IOException {
        try (ObjectOutputStream out = new ObjectOutputStream(new FileOutputStream("cat.ser"))) {
            out.writeObject(new Cat("Мурка", 3));
        }
    }
}

Теперь добавляем в Cat метод, который не трогает поля:

public void meow() {
    System.out.println(name + ": мяу");
}

И читаем старый файл:

import java.io.*;

public class LoadCat {
    public static void main(String[] args) throws IOException, ClassNotFoundException {
        try (ObjectInputStream in = new ObjectInputStream(new FileInputStream("cat.ser"))) {
            Cat cat = (Cat) in.readObject();
            System.out.println(cat);
        }
    }
}

Exception in thread "main" java.io.InvalidClassException: Cat; local class incompatible:
stream classdesc serialVersionUID = 4425893317461758209, local class serialVersionUID = -6302743921569021477

Конкретные числа у вас будут другими, но смысл тот же: данные не изменились, а прочитать их нельзя. Если в класс Cat с самого начала добавить private static final long serialVersionUID = 1L;, тот же сценарий выведет Cat{name='Мурка', age=3}.

4. InvalidClassException: причины и исправление

java.io.InvalidClassException — наследник IOException, который бросает ObjectInputStream, когда класс в classpath не подходит к данным в потоке. Текст после имени класса подсказывает причину:

Смена ссылочного типа поля (например, String → StringBuilder) выдаёт другое исключение — ClassCastException: cannot assign instance of java.lang.String to field Cat.name of type java.lang.StringBuilder. Причина и исправление те же, что во второй строке таблицы.

5. Совместимые и несовместимые изменения класса

Совместимое изменение — такое, после которого новая версия класса читает данные старой (и наоборот) без исключений. Список взят из спецификации Java Object Serialization (глава 5.6). Важное условие: все «совместимые» изменения работают, только если serialVersionUID объявлен явно и не менялся. Без него ломается даже добавление метода.

Проверим оба случая на классе Cat с serialVersionUID = 1L. Сохраним new Cat("Мурка", 3), а потом добавим поле и обновим toString():

public class Cat implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

    private String name;
    private int age;
    private String color; // новое поле

    @Override
    public String toString() {
        return "Cat{name='" + name + "', age=" + age + ", color=" + color + "}";
    }
}

Cat{name='Мурка', age=3, color=null}

Старый файл прочитался, новое поле равно null. А теперь вместо добавления поля поменяем тип age с int на long:

Exception in thread "main" java.io.InvalidClassException: Cat; incompatible types for field age

Совпадающий serialVersionUID не спасает: JVM не умеет сама преобразовать int из потока в поле long.

6. Как изменить класс и сохранить старые данные

Если новому полю не подходит значение по умолчанию, задайте его в методе readObject(). JVM вызывает этот private-метод при десериализации, а in.defaultReadObject() внутри него читает поля стандартным способом:

public class Cat implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;

    private String name;
    private int age;
    private String color;

    @Serial
    private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
        in.defaultReadObject();
        if (color == null) {
            color = "не указан"; // в старых файлах поля color нет
        }
    }
    // toString() - как выше
}

Cat{name='Мурка', age=3, color=не указан}

Для несовместимых изменений (смена типа, переименование, перенос в другой пакет) универсального приёма нет. Варианты:

• Не менять старое поле, а добавить новое. Оставьте int age, добавьте long ageInDays и заполните его в readObject() из старого поля.
• Сделать миграцию. Прочитайте старые файлы программой со старой версией класса, сохраните данные в новом виде, а потом обновите класс.
• Сознательно сменить версию. Увеличьте serialVersionUID (например, до 2L), если старые данные больше не нужны: попытка прочитать их сразу закончится понятной ошибкой, а не тихо испорченным объектом.

Если данные должны жить долго или читаться другими программами, надёжнее хранить их не во встроенном формате Java, а в JSON (Jackson, Gson) или Protobuf: там правила эволюции схемы проще и не зависят от структуры Java-класса.

7. Какое значение выбрать: 1L или сгенерированное

Значение может быть любым: JVM проверяет только совпадение. Есть два типичных случая:

• Новый класс, который ещё ни разу не сериализовался, — пишите 1L. Это просто, читается как «версия 1», и при несовместимом изменении её легко увеличить до 2L.
• Старый класс без serialVersionUID, данные которого уже лежат в файлах или кэше, — объявите тот номер, который JVM вычисляла раньше. Иначе вы сами сломаете чтение. Номер берут из сообщения InvalidClassException (значение stream classdesc) или утилитой serialver из JDK, запущенной на старой версии класса:

serialver -classpath . Cat
Cat:    private static final long serialVersionUID = 4425893317461758209L;

IntelliJ IDEA тоже умеет генерировать такое значение: включите инспекцию Serializable class without 'serialVersionUID' и примените быстрое исправление (Alt+Enter).

8. serialVersionUID в иерархии, enum и record

Иерархия. Каждый сериализуемый класс проверяется отдельно: в поток пишутся описания и класса объекта, и всех его сериализуемых родителей. Если Cat extends Animal и оба реализуют Serializable, объявите serialVersionUID в каждом. Изменение номера в Animal сломает чтение всех сохранённых объектов Cat, даже если в самом Cat ничего не менялось. Объявлять номер в родителе «за всех» бесполезно: JVM ищет поле только в самом классе, а не в предках.

enum. Перечисления сериализуются по имени константы, а их serialVersionUID всегда равен 0L. Объявлять его не нужно — JVM всё равно проигнорирует объявление.

record. Записи (Java 16+) десериализуются через канонический конструктор. Проверка совпадения serialVersionUID для них отключена, поэтому номер можно не объявлять.

9. Предупреждения IDE и компилятора

Многие впервые встречают serialVersionUID не в своём коде, а в предупреждении IDE. Чаще всего оно появляется на собственном исключении или классе Swing: Throwable и Component реализуют Serializable, поэтому все их наследники тоже сериализуемые.

• Eclipse: The serializable class MyException does not declare a static final serialVersionUID field of type long.
• IntelliJ IDEA: инспекция Serializable class without 'serialVersionUID' (по умолчанию выключена).
• javac: с флагом -Xlint:serial — serializable class MyException has no definition of serialVersionUID.

public class OrderNotFoundException extends RuntimeException {
    @Serial
    private static final long serialVersionUID = 1L;

    public OrderNotFoundException(String message) {
        super(message);
    }
}

Если объекты класса никогда не сериализуются, предупреждение безопасно подавить через @SuppressWarnings("serial"). Но объявить serialVersionUID = 1L почти так же коротко, и это защитит класс, если позже его всё-таки начнут сериализовать (например, исключение передадут через RMI или сохранят в HTTP-сессии).