gRPC & High Performance APIs · Pelajaran

Strategi Evolusi Skema

Pahami teknik untuk mengembangkan skema Protobuf tanpa merusak klien atau layanan yang sudah ada.

Strategi Evolusi Skema adalah pelajaran gRPC & High Performance APIs gratis di CoddyKit. Ini adalah pelajaran 2 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar gRPC & High Performance APIs, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus gRPC & High Performance APIs mencakup 4 pelajaran total.

Bagian dari pelajaran ini belum diterjemahkan dan ditampilkan dalam bahasa Inggris.

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.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Strategi Evolusi Skema” gratis?

Ya — teks lengkap “Strategi Evolusi Skema” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus gRPC & High Performance APIs, upgrade ke CoddyKit PRO. Kursus gRPC & High Performance APIs mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Strategi Evolusi Skema”?

Pahami teknik untuk mengembangkan skema Protobuf tanpa merusak klien atau layanan yang sudah ada. Kamu berlatih gRPC & High Performance APIs dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai gRPC & High Performance APIs?

Tidak diperlukan pengalaman sebelumnya. gRPC & High Performance APIs di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 2 dari 4.

Berapa lama pelajaran “Strategi Evolusi Skema” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran gRPC & High Performance APIs ini?

Ya. Setiap pelajaran gRPC & High Performance APIs menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

← Kembali ke gRPC & High Performance APIs