「to前端、後端」公司/團隊要不斷的累積組織過程資產，一方面提升產能和效率；一方面豐富內涵。
本次主要講解接口規範，無論是做APP、小程序還是H5，都離不開接口，應該封裝一個接口消息類，用戶反饋消息。
一、接口規範
接口返回四個字段：result、ret、code、message，分別說明：
result：結果，代表邏輯上接口是否執行成功，舉例來說，如果登錄成功，那麼返回true、如果登錄失敗，則返回false
code：錯誤碼，例如200代表成功，901代表內部錯誤等，特殊說明，result和code搭配使用，確保前端可以有效處理問題。還是以登錄為例，用戶登錄失敗，result返回false，但登錄失敗的情況有很多中，例如code=1001代表手機號不存在，則要引導至註冊頁面；code=1002代表密碼過程，則引導至重置密碼等。
message：結果說明，！！注意，這個message是給技術人員看的，提供接口時搭配錯誤碼錶，但為了調試效率，一般後端輸出接口的時候，會將code的含義放入message，所以如果code=200代表成功，則message放入“調用成功”，code=1001代表手機號不存在，則message放入“手機號不存在”。
ret：具體的返回報文，例如獲取文章信息，那麼文章信息應該防止在ret中。
二、接口樣式
拿個實例來說明，下面為登錄接口返回報文，則code=200代表登錄成功，result=true代表接口邏輯調用成功，message為code的中文描述，ret為具體點的接口信息。
{
"code": 200,
"result": true,
"message": "調用成功",
"ret": {
"id": 2401,
"real_name": null,
"nick_name": null,
"avatar": null,
"phonenum": null,
"gender": "0",
"status": "1",
"type": "0",
"token": "D0CD9D4AC37873787049BCCA5EF14CD5",
"country": null,
"province": null,
"city": null,
"language": null,
"level": 0,
"sign": null,
"yq_num": 0,
"rel_num": 0,
"created_at": "2018-11-19 18:58:22",
"updated_at": "2018-11-19 18:58:22",
"deleted_at": null,
"attach": {
"openid": "o_EXq0Ieo4TO8FTp29TRQQugWM8Q",
"session_key": "GiB4hk4mRQXks7OuxpTFEQ==",
"busi_name": "ysb",
"unionid": "oYnBVw2LNhaz2Tnn6I6a5tgt9vsE"
},
"bind_flag": true,
"new_flag": false
}
}
三、APIResponse的封裝
那麼有了接口規範，如何實施？此處給出推薦實施案例
//格式化返回
/*
* 返回數據包括
*
* result：代表接口調用的邏輯結果 true代表成功 false代表失敗
* code：錯誤碼，用於前端進行邏輯處理，特殊錯誤碼應與後端特殊定義，以便處理特殊邏輯
* message：錯誤返回信息，文字描述
* ret：返回值，具體業務返回結果
*
*/
//格式化返回
public static function makeResponse($result, $ret, $code, $mapping_function = null, $params = [])
{
$rsp = [];
$rsp['code'] = $code;
if ($result === true) {
$rsp['result'] = true;
$rsp['message'] = self::$returnMessage[$code];
$rsp['ret'] = $ret;
} else {
$rsp['result'] = false;
if ($ret) {
$rsp['message'] = $ret;
} else {
if (array_key_exists($code, self::$returnMessage)) {
$rsp['message'] = self::$returnMessage[$code];
} else {
$rsp['message'] = 'undefind error code';
}
}
$rsp['ret'] = $ret;
}
Utils::backLog(__METHOD__, $rsp);
return response()->json($rsp);
}
調用時為：
return ApiResponse::makeResponse(true, $ad, ApiResponse::SUCCESS_CODE);
維護錯誤碼：
/*
* 以下為錯誤碼錶，全部邏輯錯誤遵循該表
*
*
*/
//通用錯誤碼
const SUCCESS_CODE = 200; //成功
const MISSING_PARAM = 901; //缺少參數
const INNER_ERROR = 902; //邏輯錯誤
const UNKNOW_ERROR = 999; //未知錯誤
//token及用戶校驗錯誤
const TOKEN_ERROR = 101; //token校驗失敗
const USER_ID_LOST = 102; //用戶編碼丟失
const REGISTER_FAILED = 103; //註冊失敗
const NO_USER = 104; //未找到用戶
const VERTIFY_ERROR = 105; //驗證碼驗證失敗
const PHONENUM_DUP = 106; //手機號重複
const PHONENUM_ALREAD_REGISTED = 107; //手機號已經註冊過
四、小結
如果你管理一個技術團隊，那麼技術規範和技術管理工作應該是CTO的重點工作，我們希望達到的目標是在規範、標準庫、標準方法的支持下，整個團隊的開發效率、協同效率有提升。那麼技術管理工作，並不是單單技術問題，更深層次的講是“綜合治理問題”。最後，推薦大家文檔管理工具：
showdoc：免費的技術團隊文檔工具，支持多人協作，管理數據模型、接口文檔和項目相關信息比較通暢。
eolinker：接口管理工具，收費
閱讀更多 TerryQi 的文章
