时序图示

时序图(如果有)

开放的API

其它说明

  1. 请求类型为long表示64位长8字节整数,int表示32位长4字节整数,String表示变长字符串,Part表示HTTP协议的multipart/form-data标准的上传文件。其它类型约定请参见这里
  2. 响应类型需要参考各数据库的定义
  3. Unix标准时间表示自1970年1月1号0点0分0秒开始直目标时间所经过的毫秒数。非Unix标准实现如日期型转换时考虑将当前日期减去1970-01-01 00:00:00再获取总共毫秒数。请注意,日期类型在电子计算机中不论其软件如何表述其运算都要进行数字转换,因此良好性能习惯就是使用数字型,可大大提高搜索和比较速度。
  4. 框架为标准三层结构设计,负责与操作人交互的界面层 > 负责检查和准备业务条件的业务逻辑层 > 负责处理应用业务变更的数据层。
  5. 标准返回中code表示状态码(32位长有符号数字),data表示相关数据,msg只在失败时有字符串值(只在发生界面层不能理解的情况有此值,如用户名包含禁用字符,界面层并不知道用户名是否可以包括特定过滤字符),处理逻辑如下:
    • 当code小于0,表示操作失败,请根据状态码含义去提示操作人。在业务逻辑层失败,有时会返回msg值,请复合提示(一行状态码含义,一行msg如果有)
    • 当code大于等于0,表示业务逻辑层是成功的,状态码将由数据层提供,展开如下:
      • 在支持分页(参数带有页码和页记录数的方法)的方法,返回的数据中code的值表示当前条件下的总记录数,可自行除以记录数得出总页数。
      • 在新增操作(如新增收货地址)的方法,返回的数据中code的值表示新增记录的编号。
      • 在检查已存在(如检查用户名是否已存在、检查商户是否有货)的方法,返回的数据中code为0表示不存在,为其它大于0表示存在多少数量。
      • 在其它操作(如帐号登录、更新用户资料),返回的数据中code的值表示给定的条件下影响到的记录数。如帐号登录时给定的用户名和密码影响到0条表示该条件未匹配到任何数据。
  6. 当API有针对身份时,需要先调用登录并在后续的API中维持HTTP协议响应中的Cookie头值。当超过标准时间(通常为20分钟)没有活动(无HTTP调用),则存储的身份将被回收,并返回-1213状态码,这种情况在微端请自行调用一次登录API。
    或者理解为,每次API调用都需要传递身份信息,为避免每次的帐号密码的传递,我们约定传递特定token,此token在登录后我们将该token关联至某个用户身份。为了简化这个过程,兼容浏览器(自带Cookie支持)、Android端的CookieManager、IOS的NSHTTPCookieStorage实现,该token即HTTP协议的头值Cookie,于实现需要记录该头值并在下次请求时带上该头值。
  7. 本页面已为小型设备浏览器布局优化。
  8. 点击这里下载演示代码(如果发生未找到错误,则说明未提供演示代码)。

状态码含义

switch (code) {
    case 0:
    case 1: //大于等于0表示无错误
        return null;
    case -1:
        return "操作已成功,但产生警告请进行成果较验";
    case -9:
        return "请求已接收,但尚未开放或暂停使用";
    case -114:
        return "当前服务忙,请稍候再试";
    case -119:
        return "当前服务处于不可用状态,请稍候再试";
    case -122:
        return "发生未识别的错误,请记下操作过程并反馈给我们";
    case -144:
        return "数据操作失败,请检查各值长度、类型并稍候再试";
    case -149:
        return "数据引擎忙,请稍候再试";
    case -1000:
        return "参数无效,请确认输入格式正确且必填项均已填写";
    case -1001:
        return "值不在允许的范围,例如太大、小或太长或格式非法";
    case -1204:
        return "无法联系到目标或暂不可用";
    case -1209:
        return "操作步骤错误,请重启流程再试";
    case -1211:
        return "认证失败,请检查凭证是否输入正确";
    case -1213:
        return "目标已拒绝此访问,请检查是否登录到正确身份";
    case -1224:
        return "目标不存在或该内容已被删除";
    case -1225:
        return "目标已存在并且不能被替换";
    case -1229:
        return "该功能不受支持,或运行环境不匹配";
    default:
        return "未知错误码:" + iCode;
}