PricingLoginStart free
Node.js Backend Development Bootcamp · レッスン

Protoの進化と後方互換性

フィールド番号のルールと予約済みフィールドを使って、サービスコントラクトを安全に進化させます。

レッスン 4/413 ステップ

「Protoの進化と後方互換性」はCoddyKit上の無料Node.js Backend Development Bootcampレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはNode.js Backend Development Bootcamp学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Node.js Backend Development Bootcampコースには全4レッスンが含まれています。

このレッスンの一部はまだ翻訳されておらず、英語で表示されています。

Why Proto Evolution Matters

In a gRPC microservice world, your .proto files are a contract shared between independently deployed services. A producer service and its many consumers rarely upgrade at the exact same moment.

During a rolling deploy you will have old clients talking to new servers and new clients talking to old servers simultaneously. Evolution rules exist so neither side crashes or silently corrupts data.

  • Backward compatible: new code can read data written by old code.
  • Forward compatible: old code can read data written by new code (Protobuf gives this for free if you follow the rules).

Break the rules and you get mismatched fields, lost data, or deserialization that maps bytes to the wrong field.

Field Numbers Are the Real Identity

The single most important idea: on the wire, Protobuf does not send field names. It sends field numbers. The name email is just a label for humans and generated code.

Each encoded field is a tag built from (field_number << 3) | wire_type followed by its value. That means:

  • Renaming a field is harmless on the wire (number unchanged).
  • Changing a field's number is a breaking change — old data for number 2 will be read as a different field.
// Decode a Protobuf tag byte to see how (number, wireType) are packed.
function decodeTag(tagByte) {
  const fieldNumber = tagByte >> 3;
  const wireType = tagByte & 0x07;
  return { fieldNumber, wireType };
}

// 0x12 = 18 = (2 << 3) | 2  => field 2, length-delimited (string/bytes)
console.log(decodeTag(0x12)); // { fieldNumber: 2, wireType: 2 }
// 0x08 = 8 = (1 << 3) | 0   => field 1, varint (int/bool/enum)
console.log(decodeTag(0x08)); // { fieldNumber: 1, wireType: 0 }

A Starting Contract

Here is a v1 message for a user service. Notice every field has an explicit, stable number. In a Node.js backend you typically load this with @grpc/proto-loader and @grpc/grpc-js.

The golden rule going forward: once a field number ships to production, it is permanent. Treat numbers like database primary keys — never reuse, never repurpose.

// user.proto (v1)
// syntax = "proto3";
// package user.v1;
//
// message User {
//   string id    = 1;
//   string name  = 2;
//   string email = 3;
// }

// Loading it in Node.js:
const protoLoader = require('@grpc/proto-loader');
const grpc = require('@grpc/grpc-js');

const pkgDef = protoLoader.loadSync('user.proto', {
  keepCase: true,
  longs: String,
  defaults: true,
});
const userProto = grpc.loadPackageDefinition(pkgDef).user.v1;

Adding Fields Safely

The safest evolution is adding a new field with a brand-new number. Old clients simply ignore tags they do not recognize, and new clients reading old data see the field's default value.

  • In proto3, an unset string defaults to "", numbers to 0, bools to false.
  • So always design new fields so that the default value is a safe, meaningful state.

Below, phone (field 4) is added. A v1 client ignores it; a v2 client reading a v1 payload gets "".

// user.proto (v2) — additive change
// message User {
//   string id    = 1;
//   string name  = 2;
//   string email = 3;
//   string phone = 4;   // NEW, never-before-used number
// }

// New server filling the new field:
function buildUserV2(row) {
  return {
    id: row.id,
    name: row.name,
    email: row.email,
    phone: row.phone ?? '', // safe default if missing
  };
}

module.exports = { buildUserV2 };

Forward Compatibility: Unknown Fields

When an old server receives a message containing fields it does not know about, Protobuf preserves them as unknown fields (in many runtimes) rather than erroring. This is what makes forward compatibility work.

