数据请求须知

API 接口配置

目前，所有的前后端接口配置均位于 common/config 模块下，只需定义接口 URL，bat-ria 在初始化时会自动对齐进行封装，调用 io/serverIO 模块提供的 request 方法，生成返回异步请求 promise 的函数。默认情况下，对于以 upload 或 download 结尾的 URL，不会进行封装。上传路径通常只要给 Uploader 控件传递相应字符串 URL 即可，而下载功能可以通过 bat-ria/util 模块中的 download(url) 方法实现。

配置

// common/config
var apiConfig = {
    adList: '/data/173/list',
    adListDownload: '/data/173/list/download',
    imageUpload: '/data/image/upload'
};

调用

var api = require('common/config').api;

// sending AJAX requests
api.adList({
    keyword: 'hello'
}).then(function (data) {
    // resolved
}, function (message) {
    // rejected
});

// downloading data
var util = require('bat-ria/util');
util.download(api.adListDownload + '?keyword=hello');

serverIO 模块须知

在 bat-ria 中，通过 io/serverIO 封装了我们常用的业务端前后端接口的数据请求功能。AJAX 请求通过 er/ajax 模块进行发送，所以在使用中，除了 serverIO 本身的一些钩子，也可以调用 ajax 模块提供的一些预留钩子做一些订制化的处理。

接口格式

目前 NMP 提供两种格式的返回数据：

1. 新版接口

   请求成功

   {
       "code": 0,
       "result": {
           "id": 42,
           "name": "Universe"
       }
   }

   全局错误

   {
       "code": 1,
       "message": {
           "global": "创建用户失败"
       }
   }

   字段验证失败（表单提交时使用）

   {
       "code": 2,
       "message": {
           "field": {
               "name": "用户名“steve_rogers”已经存在，请重新输入",
               "age": "“-1”不是一个合法的年龄，请重新输入"
           }
       }
   }

   重定向（登录超时需要重定向，路径由后端给出，错误提示固定为登录超时）

   {
       "code": 3,
       "message": {
           "redirect": "http://jn.baidu.com/"
       }
   }

   session超时（登录超时需要重定向，路径在前端定义，错误提示由后端给出）

   {
       "code": 4,
       "message": {
           "noSession": "登录超时"
       }
   }

   自定义错误（code ≥ 100，返回值自定义）

   {
       "code": 101,
       "message": {
           "reason": "姿势不对"
       }
   }

2. 老版接口

   与新版接口基本相同，区别在于在 code === 0 时，老版接口返回字段为 "success": true，而在其他情况下，则返回 "success": false，没有自定义错误类型的功能。

Hooks

通过实现一些预定义的钩子，可以对处理的过程进行一定的定制，大致的流程和钩子名称如下所示。

io.request(url, data, options)
  │
  ├───── io.hooks.beforeRequest(data) ───┐
  │                                      │
  │<────────────── data ─────────────────┘
  │
  ├───── io.hooks.afterResponse(data) ───┐
  │                                      │
  │<────────────── data ─────────────────┘
  │
  └─────────────────┐
  ┌──── success ────♦──── failure ────┐
  │                                   │
  ├─ io.hooks.afterSuccess(data) ─┐   ├─ io.hooks.afterFailure(message) ─┐
  │                               │   │                                  │
  │<──────────── data ────────────┘   │<───────────── message ───────────┘
  │                                   │
  ├───────────────────────────────────┘
  ●

需要注意的是，当采用新版接口且后端返回中 code >= 100 时，传递到 io.hooks.afterFailure 及请求的 promise 在 reject 状态下的处理函数中的 message 对象下，会附加上 code 属性，方便后续定制处理。