go微服务接口协议健壮性取决于应对字段增减、版本演进、跨服务调用失败和客户端乱传参数四类压力的能力；采用go-zero的.api文件定义+goctl生成代码是最省力且容错性强的方案。
Go微服务接口协议是否健壮，不取决于你写了多少字段或用了多复杂的结构，而在于它能否扛住字段增减、版本演进、跨服务调用失败、客户端乱传参数这四类真实压力。直接结论：用 go-zero 的 .api 文件定义 + goctl 生成代码，是目前最省力且容错性最强的起点。
用 .api 文件约束请求/响应结构，别手写 struct
很多人在 handler 层手动定义 struct，结果很快出现字段命名不一致、可选字段漏加 omitempty、嵌套结构体没导出等问题。一旦上游改个字段名或加个新字段，下游就 panic 或静默丢数据。
-
.api文件强制使用统一语法（如Id int64 `path:"id"`），goctl自动生成的 struct 带完整 JSON tag、form tag 和校验逻辑 - 字段类型和位置语义（
path/query/body）全由 DSL 显式声明，不会因开发习惯不同而错乱 - 新增字段只需在
.api里加一行，运行goctl api go -api user.api -dir .就自动更新所有相关代码，包括 handler、request、response、validator
让 error 返回走统一 error code 而不是裸字符串
微服务间调用时，如果只返回 "user not found" 这类字符串，下游无法做精确错误分类——是重试、降级，还是直接报错？Go 标准库的 error 接口又太弱，没法携带 code、message、traceID 等元信息。
- 在
.api中定义错误码映射，例如：@server( 404: "user_not_found" )，goctl会生成带Code()方法的 error 类型 - 所有 handler 统一返回
svcctx.Error(code, msg)，避免手拼 JSON 或硬编码 HTTP status - 客户端 SDK 可基于 code 做 switch 分支处理，比如
if err.Code() == 503 { fallback() }，而不是靠字符串 contains 判断
接口版本控制必须体现在路径里，别用 Accept header
用 Accept: application/json; version=2 看似优雅，但实际中几乎没人遵守——前端发请求不带 header、网关默认过滤、gRPC gateway 不支持、日志系统无法按版本统计。版本混用导致线上事故频发。
- 把版本号塞进路径：
get /v1/users/:id、get /v2/users/:id，路由层天然隔离，监控、限流、灰度都可独立配置 - 旧版本接口别急着删，先设为
@deprecated，goctl生成的文档会自动标灰，方便下游感知 - 禁止在同一个路径下用 query 参数区分版本（如
?version=v2），它绕过路由匹配，破坏可观测性和链路追踪完整性
别让 DTO 和 domain model 混在一起
常见错误是把数据库 struct 直接当 API 返回值用，或者把 API request struct 当作业务逻辑入参。结果改个字段就要同步改 DAO、service、API 三层，牵一发而动全身。
- 每个
.api定义的type都是纯 DTO，只服务于这一层协议，不参与业务计算 - service 层接收 DTO 后，立刻转成内部 domain model（比如
UserCreateReq→user.User），中间用明确的ConvertToDomain()函数隔离 - DTO 字段名可以和 domain model 不同（比如 API 用
user_name，domain 用Name），靠转换函数桥接，而非强求命名一致
真正难的不是定义接口，而是守住边界：DTO 不越界进 service，error 不裸奔出 handler，版本不藏在 header 里。这些点看着琐碎，但线上每次 500 错误溯源、跨团队联调扯皮、灰度发布卡点，根源往往就在这几处松动。
