解读 Moby 仓库中 gax-go 的 HTTP-JSON 错误 Schema：apierror/internal/proto 的协议定义与 protoc 再生成实践

本仓库（moby）在 vendor/github.com/googleapis/gax-go/v2 目录下随依赖整体携带了 gax-go v2 的源码，其中 vendor/github.com/googleapis/gax-go/v2/apierror/internal/proto/README.md 即本文讲解的关联文档。它描述的是 Google API 体系"HTTP-JSON 错误格式 v2"的 protobuf 定义（error.proto），以及如何重新生成对应的 Go 代码。读完本文，你将理解该错误 Schema 与 google.rpc.Status 的对应关系、各字段的确切含义，掌握在本地用 protoc + --go_opt=module=... 一键再生成 .pb.go 的完整流程，并能在阅读 gax-go、google.golang.org/api 等依赖的报错解析逻辑时快速定位协议层代码。

文档定位：一个"仅供内部解析"的协议子包

该 README 开宗明义给出两条核心约束：

• error.proto 描述的是 Google API 传输 HTTP-JSON 错误负载所使用的 Schema（即 Google API Design Guide《错误模型 / HTTP 映射》章节描述的格式 v2）；
• 本包仅供 gax-go 内部解析逻辑使用，不允许在其他上下文中被引入使用。

在 moby 仓库中它属于被 vendor 的第三方间接依赖：仓库根目录 go.mod 中声明 github.com/googleapis/gax-go/v2 v2.23.0（标记为 // indirect），源码被整体拷贝到 vendor/ 下，因此该子目录的代码不应被手工改动，涉及协议或生成逻辑的修改应回归 gax-go 上游完成。

Schema 核心：error.proto 与 google.rpc.Status 的关系

关联文档把 error.proto 定义为"HTTP-JSON Schema"。真正的协议定义在同目录的 error.proto 中，全文不长却包含设计要点：

syntax = "proto3";

package error;

import "google/protobuf/any.proto";
import "google/rpc/code.proto";

option go_package = "github.com/googleapis/gax-go/v2/apierror/internal/proto;jsonerror";

// The error format v2 for Google JSON REST APIs.
// Copied from https://cloud.google.com/apis/design/errors#http_mapping.
//
// NOTE: This schema is not used for other wire protocols.
message Error {
  // This message has the same semantics as `google.rpc.Status`. It uses HTTP
  // status code instead of gRPC status code. It has an extra field `status`
  // for backward compatibility with Google API Client Libraries.
  message Status {
    // The HTTP status code that corresponds to `google.rpc.Status.code`.
    int32 code = 1;
    // This corresponds to `google.rpc.Status.message`.
    string message = 2;
    // This is the enum version for `google.rpc.Status.code`.
    google.rpc.Code status = 4;
    // This corresponds to `google.rpc.Status.details`.
    repeated google.protobuf.Any details = 5;
  }
  // The actual error payload. The nested message structure is for backward
  // compatibility with Google API client libraries. It also makes the error
  // more readable to developers.
  Status error = 1;
}

将其字段整理成表，可以直观看到与 google.rpc.Status 的逐字段对应：

消息	字段	标签/类型	含义（依据 .proto 注释）
Error	error	1, Status	真正的错误负载；用嵌套消息保持与老版 Google API Client Libraries 的向后兼容，也便于开发者阅读
Error.Status	code	1, int32	HTTP 状态码，对应 google.rpc.Status.code
Error.Status	message	2, string	对应 google.rpc.Status.message
Error.Status	status	4, google.rpc.Code	google.rpc.Status.code 的枚举版本，是为了老客户端库兼容而额外增加的字段
Error.Status	details	5, repeated google.protobuf.Any	对应 google.rpc.Status.details，可携带任意结构化错误详情

Schema 的两个设计特征值得注意：

