如何正确使用 WEB 接口的 HTTP 状态码和业务状态码?

当设计和开发 Web 接口时,必然会和 HTTP 状态码与业务状态码这两个概念打交道。很多同学可能没有注意过这两个概念或者两者的区别,做得稀里糊涂,接下来详细讲解下二者的定义、区别和使用方法。

HTTP 状态码

HTTP 状态码是由 HTTP 协议定义的,用于表示 Web 服务器对请求的响应状态,每一个状态码都有特定的含义。虽然开发者可以自定义 HTTP 状态码,但并不推荐这样做,因为这可能会引起混淆或者与将来的 HTTP 规范相冲突。HTTP 状态码的值是三位数字,其中第一位数字表示响应类别,目前有以下五个类别:

  • 1xx:表示请求已被接收,需要继续处理。
  • 2xx:表示请求已成功被服务器接收、理解、并接受。
  • 3xx:重定向,需要客户端采取进一步的操作才能完成请求。
  • 4xx:客户端错误,表示请求包含语法错误或者无法完成请求。
  • 5xx:服务器错误,服务器在处理请求的过程中发生了错误。

HTTP 状态码是一种标准的约定,用于表示请求的处理情况。客户端在接收到这些状态码后,可以根据不同的状态码采取相应的处理措施。如果需要表达更具体的状态信息,通常的做法是在 HTTP 响应 body 中返回业务状态码,而不是自定义 HTTP 状态码。业务状态码是由应用或服务自己定义的,可以根据实际的业务需求进行定义,比如表示用户不存在、商品库存不足、支付失败等状态。

业务状态码

业务状态码是在 HTTP 状态码之上,由应用程序自身定义的,以反映特定业务逻辑的状态。这些状态码可以针对不同的操作不同的条件提供更详细更具体的信息,以便客户端能够更好地理解和处理业务流程,根据不同的状态码采取相应的处理措施。

业务状态码通常定义在响应的数据(Response Body)中,与其他响应数据一起返回给客户端。拿登录接口举个例子,登录成功后,使用 HTTP 状态码200,业务状态码1(也可以约定其他的值)来表示,响应数据格式如下:

复制代码
 {"code":1, "data":null,"msg":""}

如果账号或者密码不正确,使用 HTTP 状态码200,业务状态码1001(业务状态码可以根据自己或团队整体情况而定)来表示,响应数据格式如下:

复制代码
 {"code":1001, "data":null,"msg":"账号或密码错误"}

业务状态码是需要根据具体应用程序的需求和上下文定义的,可以根据业务逻辑和操作类型自定义状态码的值。另外,针对同一个应用来说,业务状态码类型要保持一致,统一使用整型或统一使用字符串,建议统一使用整型。

小结

HTTP 状态码用于表示 Web 服务器对请求的处理情况,是 HTTP 协议规定的一种标准表示方式。而业务状态码是为了满足应用程序特定的业务逻辑需求,提供更具体和细粒度的响应状态。在设计接口时,我们应根据情况综合考虑使用HTTP状态码和业务状态码,以提供清晰、一致和易理解的接口响应。

相关推荐
涡能增压发动积15 小时前
同样的代码循环 10次正常 循环 100次就抛异常?自定义 Comparator 的 bug 让我丢尽颜面
后端
Wenweno0o15 小时前
0基础Go语言Eino框架智能体实战-chatModel
开发语言·后端·golang
于慨15 小时前
Lambda 表达式、方法引用(Method Reference)语法
java·前端·servlet
石小石Orz15 小时前
油猴脚本实现生产环境加载本地qiankun子应用
前端·架构
swg32132115 小时前
Spring Boot 3.X Oauth2 认证服务与资源服务
java·spring boot·后端
从前慢丶15 小时前
前端交互规范(Web 端)
前端
tyung15 小时前
一个 main.go 搞定协作白板:你画一笔,全世界都看见
后端·go
gelald15 小时前
SpringBoot - 自动配置原理
java·spring boot·后端
CHU72903515 小时前
便捷约玩,沉浸推理:线上剧本杀APP功能版块设计详解
前端·小程序
GISer_Jing15 小时前
Page-agent MCP结构
前端·人工智能