[php] 編寫接口的規范

一. 接口按請求人可以分為兩種：

　　一種是被其他內部項目調用的接口（包括js異步請求的接口和定時程序）。

　　另一種是對外的接口，主要提供給外部開發者調用的。

     兩種接口最大區別就是，內部接口不需要太嚴格的身份驗證，而對外接口需要嚴格的身份驗證，加密解密方式各種各樣，其中最常見最簡單的就是http basic驗證，例如我們的大后台彈出的賬號和密碼彈窗 就是用了basic驗證，輸入賬號和密碼才能通過驗證。但是如果內部接口涉及到重要的操作，不希望被他人惡意請求的話，還是要做一點加密驗證的。

二. 無論是哪一種接口，都應該考慮到下面的問題：

　　1.安全。參數安全：這個我們有$_INPUT基本就足夠了。是否需要身份驗證：如果只是內部通知類/回調類的接口的話就算被惡意請求也不會影響數據正常，這種的話可以完全不做驗證，舉個栗子，我做個一個同步訂單狀態的接口，里面的流程是，查詢訂單狀態有問題的訂單，然后更新這些訂單的狀態。這種接口不需要返回任何值，就算被壞人惡意調用也不會有毛線影響的，那就根本沒必要做身份驗證了。所以這個是否加驗證是按照接口實際邏輯決定的。

      2.能否重復請求。例如某個接口是根據傳入的訂單號，插入一條數據，需要做好重復請求的判斷，避免插入多條數據。

三. 編寫接口規范

　　1. 用 try...catch...結構去寫。（主要是 throw 可以隨時結束程序，這樣很爽~）

      2. 返回狀態碼，不要返回success等於true或者false，如果要編寫文檔，關於不同錯誤碼的含義也應該寫明白，方便調用方查詢出錯原因。

 下面直接看栗子：

<?php
    $code = 200; // 接口狀態碼 

    $name = trim($_INPUT['name']);
    $age  = trim($_INPUT['age']);
    if (empty($name))
    {
        $code = 401;
        throw new Exception('名字不能為空');
    }
    if (!is_numeric($age))
    {
        $code = 402;
        throw new Exception('年齡必須由數字組成');
    }
    
    $database_obj = new database_class();
    $res = $database_obj->save($name, $age);
    if ( !$res )
    {
        $code = 403;
        throw new Exception('保存數據失敗');
    }    
    $msg = 'ok';
} catch ( Exception $e ) {
    $msg = $e->getMessage();
}
output_json($code,$data,$msg); // $data可以放置需要返回的數據
// output_json函數在大function里面有~如果不想引入大function的話可以復制一份到自己項目
// ========END=======