1. 语义对齐而非字节对齐：Error.Status 与 google.rpc.Status 语义相同，但以 HTTP 状态码取代 gRPC 状态码，且多出 status 字段承载枚举形式的 gRPC 错误码，从而让新旧两代客户端都能消费同一个 JSON 负载；
2. 显式的传输协议边界：注释明确 "This schema is not used for other wire protocols"，即它只服务于 JSON REST 通道，gRPC 通道走标准的 google.rpc.Status。

生成代码验证：error.pb.go

同一目录下的 error.pb.go 是由 protoc-gen-go 自动生成的实现，文件头标明：

• protoc-gen-go v1.36.11、protoc v6.30.2；
• 生成的 Go 包名为 jsonerror（来自 go_package 选项中的 ;jsonerror 部分）；
• 消息结构体 Error（含嵌套 Error_Status）字段类型与上面 .proto 完全一致，例如 Status code.Code（即 google.golang.org/genproto/googleapis/rpc/code 包）与 Details []*anypb.Any。

自定义错误详情示例：custom_error.proto

与 error.proto 配套，目录内还有 custom_error.proto。它并不代表任何标准错误，而是一个"可以被放入 rpc status 的 details 字段"的自定义错误消息示例，用于演示如何把业务自定义错误结构打包进 google.protobuf.Any：

syntax = "proto3";

package error;

option go_package = "github.com/googleapis/gax-go/v2/apierror/internal/proto;jsonerror";

// CustomError is an example of a custom error message  which may be included
// in an rpc status. It is not meant to reflect a standard error.
message CustomError {
  enum CustomErrorCode {
    CUSTOM_ERROR_CODE_UNSPECIFIED = 0;
    TOO_MANY_FOO = 1;
    NOT_ENOUGH_FOO = 2;
    UNIVERSE_WAS_DESTROYED = 3;
  }
  CustomErrorCode code = 1;
  string entity = 2;
  string error_message = 3;
}

从其字段设计可以看到 Google 错误详情（error_details）的一般模式：一个业务错误码枚举（从 UNSPECIFIED = 0 开始，保证零值可用）+ 出错实体标识 + 人类可读的错误说明。它和 error.pb.go 一样也生成了 custom_error.pb.go。从源码结构可以推断，这类自定义消息正是设计上期望放进 Error.Status.details 的 Any 负载，供上层解析时按类型还原。

这份 Schema 在哪里被消费：apierror 包的解析链路

README 声称"仅供内部解析逻辑使用"，其消费方就是上一级目录 apierror.go。该文件以 jsonerror 别名引入本 proto 包，用 protojson 把 HTTP 响应中的 JSON 错误解码为 Error，再把负载还原成 gRPC 语义。源码中可验证的两个关键事实：

（1）HTTP 状态码到 gRPC 状态码的权威映射表 canonicalMap（apierror.go）：

HTTP 状态码	gRPC codes.Code
200 OK	OK
400 Bad Request	InvalidArgument
401 Unauthorized	Unauthenticated
403 Forbidden	PermissionDenied
404 Not Found	NotFound
409 Conflict	Aborted
416 Requested Range Not Satisfiable	OutOfRange
429 Too Many Requests	ResourceExhausted
501 Not Implemented	Unimplemented
503 Service Unavailable	Unavailable
504 Gateway Timeout	DeadlineExceeded

（2）兜底换算函数 toCode：映射表未命中的情况下，2xx 归为 OK，4xx 归为 FailedPrecondition，5xx 归为 Internal，其余归为 Unknown。

解码后得到的 ErrDetails 结构体（apierror.go）持有 ErrorInfo、BadRequest、PreconditionFailure、QuotaFailure、RetryInfo、ResourceInfo、RequestInfo、DebugInfo、Help、LocalizedMessage 等标准错误详情，并把无法识别的负载放进 Unknown，通过 ExtractProtoMessage 机制按 protobuf 类型从 Unknown 中提取自定义消息——这正好闭环呼应了 custom_error.proto 的存在意义。

