筋斗云接口编程 / 批量请求

批量请求

筋斗云框架支持批量请求，即在一次请求中，包含多条接口调用。

假设一个前端页面进入时，需要接连调用好多次接口才能完成展现，一般的做法是需要后端重新设计接口来优化。
筋斗云支持batch接口，这时后端不必做任何设计修改，前端只要调用batch接口即可获得优化。

假如前端进入某页面，需要调用下面两个接口：

获取用户信息
User.get() -> {id, name, phone, ...}

上传用户操作日志
ActionLog.add()(page, ver, userId) -> id

批处理允许把两个请求一次性提交，减少交互带来的开销。

如果前端H5应用使用了筋斗云前端框架，可以非常方便的启动/禁用批处理操作，只需要在多次调用前加一行useBatchCall，就可将多次调用合并成一次批调用：

MUI.useBatchCall(); // 在本次消息循环中执行所有的callSvr都加入批处理。
// MUI.useBatchCall({useTrans:1}); // 启用事务的写法

// 调用一
var param = {res: "id,name,phone"};
callSvr("User.get", param, function(data) {} )

// 调用二
var postParam = {page: "home", ver: "android", userId: "{$1.id}"};
callSvr("ActionLog.add", function(data) {}, postParam, {ref: ["userId"]} );

其原理是使用batch接口，在POST内容中设置每个调用，请求示例如下：

POST /mysvc/api.php/batch

[
    {
        "ac": "User.get",
        "get": {"res": "name,phone"}
    },
    {
        "ac": "ActionLog.add",
        "post": {"page": "home", "ver": "android", "userId": "{$-1.id}"},
        "ref": ["userId"]
    }
]

POST内容的格式是一个JSON数组，数组中每一项为一个调用声明，参数有ac, get, post, ref等, 只有ac参数必须，其它均可省略。

参数
- get: URL请求参数。
- post: POST请求参数。
- ref: 使用了batch引用的参数列表。

后面的请求还可以引用前面请求返回的内容作为参数。例子中，调用二中参数userId引用了调用一的返回结果，userId的值”{$1.id}”表示取第一次调用值的id属性。 注意：引用表达式应以”{}”包起来，”$n”中n可以为正数或负数（但不能为0），表示对第n次或前n次调用结果的引用，以下为可能的格式：

"{$1}"
"id={$1.id}"
"{$-1.d[0][0]}"
"id in ({$1}, {$2})"
"diff={$-2 - $-1}"

花括号中的内容将用计算后的结果替换。如果表达式非法，将使用”null”值替代。

在创建批量请求时，可以指定这些调用是否在一个事务(transaction)中，一起成功提交或失败回滚。
如果想让这批请求在一个事务中处理，只需要增加URL参数useTrans=1：

POST /mysvc/api.php/batch?useTrans=1

batch的返回内容是多条调用返回内容组成的数组，样例如下：

[0, [
    [ 0, {id: 1, name: "用户1", phone: "13712345678"} ],  // 调用User.get的返回结果
    [ 0, "OK" ]  // 调用ActionLog.add的返回结果
]]