用产品思维设计API(四)——版本控制,没有你想的这么简单
前言
最近公司内部在重构项目代码,包括API方向的重构,期间遇到了很多的问题,不由得让我重新思考了下。
- 一个优雅的API该如何设计?
- 前后端分离之后,API真的解耦分离了吗?
- 不断的版本迭代,API的兼容性该如何做?ps.这里所说的API仅为Web API,提供APP\WEB开发使用。
年前,我司内部的接口已经进入了一个完全的重构阶段,参考了市面上各大平台的API和文档,自己也总结出了很多的心得。这里向大家分享一下,接下来一个月,我们向从下面几个方面向大家介绍一个优雅的API(至少我认为挺优雅)该如何设计。
- RESTful就是个骗局 (http://blog.csdn.net/yzzst/article/details/53775319)
- 数据解耦,才是前后分离的本质(http://blog.csdn.net/yzzst/article/details/53844590)
- 版本控制,没有你想的这么简单(http://blog.csdn.net/yzzst/article/details/54755077)
- 随意定义错误码,你还在这样干?(http://blog.csdn.net/yzzst/article/details/54799971)
- 安全,就只能用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隐藏性卖萌提示。
- 定义具体的错误模块,登录相关/订单相关/产品相关
- 具体错误编号,自增即可,一个项目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