基于Golang+proto3+grpc-gateway，无固定结构Webhook请求对象如何定义？

方案对比与选择 #

针对接收未知结构Webhook Payload的场景，优先选择[]byte而非any.proto，具体原因如下：

关于[]byte #

• 适配性强：grpc-gateway会自动将HTTP请求的完整Body序列化为bytes类型，无需客户端做任何格式适配，完美匹配Webhook发送原始Payload的特性。
• 轻量易处理：直接拿到原始字节流后，可根据业务需求自行做反序列化（比如转成JSON对象、解析二进制等），没有额外依赖和格式限制。

关于any.proto #

• 不适配当前场景：Any类型要求请求必须包裹type_url和value字段（客户端需按照Google的Any格式构造请求），但Webhook客户端只会发送原始JSON/二进制数据，grpc-gateway无法将普通Payload自动解析为Any类型，会直接报错。
• 冗余复杂：即使强行使用，也需要额外的格式转换逻辑，完全发挥不出Any带类型标识的优势。

具体实现示例 #

Proto3定义 #

syntax = "proto3";

package repo;

import "google/api/annotations.proto";

message PostGitPREventRequest {
  bytes payload = 1; // 用bytes接收原始未知Payload
}

message PostGitPREventResponse {
  string status = 1;
  string message = 2;
}

service RepoService {
  rpc PostGitPR(PostGitPREventRequest) returns (PostGitPREventResponse) {
    option (google.api.http) = {
      post: "/git/pr/event"
      body: "*" // 映射整个HTTP请求Body到payload字段
    };
  }
}

Golang后端处理代码 #

package main

import (
	"context"
	"encoding/json"
	"fmt"

	pb "your/path/to/proto/package"
)

type RepoServiceServer struct {
	pb.UnimplementedRepoServiceServer
}

func (s *RepoServiceServer) PostGitPR(ctx context.Context, req *pb.PostGitPREventRequest) (*pb.PostGitPREventResponse, error) {
	// 获取原始Payload字节流
	rawPayload := req.GetPayload()

	// 示例：将JSON格式Payload反序列化为通用Map
	var payloadMap map[string]interface{}
	if err := json.Unmarshal(rawPayload, &payloadMap); err != nil {
		return &pb.PostGitPREventResponse{
			Status:  "error",
			Message: fmt.Sprintf("解析Payload失败: %v", err),
		}, nil
	}

	// 业务逻辑处理：提取所需字段
	if prNum, ok := payloadMap["number"].(float64); ok {
		fmt.Printf("收到PR请求，编号: %d\n", int(prNum))
	}

	return &pb.PostGitPREventResponse{
		Status:  "success",
		Message: "Payload处理完成",
	}, nil
}

内容的提问来源于stack exchange，提问作者Tilak Raj