yii2 restful web服務快速入門

jiufreeman發表於2020-04-07
RESTWeb

快速入門

Yii 提供了一整套用來簡化實現 RESTful 風格的 Web Service 服務的 API。 特別是，Yii 支援以下關於 RESTful 風格的 API：

  • 支援 Active Record 類的通用API的快速原型
  • 涉及的響應格式（在預設情況下支援 JSON 和 XML)
  • 支援可選輸出欄位的定製物件序列化
  • 適當的格式的資料採集和驗證錯誤
  • 支援 HATEOAS
  • 有適當HTTP動詞檢查的高效的路由
  • 內建OPTIONS和HEAD動詞的支援
  • 認證和授權
  • 資料快取和HTTP快取
  • 速率限制

如下， 我們用一個例子來說明如何用最少的編碼來建立一套RESTful風格的API。

假設你想通過 RESTful 風格的 API 來展示使用者資料。使用者資料被儲存在使用者DB表， 你已經建立了 [[yii\db\ActiveRecord|ActiveRecord]] 類 app\models\User 來訪問該使用者資料.

建立一個控制器

首先，建立一個控制器類 app\controllers\UserController 如下，

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

控制器類擴充套件自 [[yii\rest\ActiveController]]。通過指定 [[yii\rest\ActiveController::modelClass|modelClass]] 作為app\models\User， 控制器就能知道使用哪個模型去獲取和處理資料。

配置URL規則

然後，修改有關在應用程式配置的urlManager元件的配置：

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]

上面的配置主要是為user控制器增加一個 URL 規則。這樣， 使用者的資料就能通過美化的 URL 和有意義的 http 動詞進行訪問和操作。

嘗試

隨著以上所做的最小的努力，你已經完成了建立用於訪問使用者資料 的 RESTful 風格的 API。你所建立的 API 包括：

  • 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 支援的動詞

補充：Yii 將在末端使用的控制器的名稱自動變為複數。（譯註：個人感覺這裡應該變為注意）

你可以訪問你的API用curl命令如下，

$ curl -i -H "Accept:application/json" "http://localhost/users"

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
X-Powered-By: PHP/5.4.20
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

[
    {
        "id": 1,
        ...
    },
    {
        "id": 2,
        ...
    },
    ...
]

試著改變可接受的內容型別為application/xml，你會看到結果以 XML 格式返回：

$ curl -i -H "Accept:application/xml" "http://localhost/users"

HTTP/1.1 200 OK
Date: Sun, 02 Mar 2014 05:31:43 GMT
Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y
X-Powered-By: PHP/5.4.20
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <id>1</id>
        ...
    </item>
    <item>
        <id>2</id>
        ...
    </item>
    ...
</response>

技巧：你還可以通過 Web 瀏覽器中輸入 URL http://localhost/users 來訪問你的 API。 儘管如此，你可能需要一些瀏覽器外掛來傳送特定的 headers 請求。

如你所見，在 headers 響應，有關於總數，頁數的資訊，等等。 還有一些連結，讓你導航到其他頁面的資料。例如：http://localhost/users?page=2 會給你的使用者資料的下一個頁面。

使用 fields 和 expand 引數，你也可以指定哪些欄位應該包含在結果內。 例如：URL http://localhost/users?fields=id,email 將只返回 id 和 email 欄位。

補充：你可能已經注意到了 http://localhost/users 的結果包括一些敏感欄位， 例如 password_hash, auth_key 你肯定不希望這些出現在你的 API 結果中。 你應該在 響應格式 部分中過濾掉這些欄位。

總結

使用 Yii 框架的 RESTful 風格的 API, 在控制器的操作中實現API末端，使用 控制器來組織末端介面為一個單一的資源型別。

從 [[yii\base\Model]] 類擴充套件的資源被表示為資料模型。 如果你在使用（關係或非關係）資料庫，推薦你使用 [[yii\db\ActiveRecord|ActiveRecord]] 來表示資源。

你可以使用 [[yii\rest\UrlRule]] 簡化路由到你的 API 末端。

為了方便維護你的WEB前端和後端，建議你開發介面作為一個單獨的應用程式，雖然這不是必須的。

相關文章