【RESTful】Yii2實作RESTful架構配置最佳實踐Yii2實作RESTful架構配置最佳實踐

在伺服器端，應用程式狀态和功能可以分為各種資源。資源是一個有趣的概念實體，它向用戶端公開。資源的例子有：應用程式對象、資料庫記錄、算法等等。每個資源都使用 URI (Universal Resource Identifier) 得到一個唯一的位址。所有資源都共享統一的接口，以便在用戶端和伺服器之間傳輸狀态。使用的是标準的 HTTP 方法，比如 GET、PUT、POST 和 DELETE。Hypermedia 是應用程式狀态的引擎，資源表示通過超連結互聯。

無狀态,分層,可擴充

首先,Yii2自帶了實作RESTful api的方式,但是,官方的例子過于簡單,把一個資源限定成了資料庫中的一個表,這顯然是和REST中定義的資源不相符的,并且實際的業務需求過于複雜,不能通過一個表進行資料的操作。

是以,我們采用了另一種方式,通過使用Yii2的不同元件,完成RESTful API的建構

REST要求定義資源,采用不同HTTP方式進行通路。

這裡用到了架構内部的路由

在項目的配置檔案<code>/config/web.php</code>,中,對不同資源進行路由設定,進而達到同一個URL用不同的通路方式來處理不同業務的目的。

這部分的設計,參考官方文檔對于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 支援的動詞

我們需要擷取用戶端傳遞過來的<code>GET</code>,<code>POST</code>,<code>Header</code>的資料,架構自帶了<code>Yii::$app-&gt;request</code>,可以直接得到用戶端傳過來的資料。

參考<code>\yii\web\Request|\yii\console\Request $request The request component. This property is read-only.</code>

這部分和一般的項目一樣,都用<code>/models</code>中的資料表對應的Model檔案,繼承了<code>\yii\db\ActiveRecord</code>的類,實作對資料表的CURD操作。

我們在處理資料之後,需要傳回給用戶端對應的資料,在REST的設計規則裡是這樣處理的

Body隻傳回主要的資料,比如使用者清單,使用者的詳細資料

Header傳回其他的資訊,包括頁碼資訊,身份校驗資訊

完全的使用HTTP狀态碼作為資源被請求狀态的傳回,比如404,403

HTTP狀态碼的說明如下

Code

HTTP Operation

Body Contents

Description

200

GET,PUT

資源

操作成功

201

POST

資源,中繼資料

對象建立成功

202

POST,PUT,DELETE,PATCH

N/A

請求已經被接受

204

DELETE,PUT,PATCH

操作已經執行成功，但是沒有傳回資料

301

GET

link

資源已被移除

303

重定向

304

資源沒有被修改

400

GET,PSOT,PUT,DELETE,PATCH

錯誤提示(消息)

參數清單錯誤(缺少，格式不比對)

401

未授權

403

通路受限，授權過期

404

資源，服務未找到

405

不允許的http方法

409

資源沖突，或者資源被鎖定

415

不支援的資料(媒體)類型

429

請求過多被限制

500

系統内部錯誤

501

接口未實作

格式化資料,我們的傳回資料的格式為JSON

通過不同的錯誤碼,傳回不同的HTTP狀态碼。

由于的非常頻繁的調用,是以對資料進行了封裝。

錯誤處理類<code>Error.php</code>

錯誤代碼檔案<code>ErrorCode.php</code>

調用錯誤資料傳回

有句話說得好,程式員不願意寫文檔,但是看到沒有文檔的項目又會抓狂。。。。

一個合格的API文檔應該包含下面幾項

概括說明

加密協定

資料類型

錯誤處理

接口文檔

參考資料

接口文檔告訴用戶端,調用什麼資料,怎麼掉,異常了咋辦。。。

簡單說明

通路位址

請求方式

傳回結果

傳回結果字段說明

錯誤代碼

更新記錄

RESTful API的好處在于更簡潔的規範了資料請求的方式,通過資源來設計資料接口,友善用戶端的調用,減少溝通成本。

不過協定畢竟隻是個建議,我們可以根據自己項目的實際情況,有選擇的滿足協定的需求,更好的為自己的項目服務。

:)

<a href="http://www.yiichina.com/doc/guide/2.0/rest-quick-start">http://www.yiichina.com/doc/guide/2.0/rest-quick-start</a>

<a href="http://ningandjiao.iteye.com/blog/1990004">http://ningandjiao.iteye.com/blog/1990004</a>

<a href="http://www.cnblogs.com/yuzhongwusan/p/3152526.html">http://www.cnblogs.com/yuzhongwusan/p/3152526.html</a>

<a href="https://zhuanlan.zhihu.com/p/20034107">https://zhuanlan.zhihu.com/p/20034107</a>

<a href="http://my.oschina.net/freegeek/blog/303639">http://my.oschina.net/freegeek/blog/303639</a>