The practical consequence: a service in the middle of a pipeline can receive a newer message, and as long as it does not re-serialize destructively, the new data can pass through untouched.

You should never rely on a field not existing. Always tolerate extra data.

The Danger of Reusing Numbers

Suppose you delete email = 3 and later add country = 3. Disaster: an old client still sends an email string tagged with field 3. The new server happily decodes those bytes as if they were country.

Because field numbers are the wire identity, reuse causes silent data corruption — no exception, just wrong values flowing through your system.

The fix is to permanently retire deleted numbers so no future engineer can accidentally recycle them.

// Simulate the bug: bytes meant for field 3 = 'email'
// get reinterpreted by a schema that now calls field 3 'country'.
const wire = { '1': 'u-1', '2': 'Ada', '3': 'ada@mail.com' };

const v1Schema = { '1': 'id', '2': 'name', '3': 'email' };
const badV2Schema = { '1': 'id', '2': 'name', '3': 'country' }; // reused 3!

function applySchema(wireMsg, schema) {
  const out = {};
  for (const [num, val] of Object.entries(wireMsg)) out[schema[num]] = val;
  return out;
}

console.log(applySchema(wire, v1Schema));
// { id: 'u-1', name: 'Ada', email: 'ada@mail.com' }
console.log(applySchema(wire, badV2Schema));
// { id: 'u-1', name: 'Ada', country: 'ada@mail.com' }  <-- corrupted!

Reserved Fields to the Rescue

Protobuf's answer is the reserved keyword. When you remove a field, you reserve its number and its name. The compiler then refuses to let anyone reuse them.

  • reserved 3; — blocks reusing field number 3.
  • reserved "email"; — blocks reusing the name email (helps if old generated code or JSON mapping relies on it).

This turns a silent runtime corruption into a compile-time error, which is exactly where you want failures to happen.

// user.proto (v3) — email removed safely
// message User {
//   reserved 3;            // number can never be reused
//   reserved "email";      // name can never be reused
//
//   string id      = 1;
//   string name    = 2;
//   string phone   = 4;
//   string country = 5;    // new field gets a FRESH number
// }

Reserving Ranges

When you remove several fields at once, reserve them all in one statement. Ranges use to, and max covers the upper bound.

  • reserved 2, 15, 9 to 11; reserves individual numbers and a contiguous block.
  • You can reserve numbers and names in separate statements, but not mix them in a single one.

Keep a running 'graveyard' comment so the history of retired fields is visible to reviewers.

// Reserving multiple removed fields
// message Order {
//   reserved 2, 15, 9 to 11;        // numbers
//   reserved "coupon", "legacy_sku"; // names
//
//   string id        = 1;
//   string status    = 3;
//   int64  total_cents = 16;
// }

Type Changes: What Is and Isn't Safe

Some type changes preserve wire compatibility because the wire type stays the same; others silently break.

  • Safe: int32 ↔ int64 ↔ uint32 ↔ uint64 ↔ bool — all varints (just mind value ranges/truncation).
  • Safe: string ↔ bytes when bytes are valid UTF-8 (both length-delimited).
  • Unsafe: int32 → string, or changing between fixed32 and int32 — different wire types, garbled decode.

When in doubt, add a new field instead of mutating an existing one.

// Wire-type families: a quick reference table.
const wireTypes = {
  0: 'varint  (int32/int64/uint/bool/enum)',
  1: '64-bit  (fixed64/sfixed64/double)',
  2: 'length  (string/bytes/messages/packed)',
  5: '32-bit  (fixed32/sfixed32/float)',
};

// Changing a field is wire-safe only within the SAME family.
function sameFamily(aWire, bWire) {
  return aWire === bWire;
}
console.log(sameFamily(0, 0)); // int32 -> int64  => true (safe)
console.log(sameFamily(0, 2)); // int32 -> string => false (UNSAFE)

Evolving Enums Carefully

