Protobuf-SourceCodeInfo 介绍

PB 感觉工具非常成熟，这里主要指的是protoc 提供了很多核心的功能，我们直接拿来即用即可，protoc解析后的 FileDescriptorSet 足够我们去实现 代码生成、生成API文档、协议转换 等全部功能了，这里我核心讲解一下 SourceCodeInfo 的设计，其他部分感觉很好理解！

SourceCodeInfo 介绍

message SourceCodeInfo {
	
  // 从作用域大到小+从前到后的顺序 进行排序
  repeated Location location = 1; 
  
  message Location {
    // 这个表示具体的路径，表示接口定义，实际上也不难理解
    // 例如 [5,0,2,1] 表示的是 enum_type[0].value[1] 它所在的位置，也就是对应的是 `Tow = 2;` 对应的区域
    //
    // 5: 表示字段5，字段名称: enum_type，字段类型: list<DescriptorProto>
    // 0: 表示索引为0，原因是字段5类型是数组
    // 2: 表示字段2，字段名称: value, 字段类: list<EnumValueDescriptorProto>
    // 1: 表示索引为1，原因是字段2类型是数组
    // 
    // 所以我感觉最有意思的实际上还是path这个设计，类似于flat-json这种json-path，但是它的设定是紧凑、巧妙、准确的
    repeated int32 path = 1 [packed = true];
    
    // 这里表示某个 file/message/enum/field/method 所在的位置，用坐标围起来
    // 四坐标[0,0,48,1] : 起始行: 0, 起始列: 0, 结束行: 48, 结束列: 1
    // 三坐标[2,0,42]: 起始行: 2, 起始列: 0, 结束行: 2, 结束列: 42
    repeated int32 span = 2 [packed = true];
    
    // 这里表示头部的comment
    optional string leading_comments = 3;
    
    // 这里表示尾部的comment
    optional string trailing_comments = 4;
    
    // 这里表示 不属于/定义模糊/脱离 的comment （一般不会取这部分作为这个字段/类型的注释）
    repeated string leading_detached_comments = 6;
  }
}


message FileDescriptorSet {
  repeated FileDescriptorProto file = 1;
}

// Describes a complete .proto file.
message FileDescriptorProto {
  optional string name = 1;
  optional string package = 2;
  repeated string dependency = 3;
  repeated int32 public_dependency = 10;
  repeated int32 weak_dependency = 11;
  repeated DescriptorProto message_type = 4;
  repeated EnumDescriptorProto enum_type = 5;
  repeated ServiceDescriptorProto service = 6;
  repeated FieldDescriptorProto extension = 7;
  optional FileOptions options = 8;
  optional SourceCodeInfo source_code_info = 9;
  optional string syntax = 12;
}

// Describes an enum type.
message EnumDescriptorProto {
  optional string name = 1;
  repeated EnumValueDescriptorProto value = 2;
  optional EnumOptions options = 3;
  message EnumReservedRange {
    optional int32 start = 1;  // Inclusive.
    optional int32 end = 2;    // Inclusive.
  }
  repeated EnumReservedRange reserved_range = 4;
  repeated string reserved_name = 5;
}

如何获取 sourcecode info

1. 定义api.proto文件内容如下：

syntax = "proto2";

option java_package = "com.byted.xxx.xxx";

enum Num {
    // 注释
    One = 1; // 注释
    // 注释
    Tow = 2;

    // Three = 3;
    // 1111
    // 222

    // 333
    Four = 4; // 注释
}

// 111
message Request {
    // 1
    // 2
    optional string name = 1;
    /**
    * 123
    */
    repeated int32 nums = 3 [packed = true];
    /* title
    hello world
    */
    map<string, int64> kv = 4;

    required Num num= 5;

    optional  InlineRequest req = 6;
    message InlineRequest {

    }
}

message Response {}

