0Pricing
gRPC & High Performance APIs · レッスン

カスタムProtobufオプション

カスタムオプションを使ってProtobufを拡張し、定義にメタデータや設定を追加する方法を学習します。

「カスタムProtobufオプション」はCoddyKit上の無料gRPC & High Performance APIsレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはgRPC & High Performance APIs学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 gRPC & High Performance APIsコースには全4レッスンが含まれています。

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

Extend Protobuf with Options

Protobuf is powerful for defining structured data, but what if you need to add extra metadata or configuration that isn't part of your data structure itself?

This is where custom options come in! They let you extend the Protobuf definition language, adding annotations to files, messages, fields, enums, or services.

Why Use Custom Options?

Custom options are like adding sticky notes to your Protobuf definitions. They don't change the actual data sent over the wire, but they provide valuable context for code generation or runtime behavior.

  • Validation: Mark fields with min/max lengths.
  • Documentation: Add richer descriptions for API tools.
  • Code Generation: Influence how language-specific code is generated.
  • Runtime Behavior: Configure logging levels or caching strategies.

Defining a Custom Option

To create a custom option, you first define it in its own .proto file. You use the extend keyword to declare that you are adding new options to existing Protobuf elements.

For example, to add an option to a message:

// my_options.proto
syntax = "proto3";

package mypackage;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions {
  string api_version = 1000;
}

Breaking Down Option Definition

Let's look closer at our custom option definition:

  • import "google/protobuf/descriptor.proto";: This is crucial! It provides access to standard Protobuf option types like MessageOptions, FieldOptions, etc.
  • extend google.protobuf.MessageOptions: This tells Protobuf we're adding an option that can be applied to messages.
  • string api_version = 1000;: This is our custom option. It's a string, named api_version, and 1000 is its unique field number. Custom option field numbers should be high (e.g., 500 and above) to avoid conflicts with future standard options.

Applying a Message-Level Option

Once defined, you can apply your custom option to any message in your .proto files. Remember to import your options definition file!

Here's how to use the api_version option on a User message:

// my_service.proto
syntax = "proto3";

package mypackage;

import "my_options.proto"; // Import our custom options

message User {
  option (mypackage.api_version) = "v1.0"; // Apply the option
  string name = 1;
  int32 id = 2;
}

Custom Field-Level Option

You can also define options for individual fields. Let's create a validation_regex option for string fields to ensure they match a specific pattern.

First, update your my_options.proto:

// my_options.proto (updated)
syntax = "proto3";

package mypackage;

import "google/protobuf/descriptor.proto";

extend google.protobuf.MessageOptions {
  string api_version = 1000;
}

extend google.protobuf.FieldOptions {
  string validation_regex = 1001; // New field option
}

Applying the Field Option

Now, let's use our new validation_regex option on fields within a message. This could guide a validation library or UI generator.

// my_service.proto (updated)
syntax = "proto3";

package mypackage;

import "my_options.proto";

message User {
  option (mypackage.api_version) = "v1.0";
  string name = 1 [(mypackage.validation_regex) = "^[A-Z][a-z]+$"];
  int32 id = 2;
  string email = 3 [(mypackage.validation_regex) = "^\\S+@\\S+\\.\\S+$"];
}

Accessing Options in Code

After compiling your .proto files, the generated code will include methods to access these custom options. The exact API varies by language, but the concept is similar.

For example, in Java, you'd retrieve the descriptor for the message or field and then access the option value. (This is conceptual and requires a full Protobuf setup to run.)

// Example in Java (conceptual)
// import com.google.protobuf.Descriptors.FieldDescriptor;
// import com.google.protobuf.Descriptors.Descriptor;
// import mypackage.MyOptions; // Generated options class
// import mypackage.MyServiceProto; // Generated service proto class

// public class OptionReader {
//   public static void main(String[] args) {
//     Descriptor userDescriptor = MyServiceProto.User.getDescriptor();
//     String apiVersion = userDescriptor.getOptions()
//                                       .getExtension(MyOptions.api_version);
//     System.out.println("User API Version: " + apiVersion);
//
//     FieldDescriptor nameField = userDescriptor.findFieldByName("name");
//     String nameRegex = nameField.getOptions()
//                                 .getExtension(MyOptions.validation_regex);
//     System.out.println("Name Regex: " + nameRegex);
//   }
// }

Option Best Practices

When using custom options, consider these best practices:

  • Unique Field Numbers: Always use high field numbers (e.g., 500+) to avoid conflicts with future standard Protobuf options.
  • Separate Proto Files: Define options in their own .proto file for better organization and reusability.
  • Clear Naming: Give options descriptive names (e.g., validation_regex instead of just regex).
  • Language Support: Ensure your chosen programming language's Protobuf implementation provides methods to easily access custom options.

Check Your Understanding

You've learned how to define and use custom options. Now, let's test your knowledge!

Recap: Custom Options

In this lesson, you learned how to extend Protobuf definitions with custom options. These options allow you to add metadata or configuration to files, messages, and fields without altering the core data payload.

We covered defining options using the extend keyword, applying them to your definitions, and understanding how they can be accessed in generated code for various use cases like validation or influencing code generation.

よくある質問

「カスタムProtobufオプション」レッスンは無料ですか？

はい。「カスタムProtobufオプション」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、gRPC & High Performance APIsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 gRPC & High Performance APIsコースには全4レッスンが含まれています。

「カスタムProtobufオプション」で何を学びますか？

カスタムオプションを使ってProtobufを拡張し、定義にメタデータや設定を追加する方法を学習します。 ブラウザで直接実行するハンズオンコードでgRPC & High Performance APIsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

gRPC & High Performance APIsを始めるのに経験は必要ですか？

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

「カスタムProtobufオプション」レッスンにはどのくらい時間がかかりますか？

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

このgRPC & High Performance APIsレッスンでコードを書いて実行できますか？

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

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

  1. Protobufのベストプラクティス
  2. スキーマ進化の戦略
  3. カスタムProtobufオプション
  4. oneof、マップ、Well-Known Types
← gRPC & High Performance APIsに戻る