gRPC & High Performance APIs · Lezione

Strategie per l'evoluzione degli schemi

Comprenda le tecniche per far evolvere gli schemi Protobuf senza compromettere i client o i servizi esistenti.

Strategie per l'evoluzione degli schemi è una lezione gRPC & High Performance APIs gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento gRPC & High Performance APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso gRPC & High Performance APIs include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Why Schema Evolution Matters

In distributed systems, services and clients often need to communicate using a defined data format, like Protocol Buffers (Protobuf).

Over time, these data structures need to change. Maybe you need to add a new field, remove an old one, or change a type.

Schema evolution is the art of changing your data definitions without breaking existing, older versions of your services or clients. It's crucial for maintaining compatibility in dynamic environments.

The Challenge of Compatibility

When you update a schema, you face two main challenges:

Backward Compatibility: Can an older client still communicate with a newer server? The server must understand the old client's requests.
Forward Compatibility: Can a newer client still communicate with an older server? The server must gracefully ignore new fields it doesn't understand.

Breaking compatibility can lead to service outages and difficult deployments.

Protobuf's Key: Field Numbers

Unlike JSON, where field names are used for identification, Protobuf uses unique field numbers to identify fields in your messages.

These numbers are critical for compatibility. When a message is serialized, only the field numbers and their values are stored, not the field names.

This means:

Field numbers must be unique within a message.
Once assigned, a field number should never change.
Once assigned, a field number should never be reused, even if the field is removed.

Strategy 1: Adding New Fields

Adding new fields is generally safe, provided you follow these rules:

Assign a new, unused field number.
Make the new field optional (or repeated, map in proto3).

Old clients will simply ignore the new field. New clients communicating with old servers will use the field's default value if it's not present.

Try running this Java code example to see how a Protobuf-generated message handles a new field:

import com.google.protobuf.InvalidProtocolBufferException;
import com.google.protobuf.util.JsonFormat;

// Assume these classes are generated from .proto files:
// Original: message User { string name = 1; }
// Evolved:  message User { string name = 1; int32 age = 2; }

// We'll simulate the User class for demonstration purposes.
class User {
  private final String name;
  private final int age;

  private User(Builder builder) {
    this.name = builder.name;
    this.age = builder.age;
  }

  public String getName() { return name; }
  public int getAge() { return age; }

  public static Builder newBuilder() { return new Builder(); }

  public static class Builder {
    private String name = "";
    private int age = 0; // Default value for new field

    public Builder setName(String name) { this.name = name; return this; }
    public Builder setAge(int age) { this.age = age; return this; }
    public User build() { return new User(this); }
  }

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

public class AddFieldEvolution {
  public static void main(String[] args) {
    // Simulate an old client sending data (unaware of 'age')
    User oldClientUser = User.newBuilder()
        .setName("Alice")
        .build();
    System.out.println("Old client sends: " + oldClientUser);

    // Simulate a new server receiving this data.
    // The 'age' field will correctly default to 0.
    System.out.println("New server receives (age): " + oldClientUser.getAge());

    // Simulate a new client sending data (aware of 'age')
    User newClientUser = User.newBuilder()
        .setName("Bob")
        .setAge(30)
        .build();
    System.out.println("New client sends: " + newClientUser);

    // Simulate an old server receiving this data.
    // It will simply ignore the 'age' field.
    System.out.println("Old server receives (name only): " + newClientUser.getName());
  }
}

Strategy 2: Removing Fields

You should never truly delete a field number, as this could lead to data corruption if the number is reused later.

Instead, mark fields as deprecated and reserved:

Use the deprecated = true option to signal that the field should no longer be used. Compilers will issue warnings.
Use the reserved keyword to prevent future assignment of specific field numbers or names. This ensures the number is never accidentally reused.

Here's how you'd mark a field as deprecated and reserve its number:

syntax = "proto3";

package evolution;

message OldMessage {
  string id = 1;
  // This field is deprecated and should not be used.
  string old_data = 2 [deprecated = true];
  string new_data = 3;

  // Reserve field number 2 and the name 'old_data'
  // to prevent accidental reuse in the future.
  reserved 2;
  reserved "old_data";
}

Strategy 3: Renaming Fields

Remember, Protobuf identifies fields by their field numbers, not their names. So, simply changing a field's name in the .proto file is a compatible change.

However, if you also need to change the field number, this is effectively a 'remove' followed by an 'add' operation. In such cases:

Mark the old field number as reserved.
Add a new field with the new name and a new, unused field number.

This ensures that old clients/servers don't get confused by conflicting field numbers.

Strategy 4: Changing Field Types

Changing a field's type is often not backward or forward compatible and should be done with extreme caution.

Some safe changes:

int32 to int64 (values will be truncated if read by old client).
uint32 to uint64.

Unsafe changes (will break compatibility):

int32 to string.
int32 to fixed32.
Any change involving enum, message, or bytes to other types.

If an unsafe type change is unavoidable, treat it as removing the old field and adding a new one with a new number.

Strategy 5: Evolving Enums

Enums are represented as integers. Adding new values to an enum is generally safe, but follow these rules:

Always add new enum values to the end of the list.
Assign a new, unused integer value.
Never change the numeric value of an existing enum member.

Old clients encountering a new enum value will typically see its integer representation, which they might not handle gracefully if they expect only known values. Always include a 0 value as the first enum member for compatibility.

syntax = "proto3";

package evolution;

message StatusUpdate {
  Status current_status = 1;
}

enum Status {
  UNKNOWN = 0;
  PENDING = 1;
  PROCESSING = 2;
  // New status added (safe)
  COMPLETED = 3;
  // Another new status (safe)
  FAILED = 4;
}

Strategy 6: Evolving Oneof Fields

A oneof field means that at most one of the fields within the oneof group can be set at a time.

Evolving oneof fields follows similar rules:

Adding new fields to a oneof is compatible. Assign a new, unused field number. Old clients will ignore these new cases.
Removing fields from a oneof requires deprecating and reserving the field number, just like regular fields.

Be careful when changing existing fields within a oneof, as this can affect compatibility.

Quick Check: Schema Rules

Which of the following actions is generally considered unsafe and likely to break Protobuf compatibility?

Recap: Safe Schema Evolution

Congratulations! You've learned the key strategies for evolving your Protobuf schemas safely:

Field Numbers: Are paramount and must be unique and stable. Never change or reuse them.
Adding Fields: Always assign new numbers; new fields are ignored by old clients.
Removing Fields: Deprecate and reserve field numbers to prevent future reuse.
Renaming Fields: Only change the name, not the number, or treat as remove/add.
Type Changes: Mostly unsafe; avoid or treat as remove/add.
Enums: Add new values to the end, never change existing numbers.

By following these guidelines, you can ensure your gRPC services remain compatible as they evolve.

Domande Frequenti

La lezione «Strategie per l'evoluzione degli schemi» è gratuita?

Sì — il testo completo di «Strategie per l'evoluzione degli schemi» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso gRPC & High Performance APIs, passa a CoddyKit PRO. Il corso gRPC & High Performance APIs include 4 lezioni in totale.

Cosa imparerò in «Strategie per l'evoluzione degli schemi»?

Comprenda le tecniche per far evolvere gli schemi Protobuf senza compromettere i client o i servizi esistenti. Eserciti gRPC & High Performance APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare gRPC & High Performance APIs?

Non è richiesta alcuna esperienza precedente. gRPC & High Performance APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Strategie per l'evoluzione degli schemi»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione gRPC & High Performance APIs?

Sì. Ogni lezione gRPC & High Performance APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a gRPC & High Performance APIs