后端接口怎样约定减少返工接口返工往往不是字段少了一个而是双方对同一个结果理解不同HTTP 是成功还是失败空结果和未知结果是否相同客户端能否重试出现问题时该向用户展示什么。数据库和业务逻辑完成后再临时补这些约定前端、SDK、网关和监控往往已经各自形成了一套判断。接口契约应先定义资源和操作再定义成功、失败与异步状态。HTTP 状态码负责表达协议层结果例如请求格式不正确、没有权限、资源不存在或服务暂不可用业务领域中的更细原因放在稳定的响应字段中。没有必要用 200 承载所有失败也不必把每个领域规则映射成一个奇怪的 HTTP 状态码。错误响应需要稳定但不需要泄露内部细节Problem Details 格式提供了一个清楚的基础type标识错误类别title是简短说明status与 HTTP 状态一致detail可说明本次请求为何失败instance用于关联请求。团队可以添加受控的扩展字段例如字段校验错误或支持人员使用的请求 ID但字段语义一旦公开就要按契约维护。客户端需要的是可行动的信息不是数据库异常或调用栈。参数不合法时可以指出哪个公开字段不符合规则权限不足时通常不该披露资源是否存在内部错误则返回通用说明并把完整上下文仅写入受访问控制的日志。请求 ID 应贯穿网关和下游便于支持人员查找而不是用 URL 路径冒充追踪标识。type Problem struct { Type string json:type Title string json:title Status int json:status Detail string json:detail,omitempty Instance string json:instance,omitempty } func writeProblem(w http.ResponseWriter, p Problem) { w.Header().Set(Content-Type, application/problemjson) w.WriteHeader(p.Status) _ json.NewEncoder(w).Encode(p) }调用这个函数前服务应确保尚未写入响应头。中间件还需要区分已知错误、取消请求和 panic并避免同一次请求写两份响应。日志记录应该走项目统一的 logger带上请求 ID、错误类别和必要上下文而不是把错误直接打印到标准输出。空值、缺失与空集合必须在 schema 里说清楚null并不天然错误空数组也不总是正确。关键在于它们代表什么字段缺失是否表示客户端未提供null是否表示已知但没有值空数组是否表示查询成功但无元素。不同含义就应该出现在 OpenAPI 或类型定义中并有示例和测试。对列表接口稳定返回数组通常能降低客户端分支对可选对象明确可空或可缺失能避免猜测。别因为追求“整洁”而把数据库中的未知值硬转成空字符串或空对象这会丢掉业务信息。分页的items、next_cursor、总数是否可靠也应写清楚特别是在数据会变化的场景。单一真相源要有变更流程OpenAPI、代码注解或 schema 库都可以成为契约来源重点是不要让三份手写定义长期漂移。生成客户端类型很有帮助但不能替代服务端的输入校验和兼容性测试。每次修改字段类型、枚举值、默认值或错误语义都应做破坏性变更检查并在发布说明中告诉 SDK 使用者怎样迁移。新增可选字段通常较容易兼容把字符串变成对象、改变字段含义、收紧原本接受的输入则风险更高。遇到这类变更可以增加新字段或新版本端点保留旧行为到有明确下线计划为止。版本号只是出口真正减少返工的是对兼容范围的共同理解。让监控和测试验证契约网关的 4xx、5xx、超时和重试指标应与接口的真实语义一致否则告警会失真。契约测试可以验证状态码、content type、必填字段、典型错误和旧客户端场景集成测试还要覆盖认证、分页和请求取消。对外发布前用真实客户端跑一遍比只看文档页面更能发现字段含义的分歧。好接口不靠一套华丽的错误码表取胜。它让调用者在成功、失败、等待和重试时都知道该做什么也让服务端能在不破坏既有使用者的前提下继续演进。