返回值 200 / 201 与业务语义:接口文档和现场排错时怎么对齐
返回值 200 / 201 与业务语义:接口文档和现场排错时怎么对齐
目录
| 一级分类 | 章节 | 核心问题 |
|---|---|---|
| 语义认知 | 一、为什么状态码常被误用 | 技术成功≠业务成功 |
| 语义认知 | 二、200 与 201 分别表示什么 | 约定要落文档 |
| 协作实践 | 三、如何做统一返回体 | code+msg+detail |
| 协作实践 | 四、排错时先看什么 | 状态码后看业务码 |
| 收束与实践 | 五、小结 | 文档先于联调 |
一、为什么状态码常被误用
很多现场把HTTP 200当作业务成功,但有些接口会在 200 内返回业务失败信息,导致误判。
自动化监控如果只判断状态码,会漏掉大量业务失败。
二、200 与 201 分别表示什么
通常 200 表示请求处理成功,201 常用于创建成功。实际项目应以双方接口文档为准,并明确异常语义。
若同一系统混用 200/201,要在文档里写清各自触发条件,避免集成商猜测。
三、如何做统一返回体
关注点: 仅靠状态码不够。
建议返回:status/code、msg、detail、request_id,便于追踪与重放。
request_id 对跨团队排障极有价值,应在发布端生成并透传日志。
四、排错时先看什么
先看 HTTP 状态码,再看业务码与错误信息,最后结合请求参数与日志时间戳。
若业务码提示字段非法,回到数据字典核对枚举与类型,而不是反复重发相同报文。
五、小结
状态码是运输层语义,业务码才是业务层语义。两层都对齐,联调才不会各说各话。接口文档与示例报文应纳入版本管理,与代码同步更新。
关于作者
联系方式: cheng.ziwen@gonleon.com
本博客所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 Gonleon 工业!