企业官网建设流程全解析

后端接口怎样约定减少返工

接口返工往往不是字段少了一个，而是双方对同一个结果理解不同：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/problem+json") 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、必填字段、典型错误和旧客户端场景；集成测试还要覆盖认证、分页和请求取消。对外发布前用真实客户端跑一遍，比只看文档页面更能发现字段含义的分歧。

好接口不靠一套华丽的错误码表取胜。它让调用者在成功、失败、等待和重试时都知道该做什么，也让服务端能在不破坏既有使用者的前提下继续演进。