Go微服务接口治理需从协议设计、错误表达、版本演进、可观测性四层面同步约束：HTTP须用结构化ErrorResponse，错误需映射为可识别Code；版本靠Header+Struct双控；gRPC须严守Protobuf兼容规则；可观测性须全链路透传trace_id。
Go微服务的接口治理不是加个中间件就完事，而是要从协议设计、错误表达、版本演进、可观测性四个层面同步约束，否则调用方永远在猜你返回的到底是空结构体、nil、还是一个Code: "UNKNOWN"的假成功。
HTTP接口必须用结构化ErrorResponse，别传原生error
Go 的 error 接口无法 JSON 序列化——json.Marshal(err) 永远返回 null。很多团队把下游错误直接塞进 HTTP 响应体，结果前端收到 {} 或 panic，根本不知道发生了什么。
- 定义统一响应结构，例如：
ErrorResponse{Code: string, Message: string, Details: map[string]interface{}} - 禁止用
fmt.Errorf("call user svc failed: %w", err)包装远程错误——它会让errors.Is(err, context.DeadlineExceeded)失效 - 写转换函数，比如
ToServiceError(err)，把*url.Error、context.DeadlineExceeded映射为可识别的Code（如"TIMEOUT"、"CONNECTION_FAILED"） - 日志记录时必须用
.Err(err)（如zerolog.Error().Err(err).Msg("failed to fetch profile")），否则堆栈和嵌套错误全丢
版本管理不能只靠路径前缀，得靠Header+Struct双控
光靠 /v1/users 和 /v2/users 会导致路由爆炸、灰度难做、客户端升级强耦合。真正可控的版本治理，是让协议层和数据层共同承担语义责任。
- 优先用请求头识别版本：
X-API-Version: 2，fallback 到路径匹配；中间件解析后注入ctx，再路由到v2.UserHandler - struct 字段新增必须带
json:",omitempty"，删除字段先保留并加注释标记// deprecated: will be removed in v3，至少留两个发布周期 - 敏感字段升级（如
Password→PasswordHash）时，旧版 handler 仍返回空字符串，新版才填充；绝不让旧客户端因字段缺失 panic - 不确定结构用
json.RawMessage延迟解析，给灰度字段或第三方扩展留余地
gRPC接口升级必须守死Protobuf兼容规则
Protobuf 不是“改完 proto 重新生成就行”。一次不合规的改动（比如删字段、改类型、重用 enum 编号），就会让老客户端直接解码失败或静默丢数据。
立即学习“go语言免费学习笔记（深入）”；
- 只能追加字段，且序号严格递增；已分配的字段编号绝不可复用
- 枚举值只能追加，已删除的 enum number 永远不能再用（哪怕值相同）
-
int32和int64互转不兼容，string和bytes也不兼容——类型变更等于破坏契约 - .proto 文件必须放在独立 Git 仓库，所有服务通过
go.mod replace或 vendor 引用同一 commit，杜绝本地 copy-paste 导致的隐性不一致
可观测性不是加个 OpenTelemetry 就算落地，关键在 trace_id 全链路透传
没透传 trace ID 的日志，就是无坐标碎片；没打点 span 的指标，就是无上下文数字。治理失效的第一现场，往往不是代码写错，而是上下文断在某次 HTTP 转发或 context.WithTimeout 里。
- 入口 HTTP handler 必须生成
trace.Span，并通过req.Header.Set("Trace-ID", ...)或grpc metadata向下游透传 - 每个出站调用（
http.Do/grpc.Invoke）都必须从当前context.Context提取 span 并注入，不能新建空 context - metrics 要按接口维度暴露：用
prometheus.NewCounterVec区分http_status="400"和http_status="503"，而不是只记总数 - 错误日志强制附加
trace_id和span_id字段，否则 ELK 里查不到完整链路
接口治理最常被忽略的一点：它不是上线前的 checklist，而是每次 PR 都要过的一道门禁——struct 字段删没删、error 是不是被包装了、trace ID 有没有漏传、proto 改动有没有跑兼容性检测。这些动作一旦松动，半年后你面对的就是几十个版本混杂、错误语义模糊、debug 全靠猜的接口沼泽。
