gRPC & High Performance APIs · Lektion

Strategien zur Schema-Evolution

Verstehen Sie Techniken zur Weiterentwicklung von Protobuf-Schemas, ohne bestehende Clients oder Services zu beeinträchtigen.

Strategien zur Schema-Evolution ist eine kostenlose gRPC & High Performance APIs-Lektion auf CoddyKit. Dies ist Lektion 2 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des gRPC & High Performance APIs-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der gRPC & High Performance APIs-Kurs umfasst insgesamt 4 Lektionen.

Teile dieser Lektion wurden noch nicht übersetzt und werden auf Englisch angezeigt.

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.

Häufig gestellte Fragen

Ist die Lektion „Strategien zur Schema-Evolution“ kostenlos?

Ja — der vollständige Text von „Strategien zur Schema-Evolution“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des gRPC & High Performance APIs-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der gRPC & High Performance APIs-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Strategien zur Schema-Evolution“?

Verstehen Sie Techniken zur Weiterentwicklung von Protobuf-Schemas, ohne bestehende Clients oder Services zu beeinträchtigen. Du übst gRPC & High Performance APIs mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um gRPC & High Performance APIs zu starten?

Keine Vorkenntnisse erforderlich. gRPC & High Performance APIs auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 2 von 4.

Wie lange dauert die Lektion „Strategien zur Schema-Evolution“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser gRPC & High Performance APIs-Lektion Code schreiben und ausführen?

Ja. Jede gRPC & High Performance APIs-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu gRPC & High Performance APIs