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

原创 2017年01月31日 19:37:03

用产品思维设计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 20171311936
@weixin stchou_zst
@blog http://blog.csdn.net/yzzst 

这里写图片描述

版权声明:转载请标注:http://blog.csdn.net/yzzst 。 本文为博主原创文章,未经博主允许不得转载。作者:周圣韬(北漂周)

相关文章推荐

api接口设计

写过不少接口,不过一直没有去总结,网上搜了一下,大同小异,此文根据以下几个链接整理修改: https://segmentfault.com/a/1190000004051246 http://blog...

服务端 API 接口设计最佳实践

在移动互联网开发领域,我们经常需要针对移动设备,提供数据访问接口。在移动时代以前,接口设计并没有面对这么大的挑战,因为那时期的应用开发,前后端的区分并没有那么明显,需要专门设计接口的场景并不是很多。 ...
  • xsl_bj
  • xsl_bj
  • 2015年09月07日 16:49
  • 2044

taobao API 错误码一览表

系统级错误 错误码 错误描述(英文) 错误描述(中文) 3 Upload Fail 图片上传失败 4 User Call Limited...
  • ye1992
  • ye1992
  • 2013年02月25日 16:42
  • 11212

常见错误码及定义

常见错误码及定义 目录 一、授权/令牌请求接口返回码二、API通用返回码 一、授权/令牌请求接口返回码 描述应用发起授权请求或令牌请求时,开放平台的返回码。 ...

如何设计系统的错误码及错误信息

作者:朱金灿来源:http://blog.csdn.net/clever101         一个软件系统,肯定是涉及到很多错误信息。比如用户执行出错了,软件需要将错误信息返回给用户。那么如何设计错...

Java 异常设计最佳实践

关于异常在讲Java异常实践之前,先理解一下什么是异常。到底什么才算是异常呢?其实异常可以看做在我们编程过程中遇到的一些意外情况,当出现这些意外情况时我们无法继续进程正常的逻辑处理,此时我们就可以抛出...

错误编码的设计资料搜集

关于错误编码我觉得在软件设计的时候也是必不可少的环节。如果错误编码设计好了,对反馈信息非常有帮助。而有些错误编码的设计真是很优雅。 最常用的错误信息反馈,一般是弹出个消息框,或者打印个错误信息,中断和...

函数返回值及错误码设计

在开发工程中总结的关于函数错误码的设计想法。

API 返回结果设计经验与总结

前言 RESTful API的设计已经很成熟了,大家也都比较认可。本文也不再过多介绍RESTful API相关的知识,而是针对JSON型API的返回结果设计,总结下自己的经验。 结构 ...
  • ishxiao
  • ishxiao
  • 2016年08月15日 14:59
  • 1329

用产品思维设计API(一)——RESTful就是个骗局

用产品思维设计API(一)——RESTful就是个骗局前言 最近公司内部在重构项目代码,包括API方向的重构,期间遇到了很多的问题,不由得让我重新思考了下。 - 一个优雅的API该如何设计?...
  • yzzst
  • yzzst
  • 2016年12月21日 00:53
  • 4709
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:用产品思维设计API(四)——随意定义错误码,你还在这样干?
举报原因:
原因补充:

(最多只允许输入30个字)