Enums evolve too. In proto3 every enum must have a zero value (the default), conventionally *_UNSPECIFIED = 0. You can append new values safely — old clients receiving an unknown enum number keep the raw integer and treat it as unrecognized.

  • Always handle the default/unknown case in your Node.js switch logic.
  • Never renumber existing enum values; reserve removed ones just like fields.
// enum Status { STATUS_UNSPECIFIED = 0; ACTIVE = 1; SUSPENDED = 2; }
// v2 appends CLOSED = 3.

function describeStatus(status) {
  switch (status) {
    case 1: return 'active';
    case 2: return 'suspended';
    case 3: return 'closed';
    default:
      // Covers 0 (UNSPECIFIED) AND any future value an old
      // build doesn't know about yet — forward compatible.
      return 'unknown';
  }
}

console.log(describeStatus(1)); // active
console.log(describeStatus(99)); // unknown (future value)

A Safe-Evolution Checklist in CI

Teams enforce these rules automatically. Tools like buf run breaking-change detection in CI, but you can also encode simple invariants yourself. The core invariants:

  • No field number is ever removed without a matching reserved.
  • No field number changes its type family.
  • New fields use numbers higher than any previously used or reserved.

Below is a tiny guard you might run against two parsed schema snapshots in a Node.js pipeline step.

// Detect a reused/removed number that wasn't reserved.
function checkBreaking(oldFields, newFields, reserved) {
  const issues = [];
  for (const [num, type] of Object.entries(oldFields)) {
    const stillPresent = newFields[num];
    if (!stillPresent && !reserved.includes(Number(num))) {
      issues.push(`field ${num} removed but not reserved`);
    } else if (stillPresent && stillPresent !== type) {
      issues.push(`field ${num} changed type ${type} -> ${stillPresent}`);
    }
  }
  return issues;
}

const oldF = { 1: 'string', 2: 'string', 3: 'string' };
const newF = { 1: 'string', 2: 'string' }; // dropped 3
console.log(checkBreaking(oldF, newF, []));
// [ 'field 3 removed but not reserved' ]
console.log(checkBreaking(oldF, newF, [3])); // []

Quick Check

You are removing the email field (number 3) from a deployed proto message. What is the correct way to keep the contract evolvable and prevent future corruption?

対話的なレッスンで答える

Recap

You now know how to evolve gRPC contracts without breaking running services:

  • Field numbers, not names, are the wire identity — they are permanent once shipped.
  • Add fields with fresh numbers; old clients ignore them and new clients see safe defaults.
  • Protobuf preserves unknown fields, giving you forward compatibility for free.
  • Reserve removed numbers and names (reserved 3; reserved "email";) to prevent silent corruption from reuse.
  • Change types only within the same wire-type family; otherwise add a new field.
  • Append enum values, always handle the unknown/UNSPECIFIED case, and enforce all of this in CI.

Follow these rules and old and new versions of your services can coexist safely through every rolling deploy.

無料で開始

AI チューターと学ぶ JavaScript — 無料

ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。

コース
22
レッスン
92
無料で学習を始めるコース全体を表示

よくある質問

「Protoの進化と後方互換性」レッスンは無料ですか？

はい。「Protoの進化と後方互換性」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Node.js Backend Development Bootcampコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Node.js Backend Development Bootcampコースには全4レッスンが含まれています。

「Protoの進化と後方互換性」で何を学びますか？

フィールド番号のルールと予約済みフィールドを使って、サービスコントラクトを安全に進化させます。 ブラウザで直接実行するハンズオンコードでNode.js Backend Development Bootcampを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

Node.js Backend Development Bootcampを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのNode.js Backend Development Bootcampは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。

「Protoの進化と後方互換性」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このNode.js Backend Development Bootcampレッスンでコードを書いて実行できますか？

はい。すべてのNode.js Backend Development Bootcampレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

  1. Protobuf IDLによるサービスとメッセージの定義
  2. Unary、Server、Client、双方向ストリーミングRPC
  3. インターセプター、デッドライン、メタデータ
  4. Protoの進化と後方互換性
← Node.js Backend Development Bootcampに戻る