Regeneration：重新生成 protobuf Go 代码

README 的核心实操章节是"Regeneration"，给出了完整的再生成前置条件与命令。这些命令在包含 error.proto 的目录（即本仓库的 vendor/github.com/googleapis/gax-go/v2/apierror/internal/proto 目录）中执行。

前置工具清单

工具	用途
googleapis 仓库的本地副本	提供 google/rpc/code.proto、google/protobuf/any.proto 等依赖描述文件；其绝对路径须导出为环境变量 GOOGLEAPIS
protoc（protobuf 编译器）	读取 .proto 文件并驱动 protoc-gen-go 插件产出 Go 代码
Go protobuf 插件 protoc-gen-go	生成类型安全的 Go 结构体与反射实现
goimports 工具	对生成文件做 import 整理与格式化

注：README 以外部链接的形式给出这些工具的获取地址（如 googleapis 仓库、protobuf 编译器安装页、Go 插件文档、goimports 的 pkg.go.dev 页面），需要下载安装时按工具官方渠道获取即可。需要强调：GOOGLEAPIS 必须指向本地已克隆的 googleapis 代码副本，因为 .proto 中的 import "google/rpc/code.proto" 依赖它在 -I 搜索路径中被解析。

生成命令（在 proto 目录内执行）

protoc -I $GOOGLEAPIS -I. --go_out=. --go_opt=module=github.com/googleapis/gax-go/v2/apierror/internal/proto error.proto
goimports -w .

两条命令的分工：

1. protoc：通过 -I $GOOGLEAPIS -I. 指定两条 import 搜索路径（先是 googleapis 副本，再是当前目录），对 error.proto 生成 Go 代码写入当前目录（--go_out=.）；
2. goimports -w .：对生成结果执行导入排序、清理与就地写回。

module 插件选项的作用（README 特别强调）

--go_opt=module=github.com/googleapis/gax-go/v2/apierror/internal/proto 这个选项决定了输出文件的落盘位置。因为 .proto 的 go_package 选项中写死了完整的 Go import 路径 github.com/googleapis/gax-go/v2/apierror/internal/proto，若不加 module=...，protoc 会按照该路径在本目录下再创建一层嵌套目录结构（github.com/googleapis/gax-go/v2/apierror/internal/proto/）存放产物；而加上 module= 后，生成器会把这一前缀当作模块根并"裁掉"，让 error.pb.go 恰好落在当前 proto 目录，import 路径保持为模块完整路径不变。

针对 custom_error.proto 的对照验证

custom_error.proto 的 go_package 与 error.proto 相同，因此对两个文件均可套用同一生成方式（在命令末尾追加 custom_error.proto 即可一次处理多个文件）。仓库中两份已检入的 .pb.go 头部信息（protoc-gen-go v1.36.11 / protoc v6.30.2）可作为核对"本地再生成结果是否与上游一致"的版本基线。

在 Moby 仓库中的适用注意点

• 位置特殊性：本目录位于 vendor/ 之下，是 gax-go 上游代码的镜像；文章介绍的所有字段定义与生成命令，面向的是该依赖的维护与理解场景，日常编译 Moby 不需要手动执行 protoc，vendor 中已有的 .pb.go 已直接参与构建。
• 内部使用约束：README 明确该包"不应在任何其他上下文中使用"，因此业务代码不应直接 import 该 jsonerror 包，而应经由 apierror 暴露的 API 消费错误信息。
• 事实边界：本仓库仅间接依赖 gax-go v2.23.0（见 go.mod），本文对协议字段、映射表与生成流程的阐述均以仓库内实际存在的 error.proto、custom_error.proto、对应 .pb.go 及 apierror.go 源码为依据；error.proto 注释表明其格式源自 Google API Design Guide 的错误 HTTP 映射章节，需要完整背景时可继续查阅该设计规范。