高级特性

一、Optional 字段

1.1 Proto3 中的 Optional

syntax = "proto3";

message User {
  int32 id = 1;
  string name = 2;
  optional string nickname = 3;  // 可选字段
  optional int32 age = 4;        // 可选字段
}

1.2 Go 中使用

user := &pb.User{
    Id:   1,
    Name: "张三",
}

// 检查是否设置
if user.Nickname != nil {
    fmt.Println("昵称:", *user.Nickname)
}

// 设置可选字段
nickname := "小张"
user.Nickname = &nickname

二、字段选项

2.1 deprecated 选项

message User {
  int32 id = 1;
  string name = 2;
  string old_field = 3 [deprecated = true];  // 标记为废弃
}

2.2 json_name 选项

message User {
  int32 user_id = 1 [json_name = "userId"];
  string user_name = 2 [json_name = "userName"];
}

2.3 packed 选项

message Numbers {
  // Proto3 默认 packed
  repeated int32 values = 1 [packed = true];
}

三、自定义选项

3.1 定义选项

import "google/protobuf/descriptor.proto";

extend google.protobuf.FieldOptions {
  optional string my_option = 50001;
}

message User {
  string name = 1 [(my_option) = "custom value"];
}

四、Well-Known Types

4.1 Wrapper Types

import "google/protobuf/wrappers.proto";

message User {
  google.protobuf.Int32Value age = 1;      // 可空整数
  google.protobuf.StringValue name = 2;    // 可空字符串
  google.protobuf.BoolValue active = 3;    // 可空布尔
}

import "google.golang.org/protobuf/types/known/wrapperspb"

user := &pb.User{
    Age:    wrapperspb.Int32(25),
    Name:   wrapperspb.String("张三"),
    Active: wrapperspb.Bool(true),
}

// 检查是否为 nil
if user.Age != nil {
    fmt.Println("年龄:", user.Age.Value)
}

4.2 Struct 类型

import "google/protobuf/struct.proto";

message Response {
  google.protobuf.Struct data = 1;  // 动态 JSON 对象
}

import "google.golang.org/protobuf/types/known/structpb"

data, _ := structpb.NewStruct(map[string]interface{}{
    "name": "张三",
    "age":  25,
    "tags": []interface{}{"admin", "user"},
})

response := &pb.Response{Data: data}

4.3 FieldMask

import "google/protobuf/field_mask.proto";

message UpdateUserRequest {
  User user = 1;
  google.protobuf.FieldMask update_mask = 2;
}

import "google.golang.org/protobuf/types/known/fieldmaskpb"

req := &pb.UpdateUserRequest{
    User: &pb.User{
        Id:    1,
        Name:  "新名字",
        Email: "new@example.com",
    },
    UpdateMask: &fieldmaskpb.FieldMask{
        Paths: []string{"name", "email"},  // 只更新这些字段
    },
}

五、编码原理

5.1 Wire Types

Wire Type	含义	用于
0	Varint	int32, int64, uint32, uint64, bool, enum
1	64-bit	fixed64, sfixed64, double
2	Length-delimited	string, bytes, embedded messages, repeated
5	32-bit	fixed32, sfixed32, float

5.2 Varint 编码

数字 300 的编码：
300 = 100101100 (二进制)

编码过程：
1. 分成 7 位一组：0000010 0101100
2. 低位在前，高位在后
3. 除最后一组外，最高位设为 1

结果：10101100 00000010 (0xAC 0x02)

5.3 字段编码

字段编码 = (field_number << 3) | wire_type

例如：字段编号 1，类型 string (wire_type = 2)
编码 = (1 << 3) | 2 = 10 = 0x0A

六、版本兼容

6.1 向后兼容规则

// 旧版本
message User {
  int32 id = 1;
  string name = 2;
}

// 新版本（向后兼容）
message User {
  int32 id = 1;
  string name = 2;
  string email = 3;  // 新增字段
  // reserved 4;     // 保留已删除字段的编号
}

6.2 兼容性规则

可以做：

• 添加新字段
• 删除字段（保留编号）
• 重命名字段
• 将 optional 改为 repeated

不能做：

• 修改字段编号
• 修改字段类型（大多数情况）
• 删除 required 字段（proto2）

6.3 保留字段

message User {
  reserved 2, 15, 9 to 11;
  reserved "old_name", "old_email";
  
  int32 id = 1;
  string name = 3;
}

七、JSON 映射

7.1 默认映射

message User {
  int32 user_id = 1;      // JSON: "userId"
  string user_name = 2;   // JSON: "userName"
}

7.2 自定义 JSON 名称

message User {
  int32 user_id = 1 [json_name = "id"];
  string user_name = 2 [json_name = "name"];
}

7.3 Go 中的 JSON 转换

import "google.golang.org/protobuf/encoding/protojson"

user := &pb.User{
    UserId:   1,
    UserName: "张三",
}

// Protobuf 转 JSON
jsonData, _ := protojson.Marshal(user)
fmt.Println(string(jsonData))

// JSON 转 Protobuf
newUser := &pb.User{}
protojson.Unmarshal(jsonData, newUser)

八、反射

8.1 获取消息描述

import "google.golang.org/protobuf/reflect/protoreflect"

user := &pb.User{Id: 1, Name: "张三"}

// 获取消息描述
md := user.ProtoReflect().Descriptor()
fmt.Println("消息名:", md.Name())
fmt.Println("字段数:", md.Fields().Len())

// 遍历字段
fields := md.Fields()
for i := 0; i < fields.Len(); i++ {
    fd := fields.Get(i)
    fmt.Printf("字段: %s, 类型: %s\n", fd.Name(), fd.Kind())
}

8.2 动态访问字段

user := &pb.User{Id: 1, Name: "张三"}
m := user.ProtoReflect()

// 获取字段值
nameField := m.Descriptor().Fields().ByName("name")
nameValue := m.Get(nameField)
fmt.Println("Name:", nameValue.String())

// 设置字段值
m.Set(nameField, protoreflect.ValueOfString("李四"))

九、性能优化

9.1 复用消息对象

// 使用 sync.Pool 复用对象
var userPool = sync.Pool{
    New: func() interface{} {
        return &pb.User{}
    },
}

func processUser(data []byte) {
    user := userPool.Get().(*pb.User)
    defer func() {
        user.Reset()  // 重置消息
        userPool.Put(user)
    }()
    
    proto.Unmarshal(data, user)
    // 处理 user
}

9.2 预分配切片

// 预分配 repeated 字段
users := make([]*pb.User, 0, 100)
for i := 0; i < 100; i++ {
    users = append(users, &pb.User{Id: int32(i)})
}

list := &pb.UserList{Users: users}

9.3 使用 MarshalAppend

// 复用缓冲区
buf := make([]byte, 0, 1024)
buf, err := proto.MarshalOptions{}.MarshalAppend(buf, user)

十、总结