艺术~如何设计一套优秀的API响应体

前言

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

有的API用返回码是int类型，有的是string类型，有的用0表示成功，又有的用1表示成功，还有用“true”表示成功，碰上这种事情，只能说：沟通起来真头疼。

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

参考HTTP状态码

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

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

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

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

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

优秀的设计

虽说是返回码设计，但是只有code是不行的，还要有对应的message，让人可以看懂，有data统一管理数据。

进行分段处理

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

个性化Message

目前有三个问题

1. 在不同的场景下，同样的错误，可能需要给不同用户端（APP 小程序 网页）看到不一样的错误提示。
2. 通常我们的Message都是写给工程师看的，但是对于用户来说，返回的信息又必须是准确的，所以用户看到的就必须转译。
3. 完整的message如果在服务与服务之间传输调用也是没必要的浪费。

• 所以可以把转译的消息配置到数据库，并缓存到Redis或者API本机，在请求最后要返回的时候进行转译。
• 可以在请求开始的时候就从不同的用户端传入不同的application_id参数，然后在请求处理结束即将返回的时候，根据application_id+code，去匹配替换message。
  

额外的好处

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

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

我们可以根据Code的返回饼图，帮助我们发现系统、业务流程中的问题，及时的去优化业务。

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