用产品思维设计API——随意定义错误码，你还在这样干？

Posted 2022-06-23 北漂周

用产品思维设计API（四）——版本控制，没有你想的这么简单

前言

最近公司内部在重构项目代码，包括API方向的重构，期间遇到了很多的问题，不由得让我重新思考了下。
- 一个优雅的API该如何设计？
- 前后端分离之后，API真的解耦分离了吗？
- 不断的版本迭代，API的兼容性该如何做？

ps.这里所说的API仅为Web API，提供APP\\WEB开发使用。

年前，我司内部的接口已经进入了一个完全的重构阶段，参考了市面上各大平台的API和文档，自己也总结出了很多的心得。这里向大家分享一下，接下来一个月，我们向从下面几个方面向大家介绍一个优雅的API（至少我认为挺优雅）该如何设计。

1. RESTful就是个骗局 (http://blog.csdn.net/yzzst/article/details/53775319)
2. 数据解耦，才是前后分离的本质(http://blog.csdn.net/yzzst/article/details/53844590)
3. 版本控制，没有你想的这么简单（http://blog.csdn.net/yzzst/article/details/54755077）
4. 随意定义错误码，你还在这样干？（http://blog.csdn.net/yzzst/article/details/54799971）
5. 安全，就只能用HTTPS？（http://blog.csdn.net/yzzst/article/details/54882346）

ps. 打一个广告，公司内部现在在招聘各种技术岗位，Java、android、前端等，待遇保证能让你涨30%，有兴趣的朋友可以加韬哥的微信（微信号：stchou_zst），二维码在文章最后。

---

为什么API要定义错误码？

这还用废话，基本就是定义一下在API请求的时候使用是否错误的提示呗。

先看看我们现有的错误码：

错误码	错误描述	解决方案
-1	系统错误	系统内部错误，请直接联系技术支持
10001	userId过期	账号过期
10002	password格式错误	密码格式错误
10003	password错误	密码错误
10004	请求没有签名	请使用协议规范对请求中的参数进行签名
10005	登录次数受限	等会儿再登录

有什么不妥吗？乍一看并不觉得啊。

ok，开发完后使用的时候，就会发现。

提示语，居然是后端给我们直接返回回来的，“userid是啥？”、“userid is lost~我改如何操作？”，给用户的体验特别不好。很多时候我们的提示语句需要卖卖萌，或者欲盖弥彰。需要提示的语句并不是服务器返回的语句。

那这个登录过期例子来说，服务端返回：

    "request" : "/getUserInfo",
    "error_code" : "-10015",
    "error" : "userid is expire"

APP进行操作：
- 提示登录过期，重新登录
- 清空存储的用户信息
- 跳转到登录界面

我们就会发现，对于不同的错误码，我们有些需要将服务端返回的信息进行弹窗提示，有些有不需要提示。有些错误不仅仅需要提示，还需要在提示后做一些相应的操作，如清空本地缓存等内容。

这里我们做了一个简单的总结，对于错误码的功能来说，分为以下几种情况

1. 做对应的操作
2. 做对应的提示
3. 屏蔽性的仅提示

没错，除了方便开发人员进行后台查询以外，客户端研发就只关心这么多。

重新设计错误码

根据之前的经验来说，这么我们就可以很好得设计了。

• 定义错误提示级别，1为服务端返回提示、2为不提示、3隐藏性卖萌提示。
• 定义具体的错误模块，登录相关/订单相关/产品相关
• 具体错误编号，自增即可，一个项目9999种错误应该够用；

如，对于错误码20502 来说

第1位	2~3位	4~7位
2	05	0002
错误提示级别，不提示	服务模块代码	具体错误代码

返回的信息是：

    "request" : "/statuses/homeTimeline",
    "error_code" : "20502",
    "error" : "Need you follow uid."

这个接口返回的错误信息，就是使用上的错误，不应该提示。

---

写在后面，最近刚过完年了，公司业务繁忙，重构任务重大，更新博客也慢了。希望大家多多包涵。

@author zhoushengtao(周圣韬)
@since 2017年1月31日 19：36
@weixin stchou_zst
@blog http://blog.csdn.net/yzzst