自定义protoc-gen-go生成Go结构体，统一字段命名与JSON标签风格

news2025/6/9 13:06:27

背景

在日常的 Go 微服务开发中，Protocol Buffers（protobuf） 是广泛使用的数据交换格式。其配套工具 protoc-gen-go 会根据 .proto 文件生成 Go 结构体代码，但默认生成的字段名、JSON tag 命名风格往往不能满足所有团队或项目的代码规范需求。

比如，团队可能有以下规范或诉求：

Go 结构体字段名需要使用特定的 PascalCase 命名规则；
JSON tag 必须统一为 snake_case，以与前端规范对齐；
字段名称如 id、user_id等在 Go 代码中必须转换为ID、UserID，以保持一致性和清晰性。

遗憾的是，protoc-gen-go 并没有提供原生的机制来满足这些细致的定制需求。因此，我们选择自定义 protoc-gen-go 插件的生成逻辑，以实现结构体字段命名的精细控制。

实现步骤

1. 获取protobuf-go源码

首先克隆指定版本的protobuf-go仓库：

git clone github.com/protocolbuffers/protobuf-go@v1.36.6

2. 定义全局参数

在cmd/protoc-gen-go/internal_gengo/main.go文件中定义全局变量和常量：

var (
    IsCustomField bool   // 标识是否使用自定义字段命名
    TagJSONStyle  string // JSON标签命名风格
)

const (
    SnakeCaseStyle = "snake_case"
    CamelCaseStyle = "camel_case"
)

3. 声明命令行参数

在cmd/protoc-gen-go/main.go中添加参数解析逻辑：

// 定义option参数
isCustomField = flags.Bool("is_custom_field", false, 
    "struct field naming style setting, default is false, indicates no modification, "+
    "if true indicates custom hump style, for example, message field name suffix "+
    "is _id or Id, struct field name suffix of generated go code is ID")

tagJSONStyle = flags.String("tag_json_style", "", 
    "struct field tag json naming style setting, default is empty, indicates no modification, "+
    "if set to 'snake_case', indicates snake case style, if set to 'camelCase', indicates camel case style. "+
    "NOTE: this option overrides protobuf's json_name option")

// 判断参数是否合法
if *isCustomField {
    gengo.IsCustomField = true
}
if *tagJSONStyle != "" {
    if *tagJSONStyle != gengo.SnakeCaseStyle && *tagJSONStyle != gengo.CamelCaseStyle {
        return fmt.Errorf("protoc-gen-go: invalid tag_json_style value: %q, "+
            "must be 'camel_case' or'snake_case'", *tagJSONStyle)
    }
    gengo.TagJSONStyle = *tagJSONStyle
}

4. 添加命名转换工具

从nameFormat.go复制代码到cmd/protoc-gen-go/internal_gengo目录，并将函数名xstrings.ToCamelCase修改为xstrings.ToPascalCase。

5. 修改字段生成逻辑

在generateOneFile函数中添加自定义字段命名逻辑：

func generateOneFile(gen *protogen.Plugin, file *protogen.File, f *fileInfo, variant string) *protogen.GeneratedFile {
    // ......
    
    for _, message := range f.allMessages {
        // 添加的自定义字段名风格设置
        if IsCustomField {
            for _, field := range message.Fields {
                field.GoName = toCamel(field.GoName)
            }
        }
        
        genMessage(g, f, message)
    }
    
    // ......
}

6. 修改JSON标签生成逻辑

更新fieldJSONTagValue函数以支持自定义JSON标签风格：

func fieldJSONTagValue(field *protogen.Field) string {
    switch TagJSONStyle {
    case SnakeCaseStyle:
        return customToSnake(string(field.Desc.Name())) + ",omitempty"
    case CamelCaseStyle:
        return customToCamel(string(field.Desc.Name())) + ",omitempty"
    }
    return string(field.Desc.Name()) + ",omitempty" // default
}

使用示例

测试proto文件

使用以下user.proto文件进行测试：

syntax = "proto3";

package api.user.v1;

option go_package = "user/api/user/v1;v1";

service user {
  // Login 登录
  rpc Login(LoginRequest) returns (LoginReply) {}
}

message LoginRequest {
  string email = 1;
  string password = 2;
}

message LoginReply {
  uint64 user_id =1;
  uint64 communityId=2;
  repeated uint64 roleIDs =3;
  string token =4;
}

生成命令对比

默认生成方式（与原始protobuf-go行为一致）：

protoc --go_out=. --go_opt=paths=source_relative user.proto

自定义字段命名：

protoc --go_out=. --go_opt=paths=source_relative --go_opt=is_custom_field=true user.proto

自定义字段命名+蛇形JSON标签：

protoc --go_out=. --go_opt=paths=source_relative --go_opt=is_custom_field=true --go_opt=tag_json_style=snake_case user.proto

效果对比

默认生成的代码

type LoginReply struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    UserId      uint64 `protobuf:"varint,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
    CommunityId uint64 `protobuf:"varint,2,opt,name=communityId,json=communityId,proto3" json:"communityId,omitempty"`
    RoleIDs     []uint64 `protobuf:"varint,3,rep,packed,name=roleIDs,json=roleIDs,proto3" json:"roleIDs,omitempty"`
    Token       string `protobuf:"bytes,4,opt,name=token,proto3" json:"token,omitempty"`
}

自定义字段命名后的代码

type LoginReply struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    UserID      uint64 `protobuf:"varint,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
    CommunityID uint64 `protobuf:"varint,2,opt,name=communityId,json=communityId,proto3" json:"communityId,omitempty"`
    RoleIDs     []uint64 `protobuf:"varint,3,rep,packed,name=roleIDs,json=roleIDs,proto3" json:"roleIDs,omitempty"`
    Token       string `protobuf:"bytes,4,opt,name=token,proto3" json:"token,omitempty"`
}

自定义字段命名+蛇形JSON标签后的代码

type LoginReply struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    UserID      uint64 `protobuf:"varint,1,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
    CommunityID uint64 `protobuf:"varint,2,opt,name=communityId,json=communityId,proto3" json:"community_id,omitempty"`
    RoleIDs     []uint64 `protobuf:"varint,3,rep,packed,name=roleIDs,json=roleIDs,proto3" json:"role_ids,omitempty"`
    Token       string `protobuf:"bytes,4,opt,name=token,proto3" json:"token,omitempty"`
}