常用操作 / 介面返回

介面返回

函式應返回符合介面原型中描述的物件，框架會將其轉為最終的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函式記錄到服務端檔案中。

常用操作 / 介面返回

介面返回

相關文章