有偿问答
面经分享
技术探讨
资料领取
登录
如何设计API返回码(错误码)?
社长
1年前
⋅ 452 阅读
### 一、前言 客户端请求 API,通常需要通过返回码来判断 API 返回的结果是否符合预期,以及该如何处理返回的内容等 相信很多同学都吃过返回码定义混乱的亏,有的 API 用返回码是 int 类型,有的是 string 类型,有的用 0 表示成功,又有的用 1 表示成功,还有用”true” 表示成功,碰上这种事情,只能说:头疼 API 返回码的设计还是要认真对待,毕竟好的返回码设计可以降低沟通成本以及程序的维护成本 二、HTTP 状态码参考 ------------ 以 HTTP 状态码为例,为了更加清晰的表述和区分状态码的含义,HTTP 状态做了分段。 ![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20211208/e4ea2f46cf3f4a2a86b370cf56fbcfb8.png) 对于后端开发来说,我们通常见到的都是: 2XX 状态码,比如 200-> 请求成功, 5XX 状态码,比如 502-> 服务器异常,通常就是服务没正常运行,或者代码执行出错 通过状态码即可初步判断问题原因,HTTP 状态的设计思路值得借鉴。 三、参数约定 ------ 虽说是返回码设计,但是只有 code 是不行的,还要有对应的 message,让人可以看懂 ![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20211208/a35f8deb30774737837d5146f12ba1be.png) 参考 HTTP 状态码的思路,我们对错误码进行分段 ![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20211208/3625a1879ee7453c8ff261fcf2e636ed.png) 通过这样的设计,不论是程序还是人都可以非常方便的区分 API 的返回结果,关键是统一! 四、个性化 Message ------------- 通常我们的 message 都是写给工程师看的,但是在不同的场景下,同样的错误,可能需要给用户看到不一样的错误提示。 比方说 20000-29999 表示订单创建失败: * 20001,订单创建失败,存在进行中的订单 * 20002,订单创建失败,上一个订单正在排队创建中 这两种错误情况如果是给用户看,可能就只适合看到:很抱歉,您有一个正在进行中的订单,请到我的订单列表中处理。 但是对于 API 来说,返回的信息又必须是准确的,但用户看到的就必须转译,这个转译的工作调用方可以做,但是通常 API 提供者来提供个性化的 Message 能力会更好 我们可以把转译的消息配置到数据库,并缓存到 Redis 或者 API 本机 ![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20211208/673c94952ac64429b05edc60b82d64b3.png) 然后在请求处理结束即将返回的时候,根据 application_id+code,去匹配替换 message ![](https://image-1300566513.cos.ap-guangzhou.myqcloud.com/upload/images/20211208/3808b3f7a1074a1cb194286d62f9f09f.png) 这样我们就可以让手机 APP 的用户、微信小程序的用户、网页下单的企业用户看到不同的消息 五、返回信息的统一处理 ----------- 有了统一的 code,我们就可以通过 Nginx 或者 APM 工具统计 API 请求 Code 数量及分布信息。 我们可以根据单位时间内 99999 的数量来做 API 的异常告警 我们可以根据 Code 的返回饼图,帮助我们发现系统、业务流程中的问题 等等 总之,好的返回码设计,可以帮助我们提高沟通效率,降低代码的维护成本 > https://ken.io/note/api-errorcode-or-resultcode-desgin
阅读全部
全部评论:
0
条
我有话说:
@
发送
-- 目录 --
关注官方公众号:
Java问答社
接收最新有赏问答推送!
最新发布
1.
SpringBoot 接口数据加解密技巧,so easy!
2.
一个依赖搞定 Spring Boot 反爬虫,防止接口盗刷!
3.
Java8 Stream 极大简化了代码,它是如何实现的?
4.
马上大四了,秋招还是春招好?先找工作还是找实习?
5.
万字详解 Linux 常用指令(值得收藏)
6.
4年工作经验,多线程间的5种通信方式都说不出来,你敢信?
最新评论
部署文档没有了,您能提供下吗
部署文档没有了,能提供下吗
我测你的🐎
源码从哪里获取请问
想学
那篇石墨文档 没有权限查看哇