0
  • 聊天消息
  • 系统消息
  • 评论与回复
登录后你可以
  • 下载海量资料
  • 学习在线课程
  • 观看威廉希尔官方网站 视频
  • 写文章/发帖/加入社区
会员中心
创作中心

完善资料让更多小伙伴认识你,还能领取20积分哦,立即完善>

3天内不再提示

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

马哥Linux运维 来源:Ken的杂谈 2023-05-15 09:05 次阅读

一、前言

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

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

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

二、HTTP 状态码参考

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

32f83dae-f2b6-11ed-90ce-dac502259ad0.png

图片

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

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

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

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

三、参数约定

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

3324402a-f2b6-11ed-90ce-dac502259ad0.png

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

3340f0da-f2b6-11ed-90ce-dac502259ad0.png

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

四、个性化 Message

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

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

20001,订单创建失败,存在进行中的订单

20002,订单创建失败,上一个订单正在排队创建中

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

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

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

33534ed8-f2b6-11ed-90ce-dac502259ad0.png

图片

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

3367b18e-f2b6-11ed-90ce-dac502259ad0.png

图片

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

五、返回信息的统一处理

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

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

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

等等

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







审核编辑:刘清

声明:本文内容及配图由入驻作者撰写或者入驻合作网站授权转载。文章观点仅代表作者本人,不代表电子发烧友网立场。文章及其配图仅供工程师学习之用,如有内容侵权或者其他违规问题,请联系本站处理。 举报投诉
  • API
    API
    +关注

    关注

    2

    文章

    1499

    浏览量

    61970
  • APM
    APM
    +关注

    关注

    1

    文章

    71

    浏览量

    13008
  • HTTP协议
    +关注

    关注

    0

    文章

    61

    浏览量

    9719

原文标题:如何设计API返回码(错误码)?

文章出处:【微信号:magedu-Linux,微信公众号:马哥Linux运维】欢迎添加关注!文章转载请注明出处。

收藏 人收藏

    评论

    相关推荐

    Linux错误码介绍

    在处理一些程序出错语句中,不管是用户空间还是内核空间,通常都会返回一个错误码。例如`return -ERROR`。
    发表于 06-27 15:48 2069次阅读
    Linux<b class='flag-5'>错误码</b>介绍

    用CubeMX生成LwIP项目,发送使用netconn_write时,会返回错误码-6无法发送的原因?

    现象:用CubeMX生成LwIP(LwIP2.0.3版本)项目,netconn编程,接收没有问题,发送使用netconn_write时,会返回错误码-6(Illegal value),无法发送。而用
    发表于 04-03 07:25

    LabVIEW找不到错误码,USRP

    用LabVIEW操作NI USRP出现错误:The specified session handle is invalid or does not correspond to an active session.并且查不到该错误码-1074118640,求大神指教
    发表于 04-14 16:50

    cRIO电流输出板卡9266,输出时返回错误码 65543是什么意思,如何解决?

    Node节点显示错误,运行返回错误码 65543,我查了下这个的解释是“The power supply voltage level is out of range. Check the supply
    发表于 03-23 21:50

    请问Vxworks remove 返回错误码 errno为0xb83dd0 表示什么意思?

    请问Vxworks remove 返回错误码 errno为0xb83dd0 表示什么意思?
    发表于 07-02 08:19

    Linux如何查看系统提供的错误码

    在用Linux下写C的代码的时候,利用open、create函数总是会出现错误但是返回值为 -1 ,并不能定位错误在哪里,所以查看系统提供的错误码就显得特别有必要了需要包含头文件并且定
    发表于 07-05 07:31

    采用CH573做蓝牙主的时候,连接断开后返回错误码怎么处理?

    连接断开后返回错误码代表上面意识,从那个手册可以看到,Disconnected...Reason:8
    发表于 07-28 07:26

    modbus的功能错误返回什么错误信息?

    modbus在通信的过程中功能错误返回什么错误码
    发表于 10-13 07:48

    Oracle错误码大全

    Oracle错误码大全 ORA-00000 normal, successful completion Cause An operation has completed normally
    发表于 12-26 13:44 55次下载

    微辰金服新中付POS商户警惕这五个错误码

      POS机一旦提示错误码怎么办?微辰金服新中付POS商户警惕这五个错误码。  1、持卡人信用卡被刷拒付  2、因套导致信用卡消费账单与实际消费地不同引发  3、转账业务刷拒付  4、同行竞争恶意
    发表于 03-29 16:06 416次阅读

    Bada系统学习-错误码(Error Codes)

    错误码是指在安装或者加载bada应用时发生错误时显示的编码.每个错误都有对应的错误码.这个编码是用于检查这个错误的原因.下图
    发表于 04-02 14:35 560次阅读

    Docker容器退出是什么意思?导致该退出的动作是什么

    exit code:代表一个进程的返回,通过系统调用 exit_group 来触发。在 POSIX 中,0 代表正常的返回,而 1-255 代表异常
    的头像 发表于 08-02 09:55 704次阅读

    异常处理和错误码管理

    前言 在业务逻辑中,通常使用两种方式处理异常: 返回错误码:优点是性能更好,但是不宜维护。 抛出异常:可以使得代码更清晰,可读性更好,更符合面向对象。 选择哪种需要根据场景而定,不管如何选择,只要
    的头像 发表于 09-25 14:51 731次阅读
    异常处理和<b class='flag-5'>错误码</b>管理

    CAN总线常见错误码及其解决方法

    错误码,这些错误码可以帮助我们诊断和解决问题。 1. 错误帧(Error Frame) 错误码 :当CAN控制器检测到一个帧的错误时,会发送
    的头像 发表于 11-12 10:05 1770次阅读

    串口通信中常见的错误码含义

    在串口通信中,常见的错误码及其含义对于诊断和解决通信问题至关重要。以下是一些常见的串口通信错误码及其解释: CE_BREAK :检测到中断信号。这通常意味着接收到的某个字节数据缺少合法的停止位
    的头像 发表于 11-22 09:26 634次阅读