大前端接口规范

Question

1、基本规范

• 查询、获取之类的接口，通用 get 请求
• 添加、修改、删除的接口，通用 post 请求

2、基本 json 格式

//当 code == 200 时候 是成功 data 中是要用的数据
//当 code != 200 时候 msg 中是错误的信息，用于前端的错误提示
{
"code": 200,
"data": {},
"msg": "xxxxxxxxxxx",
}

• 通过 code 判断接口成功与失败与否，失败的话，前端直接展示 msg 返回的内容，具体内容后端输出
• 不能通过返回的 msg 进行判断，msg 只是用于直接获取在前端界面展示的文案

3、key 值

• 如果列表接口中没有的数据，也需要将 json 的 key 返回，不能缺少 key 值，
• 默认的 key－value
• json：{}
• array：[]
• string：’’
• number：0

4、语义化

• 接口名称语义化，以动词+名词组合，例如 getVideoList、editVideoInfo
• 不接受 list.html 格式的接口，会误认为是静态界面
• 接口字段语义化，符合大众阅读标准

5、时间格式

• 传入、传出时间，都按标 13 位准时间戳来显示
• 不接受各后端不同的类似于 2016-11-12 12:00:00 这种返回

6、关于跨域

• 如果有跨域请求的接口，需要加上 jsonp 格式的调用
• 据现有多数的接口，callback 的 key 值为 jsoncallback，
• 如果接口为不同的 key 值的话，预先通知到前端

7、编码

• 请求、返回的编码，均必须为 utf-8 编码，不允许出现返回乱码，乱码不利于抓包调试
• 由于 ie 系的 bug，接口请求的时候，需要把请求中的中文字段编码，后台接口请解码控制

8、体积

接口尽量体积小，没必要将字段删减到最小，但最好不要上 100k

9、分页格式

请求接口，当前页码 key——page，以 1 开始

每页条数 key－rows，一般是 10，返回格式：

{
  code: 200,
  data: {
    items: [
      { id: 1, name: 'xxx' },
      { id: 2, name: 'xxx' },
    ],
    page: { curPage: 1, pageSize: 10, totalPage: 2, totalRow: 20 },
  },
  msg: 'xxxxxxxxxx',
};

10、添加回调

默认需要将新添加的 json 对象返回，用于不刷新界面继续操作

11、session过期

后台返回接口

// ajax: httpstatus 400
{
  errCode: '9000',
  errMsg: 'http://uc.lecloud.com/login.do?backUrl=http://saas.lecloud.com',
  errShowMsg: '用户未登录',
};

前台控制— jquery ajax 统一过滤

// 判断控制浏览器跳转，http code 为 400 时，判断 errcode 值
$(document).ajaxError(function (event, request, settings, thrownError) {
  console.log(request);
  try {
    if (request.status == 400) {
      var responseJSON = JSON.parse(request.responseText);
      if (responseJSON.errCode == 90000) {
        top.window.location.href = responseJSON.errMsg;
      }
    }
  } catch (e) {}
});

12、分享、同步策略

• 具体接口由后端的同学在开发之前，写在自己项目的 wiki 上面
• wiki 上接口文档，如果返回的内容
• 接口变动的话，通知到前端同学
• 如果是多终端公用的接口，wiki 上面使用者将自己的使用情况备注一下
• 各后端系统尽量保持一致，开发之前，前后端确认接口
• 如果是提供给多端的接口，格式化的内容尽量在后台接口中统一，以达到各终端显示一致