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 the protoc compiler

The protoc compiler is used to compile .proto files into source code for specific programming languages.

1. Download the pre-compiled version suitable for your platform from https://github.com/protocolbuffers/protobuf/releases.
2. After unzipping, copy the protoc executable from the bin directory to a directory included in your system's PATH environment variable (e.g., /usr/local/bin).
3. Verify installation:

bash
protoc --version

2.2 Install the protobuf runtime environment

Different programming languages require installing 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 your 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 for the Student type.

4. Using the Generated Code

In Go language, you can use the generated code 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 unset, it will be initialized with its default value.
• repeated: Indicates that the field can be repeated 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, the following rules should be observed to maintain backward compatibility:

• Do not change the field numbers of existing fields.
• Do not delete existing fields.
• New fields can be added, but they must use new field numbers.
• New enum values can be added.

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