API Best Practices ~関連するフィールドは新しいメッセージにグループ化し凝集性の高いフィールドのみを入れ子にする

関連するフィールドは新しいメッセージにグループ化し凝集性の高いフィールドのみを入れ子にする

フィールドが密接に関連している場合、サーバー内部で一緒にやり取りすることがよくあります。
その場合、関連するフィールドをまとめた新しいメッセージを定義すると簡単です。

関連するフィールドを新しいメッセージにグループ化する様子：

message Foo {
  // Bad: 関連フィールドを個別に追加していくのはよくない
  optional int price;
  optional CurrencyType currency;

  // Better: 関連するフィールドは新しいメッセージにグループ（カプセル）化する
  optional CurrencyAmount price;
}

message CurrencyAmount {
  optional int price = 1;
  optional CurrencyType currency = 2;
}

このような疎結合が一般的にベストプラクティスとして受け入れられていますが、.proto ファイルを設計する際には必ずしも当てはまるわけではありません。
後で特殊なフィールドを追加することを想定して、2 つの情報単位を緊密に結合する (一方をもう一方の中にネストする) ケースがあるかもしれません。

たとえば、現時点ではかなり汎用的なフィールドのセットを作成している場合でも、後で専用のフィールドを追加することを想定している場合は、そのメッセージをこの .proto ファイルまたは他の .proto ファイルの別の場所から参照しないように、メッセージをネストさせることで抑制できます。

message Photo {
  // Bad: MetadataはPhotoの範囲外で再利用される可能性が高いので、ネストせずにアクセスしやすくするのが良いだろう。
  message Metadata {
    optional int32 width = 1;
    optional int32 height = 2;
  }
  optional Metadata photo_metadata = 1;
}

message FooConfiguration {
  // Good: RuleをFooConfigurationのスコープ外で再利用することは、無関係である可能性の高いコンポーネントと密結合させることになるが、ネストすることでそれを防ぐことができる。
  message Rule {
    optional float multiplier = 1;
  }
  repeated Rule rules = 1;
}