在服務器端，html' target='_blank'>應用程序狀態和功能可以分為各種資源。資源是一個有趣的概念實體，它向客戶端公開。資源的例子有：應用程序對象、數據庫記錄、算法等等。每個資源都使用 URI (Universal Resource Identifier) 得到一個唯一的地址。所有資源都共享統一的接口，以便在客戶端和服務器之間傳輸狀態。使用的是標準的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。Hypermedia 是應用程序狀態的引擎，資源表示通過超鏈接互聯。
無狀態,分層,可擴展
本文為原創博客,被收錄在我自己的GitHub項目中點我查看項目文件
首先,Yii2自帶了實現RESTful api的方式,但是,官方的例子過于簡單,把一個資源限定成了數據庫中的一個表,這顯然是和REST中定義的資源不相符的,并且實際的業務需求過于復雜,不能通過一個表進行數據的操作。
所以,我們采用了另一種方式,通過使用Yii2的不同組件,完成RESTful API的構建
REST要求定義資源,采用不同HTTP方式進行訪問。
這里用到了框架內部的路由
在項目的配置文件/config/web.php,中,對不同資源進行路由設置,從而達到同一個URL用不同的訪問方式來處理不同業務的目的。
//url配置對應規則 'urlManager' => [ 'enablePrettyUrl' => true, 'showScriptName' => false, 'rules' => [ //配置規則,實現RESTful的方式 'POST accounts'=>'account/login', // 登錄 'GET accounts'=>'account/get-avatar', //獲取頭像 'GET accounts/status'=>'account/status', //查詢登錄狀態 //獲取用戶組信息 'GET groups'=>'account/profile', //用戶申請加入用戶組的接口 'GET users/ask'=>'user/apply', //申請列表 'PUT users/<uid:d+>'=>'user/pass', //通過 'PATCH users/<uid:d+>'=>'user/nopass', //不通過 'GET users'=>'user/list', //通過的用戶列表 'DELETE users/<uid:d+>'=>'user/remove', //移除現有的用戶 'GET users/<uid:d+>'=>'user/info', //網紅的具體信息 'GET users/serach'=>'user/serach', //搜索當前用戶的用戶 //消息中心相關 'GET notices'=>'notice/list', //消息列表 'PUT notices/<nid:d+>'=>'notice/mark', //消息標記為已讀 'GET notices/status'=>'notice/status', //獲取消息的概要 ],
這部分的設計,參考官方文檔對于RESTful實現的部分
GET /users: 逐頁列出所有用戶 HEAD /users: 顯示用戶列表的概要信息 POST /users: 創建一個新用戶 GET /users/123: 返回用戶 123 的詳細信息 HEAD /users/123: 顯示用戶 123 的概述信息 PATCH /users/123 and PUT /users/123: 更新用戶123 DELETE /users/123: 刪除用戶123 OPTIONS /users: 顯示關于末端 /users 支持的動詞 OPTIONS /users/123: 顯示有關末端 /users/123 支持的動詞我們需要獲取客戶端傳遞過來的GET,POST,Header的數據,框架自帶了Yii::$app->request,可以直接得到客戶端傳過來的數據。
參考yiiwebRequest|yiiconsoleRequest $request The request component. This property is read-only.
這部分和一般的項目一樣,都用/models中的數據表對應的Model文件,繼承了yiidbActiveRecord的類,實現對數據表的CURD操作。
參考URL: http://www.yiichina.com/doc/guide/2.0/db-active-record
我們在處理數據之后,需要返回給客戶端對應的數據,在REST的設計規則里是這樣處理的
Body只返回主要的數據,比如用戶列表,用戶的詳細數據 Header返回其他的信息,包括頁碼信息,身份校驗信息 完全的使用HTTP狀態碼作為資源被請求狀態的返回,比如404,403HTTP狀態碼的說明如下
200 GET,PUT 資源 操作成功 201 POST 資源,元數據 對象創建成功 202 POST,PUT,DELETE,PATCH N/A 請求已經被接受 204 DELETE,PUT,PATCH N/A 操作已經執行成功，但是沒有返回數據 301 GET link 資源已被移除 303 GET link 重定向 304 GET N/A 資源沒有被修改 400 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 參數列表錯誤(缺少，格式不匹配) 401 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 未授權 403 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 訪問受限，授權過期 404 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 資源，服務未找到 405 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 不允許的http方法 409 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 資源沖突，或者資源被鎖定 415 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 不支持的數據(媒體)類型 429 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 請求過多被限制 500 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 系統內部錯誤 501 GET,PSOT,PUT,DELETE,PATCH 錯誤提示(消息) 接口未實現| Code | HTTP Operation | Body Contents | Description |
|---|---|---|---|
格式化數據,我們的返回數據的格式為JSON
$response= Yii::$app->response;$response->format = yiiwebResponse::FORMAT_JSON; //返回json
通過不同的錯誤碼,返回不同的HTTP狀態碼。
由于的非常頻繁的調用,所以對數據進行了封裝。
錯誤處理類Error.php
/** * 錯誤處理類 * * ------------------------------------ * * 錯誤處理擴展 seaslog * * http://www.oschina.net/news/50333/seaslog-0-21 * * http://neeke.github.io/SeasLog/ * * ------------------------------------ * * @author Calvin * @version 1.0 * @copyright (c) 2016, */namespace appcomponentserror;use Yii;class Error { /** * 公共的錯誤返回處理,通過傳入參數,返回對應的錯誤代碼,這里也定義了錯誤返回的格式,以及對日志的記錄 * * @param $error_code * @return array */ public static function errorJson($error_code) { $requests = Yii::$app->request; //返回值 $post = json_encode($requests->post()); $get = json_encode($requests->get()); $headers = json_encode($requests->getHeaders()->toArray()); //帶入記錄錯誤代碼的文件 $error_file = require_once Yii::$app->basePath . '/components/error/ErrorCode.php'; //獲取http狀態碼,以及文字說明 $error_info = $error_file['$error_code']; $http_code = $error_info['http_code']; $error_text = $error_info['remark']; $error_body = [ //設置返回的格式 'request' => $requests->getUrl(), 'method'=>$requests->getMethod(), 'error_code' => $error_code, 'error' =>$error_text, ]; $response = Yii::$app->response; $response->statusCode=$http_code; $response->format = yiiwebResponse::FORMAT_JSON; $headers = Yii::$app->response->headers; $headers->add('X-Halo-Result', 0);// $response->data = $error_body;// $userIP = $requests->userIP; //寫入日志// SeasLog::error('error === {error} && error_text === {error_text} && userIP === {userIP} && post === {post} && get === {get} && header === {header} ', [// '{error}' => $error,// '{error_text}' => $error_file['$error'],// '{post}' => $post,// '{get}' => $get,// '{userIP}' => $userIP,// '{header}' => $headers,// ], $request);// $appLog = Alibaba::AppLog();// $appLog->debug('debug-log-emssage');// $appLog->info('info-log-emssage');// $appLog->warn('warn-log-emssage');// $appLog->error('error-log-emssage'); return $error_body; }}
錯誤代碼文件ErrorCode.php
/** * 增加對不同類型的HTTP狀態碼的返回 * * 錯誤碼,HTTP狀態碼,返回值 */return [ '1001'=>[ 'http_code'=>403, 'remark'=>'Token驗證失敗', ], '1002'=>[ 'http_code'=>400, 'remark'=>'參數錯誤', ], '1003'=>[ 'http_code'=>400, 'remark'=>'參數不全', ], '2001'=>[ 'http_code'=>404, 'remark'=>'用戶不存在', ],];
調用錯誤數據返回
return Error::errorJson(1002);
有句話說得好,程序員不愿意寫文檔,但是看到沒有文檔的項目又會抓狂。。。。
一個合格的API文檔應該包含下面幾項
概括說明 加密協議 數據類型 錯誤處理 接口文檔 參考資料接口文檔告訴客戶端,調用什么數據,怎么掉,異常了咋辦。。。
簡單說明 訪問地址 請求方式 返回結果 返回結果字段說明 錯誤代碼 更新記錄RESTful API的好處在于更簡潔的規范了數據請求的方式,通過資源來設計數據接口,方便客戶端的調用,減少溝通成本。
不過協議畢竟只是個建議,我們可以根據自己項目的實際情況,有選擇的滿足協議的需求,更好的為自己的項目服務。
:)
鄭重聲明：本文版權歸原作者所有，轉載文章僅為傳播更多信息之目的，如作者信息標記有誤，請第一時間聯系我們修改或刪除，多謝。
新聞熱點
疑難解答