service Demo {
    // 33

    // 22
    rpc MethodName (Request) returns (Response); // 11
    // 44
}

2. 获取 source-info

protoc  -I . --descriptor_set_out=out.pb --include_source_info  api.proto

3. 解析 out.pb 文件，这里任何语言都可以，我使用的是Go

package codec

import (
	"google.golang.org/protobuf/encoding/protojson"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/descriptorpb"
	"io/ioutil"
	"testing"
)

func TestProto(t *testing.T) {
	set := descriptorpb.FileDescriptorSet{}
	file, _ := ioutil.ReadFile("/Users/bytedance/data/pb_file/out.pb")
	if err := proto.Unmarshal(file, &set); err != nil {
		t.Fatal(err)
	}
	t.Log(protojson.Format(&set))
}

3. 获取 source info，我这里输出的是JSON

{
    "file": [
        {
            "name": "api.proto",
            "messageType": [
                {
                    "name": "Request",
                    "field": [
                        {
                            "name": "name",
                            "number": 1,
                            "label": "LABEL_OPTIONAL",
                            "type": "TYPE_STRING",
                            "jsonName": "name"
                        },
                        {
                            "name": "nums",
                            "number": 3,
                            "label": "LABEL_REPEATED",
                            "type": "TYPE_INT32",
                            "jsonName": "nums",
                            "options": {
                                "packed": true
                            }
                        },
                        {
                            "name": "kv",
                            "number": 4,
                            "label": "LABEL_REPEATED",
                            "type": "TYPE_MESSAGE",
                            "typeName": ".Request.KvEntry",
                            "jsonName": "kv"
                        },
                        {
                            "name": "num",
                            "number": 5,
                            "label": "LABEL_REQUIRED",
                            "type": "TYPE_ENUM",
                            "typeName": ".Num",
                            "jsonName": "num"
                        },
                        {
                            "name": "req",
                            "number": 6,
                            "label": "LABEL_OPTIONAL",
                            "type": "TYPE_MESSAGE",
                            "typeName": ".Request.InlineRequest",
                            "jsonName": "req"
                        }
                    ],
                    "nestedType": [
                        {
                            "name": "KvEntry",
                            "field": [
                                {
                                    "name": "key",
                                    "number": 1,
                                    "label": "LABEL_OPTIONAL",
                                    "type": "TYPE_STRING",
                                    "jsonName": "key"
                                },
                                {
                                    "name": "value",
                                    "number": 2,
                                    "label": "LABEL_OPTIONAL",
                                    "type": "TYPE_INT64",
                                    "jsonName": "value"
                                }
                            ],
                            "options": {
                                "mapEntry": true
                            }
                        },
                        {
                            "name": "InlineRequest"
                        }
                    ]
                },
                {
                    "name": "Response"
                }
            ],
            "enumType": [
                {
                    "name": "Num",
                    "value": [
                        {
                            "name": "One",
                            "number": 1
                        },
                        {
                            "name": "Tow",
                            "number": 2
                        },
                        {
                            "name": "Four",
                            "number": 4
                        }
                    ]
                }
            ],
            "service": [
                {
                    "name": "Demo",
                    "method": [
                        {
                            "name": "MethodName",
                            "inputType": ".Request",
                            "outputType": ".Response"
                        }
                    ]
                }
            ],
            "options": {
                "javaPackage": "com.byted.xxx.xxx"
            },
            "sourceCodeInfo": {
                "location": [
                    {
                        "span": [ //表示整个文件
                            0,
                            0,
                            48,
                            1
                        ]
                    },
                    {
                        "path": [
                            12
                        ],
                        "span": [ // 第1行，定义了syntax
                            0,
                            0,
                            18
                        ]
                    },
                    {
                        "path": [
                            8
                        ],
                        "span": [ // 第3行，定义了 FileOptions
                            2,
                            0,
                            42
                        ]
                    },
                    {
                        "path": [ //  第3行，定义了 FileOptions.java_package
                            8,
                            1
                        ],
                        "span": [
                            2,
                            0,
                            42
                        ]
                    },
                    {
                        "path": [ // 第5行-17行，定义了第一个枚举
                            5,
                            0
                        ],
                        "span": [
                            4,
                            0,
                            16,
                            1
                        ]
                    },
                    {
                        "path": [ // 第5行，定义了第一个枚举的名称
                            5,
                            0,
                            1
                        ],
                        "span": [
                            4,
                            5,
                            8
                        ]
                    },
                    {
                        "path": [ // 第7行，定义了第一个枚举的第一个枚举值
                            5,
                            0,
                            2,
                            0
                        ],
                        "span": [
                            6,
                            4,
                            12
                        ],
                        "leadingComments": " 注释\n",
                        "trailingComments": " 注释\n"
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            0,
                            1
                        ],
                        "span": [
                            6,
                            4,
                            7
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            0,
                            2
                        ],
                        "span": [
                            6,
                            10,
                            11
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            1
                        ],
                        "span": [
                            8,
                            4,
                            12
                        ],
                        "leadingComments": " 注释\n"
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            1,
                            1
                        ],
                        "span": [
                            8,
                            4,
                            7
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            1,
                            2
                        ],
                        "span": [
                            8,
                            10,
                            11
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            2
                        ],
                        "span": [
                            15,
                            4,
                            13
                        ],
                        "leadingComments": " 333\n",
                        "trailingComments": " 注释\n",
                        "leadingDetachedComments": [
                            " Three = 3;\n 1111\n 222\n"
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            2,
                            1
                        ],
                        "span": [
                            15,
                            4,
                            8
                        ]
                    },
                    {
                        "path": [
                            5,
                            0,
                            2,
                            2,
                            2
                        ],
                        "span": [
                            15,
                            11,
                            12
                        ]
                    },
                    {
                        "path": [ // 第20行-39行 定义了 第一个结构体
                            4,
                            0
                        ],
                        "span": [
                            19,
                            0,
                            38,
                            1
                        ],
                        "leadingComments": " 111\n"
                    },
                    {
                        "path": [
                            4,
                            0,
                            1
                        ],
                        "span": [
                            19,
                            8,
                            15
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            0
                        ],
                        "span": [
                            22,
                            4,
                            29
                        ],
                        "leadingComments": " 1\n 2\n"
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            0,
                            4
                        ],
                        "span": [
                            22,
                            4,
                            12
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            0,
                            5
                        ],
                        "span": [
                            22,
                            13,
                            19
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            0,
                            1
                        ],
                        "span": [
                            22,
                            20,
                            24
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            0,
                            3
                        ],
                        "span": [
                            22,
                            27,
                            28
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1
                        ],
                        "span": [
                            26,
                            4,
                            44
                        ],
                        "leadingComments": "*\n 123\n"
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            4
                        ],
                        "span": [
                            26,
                            4,
                            12
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            5
                        ],
                        "span": [
                            26,
                            13,
                            18
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            1
                        ],
                        "span": [
                            26,
                            19,
                            23
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            3
                        ],
                        "span": [
                            26,
                            26,
                            27
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            8
                        ],
                        "span": [
                            26,
                            28,
                            43
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            1,
                            8,
                            2
                        ],
                        "span": [
                            26,
                            29,
                            42
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            2
                        ],
                        "span": [
                            30,
                            4,
                            30
                        ],
                        "leadingComments": " title\nhello world\n"
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            2,
                            6
                        ],
                        "span": [
                            30,
                            4,
                            22
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            2,
                            1
                        ],
                        "span": [
                            30,
                            23,
                            25
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            2,
                            3
                        ],
                        "span": [
                            30,
                            28,
                            29
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            3
                        ],
                        "span": [
                            32,
                            4,
                            24
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            3,
                            4
                        ],
                        "span": [
                            32,
                            4,
                            12
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            3,
                            6
                        ],
                        "span": [
                            32,
                            13,
                            16
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            3,
                            1
                        ],
                        "span": [
                            32,
                            17,
                            20
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            3,
                            3
                        ],
                        "span": [
                            32,
                            22,
                            23
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            4
                        ],
                        "span": [
                            34,
                            4,
                            36
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            4,
                            4
                        ],
                        "span": [
                            34,
                            4,
                            12
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            4,
                            6
                        ],
                        "span": [
                            34,
                            14,
                            27
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            4,
                            1
                        ],
                        "span": [
                            34,
                            28,
                            31
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            2,
                            4,
                            3
                        ],
                        "span": [
                            34,
                            34,
                            35
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            3,
                            1
                        ],
                        "span": [
                            35,
                            4,
                            37,
                            5
                        ]
                    },
                    {
                        "path": [
                            4,
                            0,
                            3,
                            1,
                            1
                        ],
                        "span": [
                            35,
                            12,
                            25
                        ]
                    },
                    {
                        "path": [
                            4,
                            1
                        ],
                        "span": [
                            40,
                            0,
                            19
                        ]
                    },
                    {
                        "path": [
                            4,
                            1,
                            1
                        ],
                        "span": [
                            40,
                            8,
                            16
                        ]
                    },
                    {
                        "path": [
                            6,
                            0
                        ],
                        "span": [
                            42,
                            0,
                            48,
                            1
                        ],
                        "trailingComments": " 33\n"
                    },
                    {
                        "path": [
                            6,
                            0,
                            1
                        ],
                        "span": [
                            42,
                            8,
                            12
                        ]
                    },
                    {
                        "path": [
                            6,
                            0,
                            2,
                            0
                        ],
                        "span": [
                            46,
                            4,
                            48
                        ],
                        "leadingComments": " 22\n",
                        "trailingComments": " 11\n"
                    },
                    {
                        "path": [
                            6,
                            0,
                            2,
                            0,
                            1
                        ],
                        "span": [
                            46,
                            8,
                            18
                        ]
                    },
                    {
                        "path": [
                            6,
                            0,
                            2,
                            0,
                            2
                        ],
                        "span": [
                            46,
                            20,
                            27
                        ]
                    },
                    {
                        "path": [
                            6,
                            0,
                            2,
                            0,
                            3
                        ],
                        "span": [
                            46,
                            38,
                            46
                        ]
                    }
                ]
            }
        }
    ]
}

