返回值 200 / 201 与业务语义:接口文档和现场排错时怎么对齐

目录

一级分类 章节 核心问题
语义认知 一、为什么状态码常被误用 技术成功≠业务成功
语义认知 二、200 与 201 分别表示什么 约定要落文档
协作实践 三、如何做统一返回体 code+msg+detail
协作实践 四、排错时先看什么 状态码后看业务码
收束与实践 五、小结 文档先于联调

一、为什么状态码常被误用

很多现场把HTTP 200当作业务成功,但有些接口会在 200 内返回业务失败信息,导致误判。

自动化监控如果只判断状态码,会漏掉大量业务失败。

二、200 与 201 分别表示什么

通常 200 表示请求处理成功,201 常用于创建成功。实际项目应以双方接口文档为准,并明确异常语义。

若同一系统混用 200/201,要在文档里写清各自触发条件,避免集成商猜测。

三、如何做统一返回体

关注点: 仅靠状态码不够。

建议返回:status/codemsgdetailrequest_id,便于追踪与重放。

request_id 对跨团队排障极有价值,应在发布端生成并透传日志。

四、排错时先看什么

先看 HTTP 状态码,再看业务码与错误信息,最后结合请求参数与日志时间戳。

若业务码提示字段非法,回到数据字典核对枚举与类型,而不是反复重发相同报文。

五、小结

状态码是运输层语义,业务码才是业务层语义。两层都对齐,联调才不会各说各话。接口文档与示例报文应纳入版本管理,与代码同步更新。

关于作者

联系方式: cheng.ziwen@gonleon.com