0Pricing
gRPC & High Performance APIs · 课时

模式演进策略

了解如何演进 Protobuf 模式，同时不破坏现有客户端或服务

模式演进策略 是 CoddyKit 上的免费 gRPC & High Performance APIs 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 gRPC & High Performance APIs 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 gRPC & High Performance APIs 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

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.

常见问题解答

「模式演进策略」课时是免费的吗？

是的 — 「模式演进策略」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 gRPC & High Performance APIs 课程的其余内容，请升级到 CoddyKit PRO。 gRPC & High Performance APIs 课程共包含 4 节课。

「模式演进策略」这节课中我会学到什么？

了解如何演进 Protobuf 模式，同时不破坏现有客户端或服务 你通过在浏览器中直接运行的动手代码来练习 gRPC & High Performance APIs，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 gRPC & High Performance APIs 需要有经验吗？

无需任何先前经验。CoddyKit 上的 gRPC & High Performance APIs 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「模式演进策略」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 gRPC & High Performance APIs 课中编写并运行代码吗？

能。每节 gRPC & High Performance APIs 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. Protobuf 最佳实践
  2. 模式演进策略
  3. 自定义 Protobuf 选项
  4. Oneof、映射与众所周知的类型
← 返回 gRPC & High Performance APIs