如何解析/使用 SourceCodeInfo

那么问题来了，我们需要SourceCodeInfo 做啥了，那当然是做 代码生成、接口文档展示、IDE了！

具体做法大概有两种做法，懒加载/预加载，这两种方法都可取，看实际需求即可！

针对于场景一个人比较推荐预加载，因为懒加载需要每次都需要遍历 SourceCodeInfo，而预加载性能会很高！

懒加载

我们知道对于一个字段/类型来说，它的索引是固定的，我们只需要去SourceCodeInfo中查找即可，为此实现会很简单

例如我们要查找 Num.One 的注释那么根据索引，可以知道是 一个枚举的第一个字段，因此坐标是 [5,0,2,0]，那么结果就是

{
    "path": [
        5,
        0,
        2,
        0
    ],
    "span": [
        6,
        4,
        12
    ],
    "leadingComments": " 注释\n",
    "trailingComments": " 注释\n"
}

预加载

就是先遍历，实际上如果我们只是处理字段的注释，那么只需要处理以下几个对号入座即可！

• [4,x,2,x]： 表示message字段注释
• [5,x,2,x]：表示enum 字段注释
• [6,x,2,x]：表示method 注释
• [4,x]：表示message 注释
• [5,x]：表示enum注释
• [6,x]：表示service注释

参考文章

• Best way to parse SourceCodeInfo Data From Protobuf Files