共计 1521 个字符，预计需要花费 4 分钟才能阅读完成。
起源：https://ken.io/note/api-error…
一、前言
客户端申请 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
这样咱们就能够让手机 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 开发手册（嵩山版）》最新公布，速速下载！
感觉不错，别忘了顺手点赞 + 转发哦！