当前位置：首页 > news >正文

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

news 来源：原创 2025/6/9 9:26:28

背景

在日常的 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.MessageStatesizeCache     protoimpl.SizeCacheunknownFields protoimpl.UnknownFieldsUserId      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.MessageStatesizeCache     protoimpl.SizeCacheunknownFields protoimpl.UnknownFieldsUserID      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.MessageStatesizeCache     protoimpl.SizeCacheunknownFields protoimpl.UnknownFieldsUserID      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"`
}