如何设计 API 返回码(错误码)?

如何设计 API 返回码(错误码)?

来源:https://ken.io/note/api-errorcode-or-resultcode-desgin

一、前言

客户端请求API,通常需要通过返回码来判断API返回的结果是否符合预期,以及该如何处理返回的内容等

相信很多同学都吃过返回码定义混乱的亏,有的API用返回码是int类型,有的是string类型,有的用0表示成功,又有的用1表示成功,还有用”true”表示成功,碰上这种事情,只能说:头疼

API返回码的设计还是要认真对待,毕竟好的返回码设计可以降低沟通成本以及程序的维护成本

二、HTTP状态码参考

以HTTP状态码为例,为了更加清晰的表述和区分状态码的含义,HTTP状态做了分段。

分段 分段描述
1XX 信息,服务器收到请求,需要请求者继续执行操作
2XX 成功,操作被成功接收并处理
3XX 重定向,需要进一步的操作以完成请求
4XX 客户端错误,请求包含语法错误或无法完成请求
5XX 服务器错误,服务器在处理请求的过程中发生了错误

对于后端开发来说,我们通常见到的都是:

2XX状态码,比如200->请求成功,

5XX状态码,比如502->服务器异常,通常就是服务没正常运行,或者代码执行出错

通过状态码即可初步判断问题原因,HTTP状态的设计思路值得借鉴。

三、参数约定

虽说是返回码设计,但是只有code是不行的,还要有对应的message,让人可以看懂

字段 类型 说明
code int 返回码
message string 返回码说明

参考HTTP状态码的思路,我们对错误码进行分段

返回码值 说明
0 成功
99999 系统发生未知异常
10000-19999 参数校验错误
20000-29999 A步骤执行失败
30000-39999 B步骤执行失败

通过这样的设计,不论是程序还是人都可以非常方便的区分API的返回结果,关键是统一!

四、个性化Message

通常我们的message都是写给工程师看的,但是在不同的场景下,同样的错误,可能需要给用户看到不一样的错误提示。

比方说 20000-29999表示订单创建失败:

  • 20001,订单创建失败,存在进行中的订单
  • 20002,订单创建失败,上一个订单正在排队创建中

这两种错误情况如果是给用户看,可能就只适合看到:很抱歉,您有一个正在进行中的订单,请到我的订单列表中处理。

但是对于API来说,返回的信息又必须是准确的,但用户看到的就必须转译,这个转译的工作调用方可以做,但是通常API提供者来提供个性化的Message能力会更好

我们可以把转译的消息配置到数据库,并缓存到Redis或者API本机

application_id code message
100001 20001 很抱歉,您有一个正在进行中的订单,请到我的订单列表中处理。
100001 20002 很抱歉,您有一个正在进行中的订单,请到我的订单列表中处理。

然后在请求处理结束即将返回的时候,根据application_id+code,去匹配替换message

request-api-get-my-message

这样我们就可以让手机APP的用户、微信小程序的用户、网页下单的企业用户看到不同的消息

五、返回信息的统一处理

有了统一的code,我们就可以通过Nginx或者APM工具统计API请求Code数量及分布信息。

我们可以根据单位时间内99999的数量来做API的异常告警

我们可以根据Code的返回饼图,帮助我们发现系统、业务流程中的问题

等等,总之,好的返回码设计,可以帮助我们提高沟通效率,降低代码的维护成本。

近期热文推荐:

1.1,000+ 道 Java面试题及答案整理(2022最新版)

2.劲爆!Java 协程要来了。。。

3.Spring Boot 2.x 教程,太全了!

4.20w 程序员红包封面,快快领取。。。

5.《Java开发手册(嵩山版)》最新发布,速速下载!

觉得不错,别忘了随手点赞+转发哦!

hmoban主题是根据ripro二开的主题,极致后台体验,无插件,集成会员系统
自学咖网 » 如何设计 API 返回码(错误码)?