Master Java Serialization: Common Pitfalls and Best Practices

Background Introduction

Serialization and Deserialization are everyday tasks for engineers, especially in micro‑service development. For beginners the term can be confusing, so think of it like a magic trick: turning an object into a byte stream (serialization) and turning the byte stream back into an object (deserialization).

In programming terms, serialization converts an object into a byte stream that any computer can understand; deserialization restores the byte stream back into a usable object. The main goal is to enable cross‑platform storage and network transmission.

Early Internet serialization methods included COM (Windows‑only, not truly cross‑platform) and CORBA (cross‑platform but complex and now obsolete). Modern formats such as XML, JSON, Protobuf, Thrift, and Avro each have strengths, and the choice depends on factors like cross‑platform support, speed, and payload size.

Code Practice

Java serialization is simple: implement Serializable and define the class.

public class Student implements Serializable {
    private String name;
    private Integer age;
    public Student(String name, Integer age) {
        this.name = name;
        this.age = age;
    }
    @Override
    public String toString() {
        return "Student{name='" + name + "', age=" + age + "}";
    }
}

Testing serialization and deserialization:

public class ObjectMainTest {
    public static void main(String[] args) throws Exception {
        serialize();
        deserialize();
    }
    private static void serialize() throws Exception {
        Student s = new Student("张三", 20);
        System.out.println(s);
        ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("object.log"));
        oos.writeObject(s);
        oos.close();
    }
    private static void deserialize() throws Exception {
        ObjectInputStream ois = new ObjectInputStream(new FileInputStream("object.log"));
        Student s = (Student) ois.readObject();
        ois.close();
        System.out.println(s);
    }
}

Output shows successful round‑trip.

Serialization Issues Summary

Static fields cannot be serialized

Fields marked static belong to the class, not the instance, so they are not included in the serialized form.

Transient fields are ignored

Fields marked transient are deliberately excluded; after deserialization they become null or default values.

public class Student implements Serializable {
    private transient String name;
    private Integer age;
    // ...
}

serialVersionUID mismatches

Every Serializable class has a version identifier. If you do not define it, the JVM generates one based on class structure. Changing the class without updating the UID causes InvalidClassException during deserialization.

private static final long serialVersionUID = 1L;

Demonstration: serializing a class without a custom UID, then adding a field or changing the UID leads to deserialization failure.

Inheritance serialization

If a parent class does not implement Serializable, its fields are not serialized even when the child does. If the parent implements Serializable, all inherited fields are serialized.

// Parent not serializable, Child serializable
class Parent { private String name; }
class Child extends Parent implements Serializable { private String id; }
// After serialization, "name" becomes null on deserialization.

Custom serialization with Externalizable

For fine‑grained control, implement Externalizable, which requires a no‑arg constructor and explicit writeExternal / readExternal methods.

public class Person implements Externalizable {
    private String name;
    private int age;
    public Person() { System.out.println("Person: empty"); }
    public Person(String name, int age) { this.name = name; this.age = age; }
    @Override
    public void writeExternal(ObjectOutput out) throws IOException {
        out.writeObject(name);
        out.writeInt(age);
    }
    @Override
    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
        name = (String) in.readObject();
        age = in.readInt();
    }
    @Override
    public String toString() { return "Person{name='" + name + "', age=" + age + "}"; }
}

Testing shows custom write/read logic is executed.

Conclusion

Serialization is ubiquitous in Java micro‑service development; forgetting to implement Serializable or ignoring version UID can cause runtime errors. Define a stable serialVersionUID, be aware of static and transient fields, and choose the appropriate format (JSON, Protobuf, etc.) based on cross‑platform needs, performance, and payload size.