用产品思维设计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接口设计 注意问题

摘要: 总结一下API接口开发过程中的注意事项 1、跨平台性 所谓跨平台是指我们的接口要能够支持不同的终端,比如Android、iOS、windowsphone以及桌面软件、网站等。如:不同的终端每页...
  • gb4215287
  • gb4215287
  • 2017年02月16日 09:50
  • 1105

api接口设计

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

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

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

常见错误码及定义

常见错误码及定义 目录 一、授权/令牌请求接口返回码二、API通用返回码 一、授权/令牌请求接口返回码 描述应用发起授权请求或令牌请求时,开放平台的返回码。 ...
  • ycl295644
  • ycl295644
  • 2016年02月03日 09:18
  • 5729

taobao API 错误码一览表

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

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

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

系统出错信息设计

【系统出错信息设计】详细设计说明书    文件状态: [√] 草稿 [ ] 正式发布 ...
  • WuOu
  • WuOu
  • 2007年10月30日 17:18
  • 3768

错误代码的设计!

shipatrioc http://www.jdon.com Dec 3, 2004 8:04 PM 回复 是这样在系统中web端最终给客户的错误提示是根据这样一个class来显示的.public ...
  • daoquan
  • daoquan
  • 2005年02月02日 14:03
  • 1013

规范定义的错误码

1.1 DSMP规范定义的错误码 1.1.1 MISC响应代码与业务网关之间接口消息的错误代码 错误代码 错误描述 备注 0 成...
  • fuzhouxufeng
  • fuzhouxufeng
  • 2014年06月30日 08:10
  • 4998

APP系统报错日志反馈机制设计

APP日志调取与服务器的交互设计APP日志调取接口设计接口约定接口返回说明 参数 参数类型 说明 code Integer 含义类似http协议返回码,200代表成功 mes...
  • RuihanChen
  • RuihanChen
  • 2016年04月12日 15:16
  • 3047
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:用产品思维设计API(四)——随意定义错误码,你还在这样干?
举报原因:
原因补充:

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