用产品思维设计API(四)——随意定义错误码,你还在这样干?

用产品思维设计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,开发完后使用的时候,就会发现。

用产品思维设计API(四)——随意定义错误码,你还在这样干?_第1张图片

提示语,居然是后端给我们直接返回回来的,“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 20171311936
@weixin stchou_zst
@blog http://blog.csdn.net/yzzst 

用产品思维设计API(四)——随意定义错误码,你还在这样干?_第2张图片

你可能感兴趣的:(Android,Java,如何带领你的团队)