Opções personalizadas do Protobuf

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.

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.

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:

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.

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:

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:

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

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.)

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.

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.