Go jsonpb反序列化Protobuf兼容names字段新旧类型实现方法

问题本质 #

原有Protobuf定义中Event.names为string类型，底层数据源升级后新写入数据的names为字符串数组，新旧数据混合返回时，jsonpb按原有string类型解析数组会直接抛出如下错误：

json: cannot unmarshal array into Go value of type string

不推荐使用google.protobuf.Any实现兼容：Any类型设计初衷是承载任意Protobuf结构化消息，用来兼容JSON基础类型/数组差异会引入额外的Pack/Unpack逻辑，冗余度高且维护成本大，完全没有必要。

方案一：前置JSON预处理（零Proto改动，落地成本最低） #

核心逻辑是在正式走jsonpb反序列化前，先对原始JSON做字段类型统一：如果names是数组就按约定规则拼接成字符串，如果是字符串则直接保留，处理完成后再走原有反序列化流程，完全不需要修改现有Proto定义。

实现步骤 #

• 先将原始json.RawMessage反序列化为通用map[string]interface{}结构，无需额外定义DTO
• 对names字段做类型分支处理：
  • 匹配到string类型：直接保留原值，对应存量旧数据
  • 匹配到[]interface{}类型（JSON数组在Go泛型解析下的默认类型）：遍历提取所有字符串元素，按业务约定的分隔符拼接为单个字符串，对应新写入数据
• 将处理完成的map重新序列化为JSON字节流，传入原有jsonpb反序列化逻辑即可

代码实现 #

import (
	"bytes"
	"encoding/json"
	"github.com/golang/protobuf/jsonpb"
	"strings"
)

func UnmarshalEvent(raw json.RawMessage) (*pb.Event, error) {
	// 泛型解析原始JSON做字段兼容
	var temp map[string]interface{}
	if err := json.Unmarshal(raw, &temp); err != nil {
		return nil, err
	}

	// names字段类型统一处理
	if namesVal, exist := temp["names"]; exist {
		switch v := namesVal.(type) {
		case string:
			// 旧数据为字符串，直接保留
			temp["names"] = v
		case []interface{}:
			// 新数据为字符串数组，拼接为单字符串
			strItems := make([]string, 0, len(v))
			for _, item := range v {
				if s, isStr := item.(string); isStr {
					strItems = append(strItems, s)
				}
			}
			// 分隔符可根据业务规则调整，注意不要和字段内容本身冲突
			temp["names"] = strings.Join(strItems, ",")
		}
	}

	// 处理后的JSON走原有反序列化逻辑
	processedRaw, err := json.Marshal(temp)
	if err != nil {
		return nil, err
	}

	evnt := new(pb.Event)
	unmarshaler := jsonpb.Unmarshaler{AllowUnknownFields: true}
	if err := unmarshaler.Unmarshal(bytes.NewReader(processedRaw), evnt); err != nil {
		return nil, err
	}
	return evnt, nil
}

方案优势 #

• 无Proto改动，不会影响其他依赖该Protobuf定义的服务
• 兼容逻辑完全可控，后续新增其他字段类型兼容可直接在预处理层扩展
• 完全保留原有jsonpb的配置项（如AllowUnknownFields），不改变原有反序列化行为

方案二：自定义JSONUnmarshaler接口（适合多场景复用） #

如果Event结构在多处需要反序列化，可以封装自定义类型实现jsonpb.JSONUnmarshaler接口，将兼容逻辑封装到反序列化方法内部，使用时无需重复编写预处理代码。

代码实现 #

// CustomEvent 封装原有pb.Event，实现自定义反序列化逻辑
type CustomEvent struct {
	*pb.Event
}

func (e *CustomEvent) UnmarshalJSONPB(unmarshaler *jsonpb.Unmarshaler, data []byte) error {
	var temp map[string]interface{}
	if err := json.Unmarshal(data, &temp); err != nil {
		return err
	}

	// 复用names字段兼容逻辑
	if namesVal, exist := temp["names"]; exist {
		switch v := namesVal.(type) {
		case string:
			temp["names"] = v
		case []interface{}:
			strItems := make([]string, 0, len(v))
			for _, item := range v {
				if s, isStr := item.(string); isStr {
					strItems = append(strItems, s)
				}
			}
			temp["names"] = strings.Join(strItems, ",")
		}
	}

	processed, err := json.Marshal(temp)
	if err != nil {
		return err
	}

	// 调用默认反序列化逻辑完成赋值
	e.Event = new(pb.Event)
	return unmarshaler.Unmarshal(bytes.NewReader(processed), e.Event)
}

使用方式 #

直接初始化自定义类型传入反序列化方法即可，无需额外预处理：

evnt := new(CustomEvent)
unmarshaler := jsonpb.Unmarshaler{AllowUnknownFields: true}
err := unmarshaler.Unmarshal(bytes.NewReader(rawMsg), evnt)

注意事项 #

• 数组拼接使用的分隔符需要和调用客户端提前约定，避免分隔符和字段实际内容冲突导致解析异常
• 如果后续计划彻底将names字段切换为数组类型，建议在Protobuf中新增repeated string类型的新字段做双写过渡，等存量数据全部迁移完成后再废弃旧的string类型字段，不要直接修改原有字段的类型定义。

内容的提问来源于stack exchange，提问作者Jay D