如何设计API返回码(错误码)?
前言
客户端请求API,通常需要通过返回码来判断API返回的结果是否符合预期,以及该如何处理返回的内容等。
相信很多同学都吃过返回码定义混乱的亏,有的API用返回码是int类型,有的是string类型,有的用0表示成功,又有的用1表示成功,还有用“true”表示成功,碰上这种事情,只能说:头疼。
API返回码的设计还是要认真对待,毕竟好的返回码设计可以降低沟通成本以及程序的维护成本。
HTTP状态码参考
以HTTP状态码为例,为了更加清晰的表述和区分状态码的含义,HTTP状态做了分段。
对于后端开发来说,我们通常见到的都是:
2XX状态码,比如200->请求成功。
5XX状态码,比如502->服务器异常,通常就是服务没正常运行,或者代码执行出错。
通过状态码即可初步判断问题原因,HTTP状态的设计思路值得借鉴。
参数约定
虽说是返回码设计,但是只有code是不行的,还要有对应的message,让人可以看懂。
参考HTTP状态码的思路,我们对错误码进行分段。
通过这样的设计,不论是程序还是人都可以非常方便的区分API的返回结果,关键是统一!
个性化Message
通常我们的Message都是写给工程师看的,但是在不同的场景下,同样的错误,可能需要给用户看到不一样的错误提示。
比方说20000-29999表示订单创建失败:
20001,订单创建失败,存在进行中的订单
20002,订单创建失败,上一个订单正在排队创建中
这两种错误情况如果是给用户看,可能就只适合看到:很抱歉,您有一个正在进行中的订单,请到我的订单列表中处理。
但是对于API来说,返回的信息又必须是准确的,但用户看到的就必须转译,这个转译的工作调用方可以做,但是通常API提供者来提供个性化的Message能力会更好。
我们可以把转译的消息配置到数据库,并缓存到Redis或者API本机。
然后在请求处理结束即将返回的时候,根据application_id+code,去匹配替换message。
这样我们就可以让手机APP的用户、微信小程序的用户、网页下单的企业用户看到不同的消息。
返回信息的统一处理
有了统一的code,我们就可以通过Nginx或者APM工具统计API请求Code数量及分布信息。
我们可以根据单位时间内99999的数量来做API的异常告警。
我们可以根据Code的返回饼图,帮助我们发现系统、业务流程中的问题。
等等……
总之,好的返回码设计,可以帮助我们提高沟通效率,降低代码的维护成本
原文链接:https://ken.io/note/api-errorcode-or-resultcode-desgin
如何设计API返回码(错误码)?相关推荐
- 银联POS返回码/错误码详解
00 --pos机交易成功 承兑或交易成功 01 --pos机交易失败,请联系发卡行 查发卡行或检查卡内余额 02 --同上 03-- 商户未登记,无权使用银联pos机终端 联系银行卡服务中心处理 0 ...
- 关于SP一些响应码的API返回码及解析集合
在一些金融的行业(银行.证券.保险等),如果接触了一些中间件,比如长城.恒银.广电等一些厂商的设备,不同的厂商有不同的一些规范,在应用开发的过程中难免会和中间件的错误码打交道,这里总结一下.基本常用的 ...
- curl返回常见错误码
关注公众号 风色年代(itfantasycc) 300G微服务资料等你拿! curl返回常见错误码 - 阿波伦 - 博客园 CURLE_OK(0) 成功. CURLE_UNSUPPORTED_PROT ...
- LoadLibrary下错误返回126错误码排查过程
在开发一些Windows下的应用程序过程中,经常会手动加载一些DLL,使用的就是LoadLibrary这个函数,而这个函数一旦失败,返回的错误码基本都是126,126错误码的意思是找不到指定的模块,这 ...
- libcurl中上传文件的坑-英文操作系统中文路径无法上传返回26错误码
libcurl中上传文件的坑-英文操作系统中文路径无法上传返回26错误码 最近在使用libcurl使用表单形式上传本地文件,自己测试的时候都没有问题,但是在测试的电脑上无法上传,返回26错误码,在li ...
- linux udp 广播recvfrom 返回 -1 错误码是 11 EAGAIN Resource temporarily unavailable
版本:银河麒麟桌面操作系统V10(SP1) 内核:Linux 5.4.18-28.23-bj-generic CPU:Loongson-3A5000 架构:loongarch64-linux-gnu ...
- 使用百度地图定位功能第一次成功,第二次开始返回505错误码
使用百度地图定位功能第一次成功,第二次开始返回505错误码 505错误码的意思是AK错误,申请AK的时候要严格按照官网的教程 http://lbsyun.baidu.com/index.php?tit ...
- 中文解释“GetLastError()返回值”---错误码大全
GetLastError函数的定义形式为: DWORD GetLastError(VOID); SetLastError函数主要在对api函数进行模拟的dll函数中使用. (0)-操作成功完成. (1 ...
- VC中GetLastErro返回的错误码
原文地址:http://www.cnblogs.com/braver/articles/2563157.html [0]-操作成功完成. [1]-功能错误. [2]-系统找不到指定的文件. [3]-系 ...
最新文章
- 正则表达式简介及在C++11中的简单使用
- python基础--函数
- WP缩略图出不了,打开缩略图提示“A TimThumb error has occured”
- Acwing 307. 连通图
- Vue 组件的自定义事件
- vs2005下,回发或回调参数无效的解决方法
- 分布式数据库中间件–(1) Cobar初始化过程
- linux php服务器搭建,如何搭建linux服务器
- 阿里云为什么在十三年后重构调度系统?
- 百度云盘资源下载器分享【只要有分享地址+提取码】
- ex10_13几何:正n边形
- VBA的userform 相关的基本事件,方法和属性,以及 userform.name 使用规范备忘
- C语言因式分解的程序框图,C语言编写方案-因式分解
- 纸壳CMS列表Grid的配置
- NOIP2015跳石头【二分答案(最小值最大化) | 贪心】
- leaflet移动图标(leaflet篇.68)
- python读取图片的几种方式
- MyEclipse使用Maven创建web项目+搭建SSM框架教
- MBT测试实例:做个“机器人”,使其随机、持续的对“web页面”做交互性测试(三)测试建模画图准备
- Windows CMD命令行进行日期计算及本件备份