企业官网建设流程全解析

高并发接口怎样约定减少返工

高并发接口返工，往往不是漏了字段，而是双方从未约定超时、重复请求和过载时到底发生什么。客户端超时后可能重试，服务端也可能重试下游；写操作没有幂等语义，一次网络抖动就足以造成两份结果。接口设计应该先把状态变化与失败含义写清，再讨论 JSON 长什么样。

HTTP 状态和业务错误分工明确

HTTP 状态描述协议层的结果，响应体提供稳定的业务错误码、用户可读信息和请求标识。是否统一使用Result<T>是团队选择，但资源不存在、参数无效、无权限、临时过载不能在不同接口里各说各话。外部响应不该包含 SQL、表名、堆栈或 ORM 实体；内部原因保留在脱敏日志中，通过请求标识关联。

Go 服务内部可以用标准错误并保留原因链，在 HTTP 边界集中映射：

type DomainError struct { Kind string HTTPStatus int Code string Message string Err error } func (e *DomainError) Error() string { return e.Message } func (e *DomainError) Unwrap() error { return e.Err }

统一的错误处理中间件据此写状态码和 JSON，未知错误只返回通用说明。Panic 恢复、审计日志和链路标识则应是独立责任。这样调用方知道哪些情况可以修改参数、哪些应停止、哪些可能在稍后重试，而不是去猜一个含混的数字代码。

不要把数据库实体当成公开契约

持久化模型服务于表结构，领域模型服务于规则，接口 DTO 只表达愿意公开的字段。项目不必为每层机械创建大量结构体，但外部响应直接嵌入 ORM 模型很危险：删除标记、内部 ID 或新增列可能无意间泄露。显式转换也让数据库重构停在服务内部，转换函数应覆盖空值、未知枚举和敏感字段。

写操作要说明幂等键由谁生成、作用范围和保存期限，相同键但参数不同如何处理。服务端的幂等判断必须与业务提交处在可靠边界，不能只放在进程内缓存。查询接口则要约定稳定排序、游标与快照语义，否则高并发写入时分页会重复或遗漏。

把超时与过载写进契约

超时不是一个孤立数值。客户端的截止时间应能向下传递，服务端在截止后停止无用工作；已经越过提交点的写操作，应返回可查询的任务标识，而不是假装取消成功。入口主动拒绝与依赖故障也要区分，让调用方决定是否退避。自动重试只适用于已定义幂等的操作，并限制次数、退避与总截止时间，避免多层重试相乘。

OpenAPI 可以成为协作基线：路径、参数、认证、正常响应、错误、幂等与样例由同一权威来源描述；CI 审查契约变更，并运行新旧客户端的兼容测试。规范文件通过 lint 不等于运行时真的遵守它，还要用契约测试验证。接口一旦把重复、超时、过载和版本并存讲明白，客户端就无需为每个接口重新发明一套防御逻辑，服务端也能更清楚地判断内部改动是否越过了公共边界。

文档中最好同时给出最小的正常、参数错误、无权限、资源不存在和繁忙示例。调用方据此写出稳定的错误处理，服务端也能在变更评审时发现某个字段或状态码是否破坏旧版本。这些样例比只列字段类型更接近真实协作。