面试官：如何设计API返回码（错误码）？

亦凉 2024-03-16 23:51 4阅读 0赞

### **一、前言** ###

###  ###

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

###  ###

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

###  ###

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

###  ###

### **二、HTTP 状态码参考** ###

###  ###

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

![fda67f16bc03cb2f2467570dcf18010c.png][]

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

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

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

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

**三、参数约定**

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

![34ded46757b55c2efb7e8da31a6f7c01.png][]

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

![f6247203904903d1142aec4790d7c7e9.png][]

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

**四、个性化 Message**

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

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

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

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

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

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

![9ee6e95acb2b3357d62cf130d6feb34c.png][]

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

![74b52770527c3914e432062add903ed5.png][]

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

### **五、返回信息的统一处理** ###

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

###  ###

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

###  ###

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

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

[fda67f16bc03cb2f2467570dcf18010c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/9108c76c25e943ceb091a1a8134d7407.png
[34ded46757b55c2efb7e8da31a6f7c01.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/b4b74f8b2f44431581b749ebd1f01ee2.png
[f6247203904903d1142aec4790d7c7e9.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/a3844a201d2444bbbfdfe21c198e46ea.png
[9ee6e95acb2b3357d62cf130d6feb34c.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/d255e2ee74ce48b19200b8f40eb2837f.png
[74b52770527c3914e432062add903ed5.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/15/a746c5feb9074570a9e57937cd2a2d30.png