如何为gRPC服务定义可复用的通用Proto响应结构？

原方案存在的问题 #

• DataResponse是固定结构，没法适配不同业务服务的自定义返回数据，复用性差
• Status枚举和oneof的response字段冗余，比如status=OK必然对应data，status=ERROR必然对应error，没必要重复定义
• Response里的message字段和ErrorResponse的message字段重复，容易混淆
• 缺乏对业务数据的泛化支持，每个业务服务没法直接复用这个通用结构

优化后的通用.proto文件 #

syntax = "proto3";

package common;

import "google/protobuf/any.proto";

// 字段级错误，用于表单验证等场景
message FieldError {
  string field = 1;        // 出错字段名
  string message = 2;      // 字段错误描述
}

// 通用错误详情，返回错误码、错误信息和字段级错误
message ErrorDetails {
  int32 code = 1;          // 业务错误码
  string message = 2;      // 具体错误描述
  repeated FieldError field_errors = 3; // 字段级错误列表
}

// 通用响应模板，支持任意业务数据和错误详情
message GenericResponse {
  bool success = 1;        // 标识请求是否成功，替代原Status枚举
  string message = 2;      // 通用提示信息（成功时友好提示，错误时简短描述）
  
  oneof payload {
    google.protobuf.Any data = 3;      // 成功时的业务数据，支持任意结构
    ErrorDetails error_details = 4;    // 失败时的错误详情
  }
}

设计思路说明 #

• 泛化业务数据：用google.protobuf.Any替代固定的DataResponse，任何业务服务的返回数据都能打包进去，只要业务proto导入google/protobuf/any.proto就能复用，灵活性拉满。
• 简化状态判断：用bool success替代枚举，直观易懂，不用额外判断status和oneof的匹配关系——success=true就取data，false就取error_details。
• 清晰的错误分层：把字段级错误单独做成FieldError结构体，比原有的repeated string能传递更多信息（比如明确哪个字段出错），ErrorDetails专注于整体错误的描述和编码。
• 避免字段重复：GenericResponse的message用于通用提示，ErrorDetails的message用于具体错误说明，职责明确，不会混淆。

业务服务复用示例 #

比如用户服务的proto可以这么写：

syntax = "proto3";

package user;

import "common/common.proto";
import "google/protobuf/any.proto";

// 用户信息结构
message UserInfo {
  string user_id = 1;
  string username = 2;
  string email = 3;
}

// 获取用户信息请求
message GetUserRequest {
  string user_id = 1;
}

// 获取用户信息响应，直接复用通用响应
message GetUserResponse {
  common.GenericResponse base = 1;
}

// 用户服务定义
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

在业务代码里（以Go为例）：

• 成功场景：构造UserInfo实例，用anypb.New(userInfo)打包到GenericResponse的data字段，设置success=true、message="获取用户信息成功"。
• 失败场景：构造ErrorDetails实例，设置对应的错误码、错误信息和字段错误，设置success=false、message="获取用户信息失败"。

内容的提问来源于stack exchange，提问作者saeed jalali