筋斗云接口编程 / 常用操作（二）

接口返回

函数应返回符合接口原型中描述的对象，框架会将其转为最终的JSON字符串。

比如登录接口要求返回{id, _isNew}：

login(uname, pwd, _app?=user) -> {id, _isNew?}

因而在api_login中，返回结构相符的对象即可：

$ret = [
    "id" => $id,
    "_isNew" => 1
];
return $ret;

最终返回的JSON示例：

[0, {"id": 1, "_isNew": 1}]

如果接口原型中没有定义返回值，框架会自动返回字符串”OK”。比如接口api_logout没有调用return，则最终返回的JSON为：

[0, "OK"]

[异常返回]

如果处理出错，应返回一个错误对象，这通过抛出MyException异常来实现，比如

throw new MyException(E_AUTHFAIL, "bad password", "密码错误");

它最终返回的JSON为：

[-1, "密码错误", "bad password"]

分别表示[错误码, 显示给用户看的错误信息, 调试信息]，一般调试信息用英文，在各种编码下都能显示，且内容会详细些；错误信息一般用中文，提示给最终用户看。

也可以忽略错误信息，这时框架返回错误码对应的默认错误信息，如

throw new MyException(E_AUTHFAIL, "bad password");

最终返回JSON为：

[-1, "认证失败", "bad password"]

甚至直接：

throw new MyException(E_AUTHFAIL);

最终返回JSON为：

[-1, "认证失败"]

常用的其它返回码还有E_PARAM（参数错）, E_FORBIDDEN（无权限操作）等:

const E_ABORT = -100; // 要求客户端不报错
const E_PARAM=1; // 参数不合法
const E_NOAUTH=2; // 未认证，一般要求前端跳转登录页面
const E_DB=3; // 数据库错
const E_SERVER=4; // 服务器错
const E_FORBIDDEN=5; // 无操作权限，不允许访问

[立即返回]

接口除了通过return来返回数据，还可以抛出DirectReturn异常，立即中断执行并返回结果。

示例：实现获取图片接口pic。

pic() -> 图片内容

注意：该接口直接返回图片内容，不符合筋斗云[0, JSON数据]的返回规范，所以用DirectReturn立即返回，避免框架干预：

function api_pic()
{
    header("Content-Type: image/jpeg");
    readfile("1.jpg");
    throw new DirectReturn();
}

前端可以直接使用链接显示图片：

<img src="http://localhost/mysvc/api.php/pic">

示例：查询天气接口

weather(areaid) -> { data }

在实现时，调用第三方服务接口来获取天气，由于第三方已经返回JSON数据，无须再解码、编码，直接包装成筋斗云格式返回即可：

function api_weather()
{
    $areaid = mparam("areaid");

    $URL="http://open.weather.com.cn/data/?areaid=".$areaid;
    @$rv = file_get_contents($URL);
    if ($rv === false || is_null(json_decode($rv))) {
        addLog($rv);
        throw new MyException(E_SERVER, "bad data");
    }
    // 将已编码好的JSON数据包装成筋斗云返回格式
    echo "[0, $rv]";
    throw new DirectReturn();
}

上面在处理失败时，调用函数addLog用于将日志返回给前端，便于测试模式下查看。还可以用logit函数记录到服务端文件中。