Protocol Buffers Getting Started Guide
1. Introduction
Protocol Buffers (protobuf for short) is a language-agnostic, platform-agnostic, extensible mechanism for serializing structured data developed by Google. Compared to serialization methods like JSON and XML, protobuf is smaller, faster, and simpler.
- Project homepage: https://github.com/protocolbuffers/protobuf
- Official documentation: https://protobuf.dev/
2. Installation
2.1 Install protoc Compiler
The protoc compiler is used to compile .proto files into source code for specific programming languages.
- Download the pre-compiled version suitable for your platform from https://github.com/protocolbuffers/protobuf/releases.
- After decompression, copy the
protocexecutable from thebindirectory to a directory included in your system's PATH environment variable (e.g.,/usr/local/bin). - Verify installation:
bash
protoc --version
2.2 Install protobuf Runtime Environment
Different programming languages require the installation of their respective protobuf runtime environments. For example, for Go language:
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
Ensure that $GOPATH/bin is added to your system's PATH environment variable so that protoc can find the protoc-gen-go plugin.
3. Defining Message Types
Create a .proto file to define the data structure. For example, create student.proto:
syntax = "proto3";
package main;
message Student {
string name = 1;
bool male = 2;
repeated int32 scores = 3;
}
Execute the following command in the current directory to generate Go language code:
protoc --go_out=. student.proto
This will generate the student.pb.go file, which contains the Go language implementation of the Student type.
4. Using Generated Code
In Go language, the generated code can be used for data serialization and deserialization.
package main
import (
"fmt"
"log"
"google.golang.org/protobuf/proto"
)
func main() {
student := &Student{
Name: "Alice",
Male: false,
Scores: []int32{90, 95, 100},
}
// 序列化
data, err := proto.Marshal(student)
if err != nil {
log.Fatal("Marshaling error: ", err)
}
// 反序列化
newStudent := &Student{}
err = proto.Unmarshal(data, newStudent)
if err != nil {
log.Fatal("Unmarshaling error: ", err)
}
fmt.Println("Student:", newStudent)
}
5. Field Rules
optional: Indicates that the field is optional; it can be set or left unset. If not set, it will be initialized with its default value.repeated: Indicates that the field can be used any number of times, similar to a dynamic array.
Note: In proto3, the required keyword has been removed, and all fields are optional by default.
6. Enums and Nested Types
You can define enum types and nested message types in a .proto file. For example:
syntax = "proto3";
package main;
message Person {
string name = 1;
int32 id = 2;
string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
string number = 1;
PhoneType type = 2;
}
repeated PhoneNumber phones = 4;
}
7. Backward Compatibility
When updating .proto files, to maintain backward compatibility, you should follow these rules:
- Do not change the field numbers of existing fields.
- Do not delete existing fields.
- You can add new fields, but they must use new numbers.
- You can add new enum values.
Following these rules ensures that older code can still parse new message formats.
8. More Resources
- Official documentation: https://protobuf.dev/
- Go language support: https://pkg.go.dev/google.golang.org/protobuf
主题测试文章，只做测试使用。发布者：Walker，转转请注明出处：https://walker-learn.xyz/archives/4460
