OpenAPI oneOf转Protobuf oneOf后JSON反序列化失败及Go适配咨询

针对你遇到的OpenAPI oneOf（扁平JSON结构）与Protobuf oneOf（嵌套结构）不兼容导致反序列化失败的问题，有以下几种实用的适配方案：

1. 自定义JSON反序列化逻辑 #

直接在Protobuf生成的Pet结构体上实现json.Unmarshaler接口，手动识别Cat/Dog的特征字段，将扁平结构转换为Protobuf期望的嵌套格式。

示例代码：

import (
	"encoding/json"
	"fmt"
)

// 假设这是protoc生成的Pet及关联结构体
type Pet struct {
	// 省略Protobuf内部字段...
	Pet is_Pet `protobuf_oneof:"pet"`
}

type Pet_Cat struct {
	Cat *Cat `protobuf:"bytes,1,opt,name=cat,proto3,oneof"`
}

type Pet_Dog struct {
	Dog *Dog `protobuf:"bytes,2,opt,name=dog,proto3,oneof"`
}

type Cat struct {
	Hunts bool `protobuf:"varint,1,opt,name=hunts,proto3"`
	Age   int32 `protobuf:"varint,2,opt,name=age,proto3"`
}

type Dog struct {
	Bark  bool   `protobuf:"varint,1,opt,name=bark,proto3"`
	Breed string `protobuf:"bytes,2,opt,name=breed,proto3"`
}

// 自定义UnmarshalJSON实现扁平结构到Protobuf oneOf的转换
func (p *Pet) UnmarshalJSON(data []byte) error {
	var rawReq map[string]interface{}
	if err := json.Unmarshal(data, &rawReq); err != nil {
		return err
	}

	petData, ok := rawReq["pet"].(map[string]interface{})
	if !ok {
		return fmt.Errorf("invalid pet field: expected object")
	}

	// 通过特征字段判断宠物类型
	if _, hasHunts := petData["hunts"]; hasHunts {
		cat := &Cat{}
		catBytes, _ := json.Marshal(petData)
		if err := json.Unmarshal(catBytes, cat); err != nil {
			return err
		}
		p.Pet = &Pet_Cat{Cat: cat}
		return nil
	}

	if _, hasBark := petData["bark"]; hasBark {
		dog := &Dog{}
		dogBytes, _ := json.Marshal(petData)
		if err := json.Unmarshal(dogBytes, dog); err != nil {
			return err
		}
		p.Pet = &Pet_Dog{Dog: dog}
		return nil
	}

	return fmt.Errorf("unknown pet type")
}

优点：无需修改API定义或Protobuf结构，直接适配现有业务逻辑；缺点：需要维护自定义反序列化代码，新增宠物类型时需同步更新判断逻辑。

2. 中间层结构转换 #

在API入口（如网关、HTTP服务中间件）添加一层转换逻辑，将客户端提交的扁平JSON结构转换为Protobuf期望的嵌套格式，再传递给后端微服务。

示例Gin中间件代码：

import (
	"bytes"
	"encoding/json"
	"io"
	"net/http"

	"github.com/gin-gonic/gin"
)

func PetJSONTransformMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		var rawReq map[string]interface{}
		if err := c.ShouldBindJSON(&rawReq); err != nil {
			c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
			return
		}

		if petData, ok := rawReq["pet"].(map[string]interface{}); ok {
			var nestedPet map[string]interface{}
			if _, hasHunts := petData["hunts"]; hasHunts {
				nestedPet = map[string]interface{}{"cat": petData}
			} else if _, hasBark := petData["bark"]; hasBark {
				nestedPet = map[string]interface{}{"dog": petData}
			} else {
				c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "unknown pet type"})
				return
			}
			rawReq["pet"] = nestedPet
		}

		// 重新序列化修改后的JSON，替换请求体
		modifiedBody, err := json.Marshal(rawReq)
		if err != nil {
			c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "failed to transform request"})
			return
		}
		c.Request.Body = io.NopCloser(bytes.NewBuffer(modifiedBody))
		c.Request.ContentLength = int64(len(modifiedBody))
		c.Next()
	}
}

优点：业务代码无需修改，转换逻辑集中管理；缺点：增加了请求处理的额外开销。

3. 定制OpenAPI代码生成规则 #

如果使用oapi-codegen等工具生成Go代码，可以通过自定义模板或扩展字段，让生成的结构体自动适配扁平JSON与Protobuf oneOf的映射。

比如在OpenAPI定义中添加自定义扩展：

components:
  schemas:
    Pet:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
      x-protobuf-oneof-flatten: true  # 自定义扩展，告知代码生成器需要扁平结构适配

然后修改oapi-codegen的模板，让生成的Pet结构体自带自定义反序列化逻辑（类似方案1的实现）。

优点：代码自动生成，无需手动维护适配逻辑；缺点：需要熟悉代码生成工具的模板或插件开发。

内容的提问来源于stack exchange，提问作者Ganesh Agrawal