mirror of https://gitee.com/hyperf/hyperf.git synced 2024-12-05 05:07:58 +08:00

* Add translate docs action

* Remove push

Co-authored-by: sy-records <sy-records@users.noreply.github.com>

2021-02-19 12:53:50 +08:00

23 KiB

Raw Blame History

API 資源構造器

支持返回 Grpc 響應的資源擴展

簡介

當構建 API 時，你往往需要一個轉換層來聯結你的 Model 模型和實際返回給用户的 JSON 響應。資源類能夠讓你以更直觀簡便的方式將模型和模型集合轉化成 JSON。

安裝

composer require hyperf/resource

生成資源

你可以使用 gen:resource 命令來生成一個資源類。默認情況下生成的資源都會被放置在應用程序的 app/Resource 文件夾下。資源繼承自 Hyperf\Resource\Json\JsonResource 類：

php bin/hyperf.php gen:resource User

資源集合

除了生成資源轉換單個模型外，你還可以生成資源集合用來轉換模型的集合。這允許你在響應中包含與給定資源相關的鏈接與其他元信息。

你需要在生成資源時添加 --collection 標誌以生成一個資源集合。或者，你也可以直接在資源的名稱中包含 Collection 表示應該生成一個資源集合。資源集合繼承自 Hyperf\Resource\Json\ResourceCollection 類：

php bin/hyperf.php gen:resource Users --collection

php bin/hyperf.php gen:resource UserCollection

gRPC 資源

需要額外安裝 hyperf/resource-grpc

composer require hyperf/resource-grpc

php bin/hyperf.php gen:resource User --grpc

gRPC 資源需要設置 message 類. 通過重寫該資源類的 expect() 方法來實現.

gRPC 服務返回時, 必須調用 toMessage(). 該方法會返回一個實例化的 message 類.

<?php
namespace HyperfTest\ResourceGrpc\Stubs\Resources;

use Hyperf\ResourceGrpc\GrpcResource;
use HyperfTest\ResourceGrpc\Stubs\Grpc\HiReply;

class HiReplyResource extends GrpcResource
{
    public function toArray(): array
    {
        return [
            'message' => $this->message,
            'user' => HiUserResource::make($this->user),
        ];
    }

    public function expect(): string
    {
        return HiReply::class;
    }
}

默認生成的資源集合, 可通過繼承 Hyperf\ResourceGrpc\GrpcResource 接口來使其支持 gRPC 返回.

概念綜述

這是對資源和資源集合的高度概述。強烈建議你閲讀本文檔的其他部分，以深入瞭解如何更好地自定義和使用資源。

在深入瞭解如何定製化編寫你的資源之前，讓我們先來看看在框架中如何使用資源。一個資源類表示一個單一模型需要被轉換成 JSON 格式。例如，現在我們有一個簡單的 User 資源類：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

每一個資源類都定義了一個 toArray 方法，在發送響應時它會返回應該被轉化成 JSON 的屬性數組。注意在這裏我們可以直接使用 $this 變量來訪問模型屬性。這是因為資源類將自動代理屬性和方法到底層模型以方便訪問。你可以在控制器中返回已定義的資源：

<?php

namespace App\Controller;

use App\Resource\User as UserResource;
use App\Model\User;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserResource(User::first()))->toResponse();
    }
}

資源集合

你可以在控制器中使用 collection 方法來創建資源實例，以返回多個資源的集合或分頁響應：


namespace App\Controller;

use App\Resource\User as UserResource;
use App\Model\User;

class IndexController extends AbstractController
{
    public function index()
    {
        return UserResource::collection(User::all())->toResponse();
    }
}

當然了，使用如上方法你將不能添加任何附加的元數據和集合一起返回。如果你需要自定義資源集合響應，你需要創建一個專用的資源來表示集合：

php bin/hyperf.php gen:resource UserCollection

你可以輕鬆的在已生成的資源集合類中定義任何你想在響應中返回的元數據：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray() :array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

你可以在控制器中返回已定義的資源集合：

<?php
namespace App\Controller;

use App\Model\User;
use App\Resource\UserCollection;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserCollection(User::all()))->toResponse();
    }
}

保護集合的鍵

當從路由返回資源集合時，將重置集合的鍵，使它們以簡單的數字順序。但是，可以將 preserveKeys 屬性添加到資源類中，指示是否應保留集合鍵：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * 指示是否應保留資源的集合鍵。
     *
     * @var bool
     */
    public $preserveKeys = true;

    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

當 preserveKeys 屬性被設置為 true，集合的鍵將會被保護：

<?php

namespace App\Controller;

use App\Model\User;
use App\Resource\User as UserResource;

class IndexController extends AbstractController
{
    public function index()
    {
        return UserResource::collection(User::all()->keyBy->id)->toResponse();
    }
}

自定義基礎資源類

通常，資源集合的 $this->collection 屬性會自動填充，結果是將集合的每個項映射到其單個資源類。假定單一資源類是集合的類名，但結尾沒有 Collection 字符串。

例如，UserCollection 將給定的用户實例映射到 User 資源中。若要自定義此行為，你可以重寫資源集合的 $collects 屬性：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * collects 屬性定義了資源類。
     *
     * @var string
     */
    public $collects = 'App\Resource\Member';

    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

編寫資源

如果你還沒有閲讀概念綜述，那麼在繼續閲讀本文檔前，強烈建議你去閲讀一下。

從本質上來説，資源的作用很簡單。它們只需要將一個給定的模型轉換成一個數組。所以每一個資源都包含一個 toArray 方法用來將你的模型屬性轉換成一個可以返回給用户的 API 友好數組：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
        ];
    }
}

你可以在控制器中返回已經定義的資源：

<?php

namespace App\Controller;

use App\Model\User;
use App\Resource\User as UserResource;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserResource(User::find(1)))->toResponse();
    }
}

關聯

如果你希望在響應中包含關聯資源，你只需要將它們添加到 toArray 方法返回的數組中。在下面這個例子裏，我們將使用 Post 資源的 collection 方法將用户的文章添加到資源響應中：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'posts' => PostResource::collection($this->posts),
        ];
    }
}

如果你只想在關聯已經加載時才添加關聯資源，請查看相關文檔。

資源集合

資源是將單個模型轉換成數組，而資源集合是將多個模型的集合轉換成數組。所有的資源都提供了一個 collection 方法來生成一個「臨時」資源集合，所以你沒有必要為每一個模型類型都編寫一個資源集合類：

<?php
namespace App\Controller;

use App\Resource\User as UserResource;
use App\Model\User;

class IndexController extends AbstractController
{
    public function index()
    {
        return UserResource::collection(User::all())->toResponse();
    }
}

要自定義返回集合的元數據，則仍需要定義一個資源集合：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

和單個資源一樣，你可以在控制器中直接返回資源集合：

<?php
namespace App\Controller;

use App\Model\User;
use App\Resource\UserCollection;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserCollection(User::all()))->toResponse();
    }
}

數據包裹

默認情況下，當資源響應被轉換成 JSON 時，頂層資源將會被包裹在 data 鍵中。因此一個典型的資源集合響應如下所示：


    {
        "data": [
            {
                "id": 1,
                "name": "Eladio Schroeder Sr.",
                "email": "therese28@example.com"
            },
            {
                "id": 2,
                "name": "Liliana Mayert",
                "email": "evandervort@example.com"
            }
        ]
    }

你可以使用資源基類的 withoutWrapping 方法來禁用頂層資源的包裹。

<?php
namespace App\Controller;

use App\Model\User;
use App\Resource\UserCollection;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserCollection(User::all()))->withoutWrapping()->toResponse();
    }
}

withoutWrapping 方法只會禁用頂層資源的包裹，不會刪除你手動添加到資源集合中的 data 鍵。而且只會在當前的資源或資源集合中生效，不影響全局。

包裹嵌套資源

你可以完全自由地決定資源關聯如何被包裹。如果你希望無論怎樣嵌套，都將所有資源集合包裹在 data 鍵中，那麼你需要為每個資源都定義一個資源集合類，並將返回的集合包裹在 data 鍵中。

當然，你可能會擔心這樣頂層資源將會被包裹在兩個 data 鍵中。請放心，組件將永遠不會讓你的資源被雙層包裹，因此你不必擔心被轉換的資源集合會被多重嵌套：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'data' => $this->collection,
        ];
    }
}

分頁

當在資源響應中返回分頁集合時，即使你調用了 withoutWrapping 方法，組件也會將你的資源數據包裹在 data 鍵中。這是因為分頁響應中總會有 meta 和 links 鍵包含着分頁狀態信息：


    {
        "data": [
            {
                "id": 1,
                "name": "Eladio Schroeder Sr.",
                "email": "therese28@example.com"
            },
            {
                "id": 2,
                "name": "Liliana Mayert",
                "email": "evandervort@example.com"
            }
        ],
        "links":{
            "first": "/pagination?page=1",
            "last": "/pagination?page=1",
            "prev": null,
            "next": null
        },
        "meta":{
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "path": "/pagination",
            "per_page": 15,
            "to": 10,
            "total": 10
        }
    }

你可以將分頁實例傳遞給資源的 collection 方法或者自定義的資源集合：

<?php

namespace App\Controller;

use App\Model\User;
use App\Resource\UserCollection;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserCollection(User::paginate()))->toResponse();
    }
}

分頁響應中總有 meta 和 links 鍵包含着分頁狀態信息：


    {
        "data": [
            {
                "id": 1,
                "name": "Eladio Schroeder Sr.",
                "email": "therese28@example.com"
            },
            {
                "id": 2,
                "name": "Liliana Mayert",
                "email": "evandervort@example.com"
            }
        ],
        "links":{
            "first": "/pagination?page=1",
            "last": "/pagination?page=1",
            "prev": null,
            "next": null
        },
        "meta":{
            "current_page": 1,
            "from": 1,
            "last_page": 1,
            "path": "/pagination",
            "per_page": 15,
            "to": 10,
            "total": 10
        }
    }

條件屬性

有些時候，你可能希望在給定條件滿足時添加屬性到資源響應裏。例如，你可能希望如果當前用户是「管理員」時添加某個值到資源響應中。在這種情況下組件提供了一些輔助方法來幫助你解決問題。 when 方法可以被用來有條件地向資源響應添加屬性：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'secret' => $this->when(Auth::user()->isAdmin(), 'secret-value'),
        ];
    }
}

在上面這個例子中，只有當 isAdmin 方法返回 true 時， secret 鍵才會最終在資源響應中被返回。如果該方法返回 false ，則 secret 鍵將會在資源響應被髮送給客户端之前被刪除。 when 方法可以使你避免使用條件語句拼接數組，轉而用更優雅的方式來編寫你的資源。

when 方法也接受閉包作為其第二個參數，只有在給定條件為 true 時，才從閉包中計算返回的值：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'secret' => $this->when(Auth::user()->isAdmin(), function () {
                return 'secret-value';
            }),
        ];
    }
}

有條件的合併數據

有些時候，你可能希望在給定條件滿足時添加多個屬性到資源響應裏。在這種情況下，你可以使用 mergeWhen 方法在給定的條件為 true 時將多個屬性添加到響應中：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            $this->mergeWhen(Auth::user()->isAdmin(), [
                'first-secret' => 'value',
                'second-secret' => 'value',
            ]),
        ];
    }
}

同理，如果給定的條件為 false 時，則這些屬性將會在資源響應被髮送給客户端之前被移除。

mergeWhen 方法不應該被使用在混合字符串和數字鍵的數組中。此外，它也不應該被使用在不按順序排列的數字鍵的數組中。

條件關聯

除了有條件地添加屬性之外，你還可以根據模型關聯是否已加載來有條件地在你的資源響應中包含關聯。這允許你在控制器中決定加載哪些模型關聯，這樣你的資源可以在模型關聯被加載後才添加它們。

這樣做可以避免在你的資源中出現「N+1」查詢問題。你應該使用 whenLoaded 方法來有條件的加載關聯。為了避免加載不必要的關聯，此方法接受關聯的名稱而不是關聯本身作為其參數：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'email' => $this->email,
            'posts' => PostResource::collection($this->whenLoaded('posts')),
        ];
    }
}

在上面這個例子中，如果關聯沒有被加載，則 posts 鍵將會在資源響應被髮送給客户端之前被刪除。

條件中間表信息

除了在你的資源響應中有條件地包含關聯外，你還可以使用 whenPivotLoaded 方法有條件地從多對多關聯的中間表中添加數據。 whenPivotLoaded 方法接受的第一個參數為中間表的名稱。第二個參數是一個閉包，它定義了在模型上如果中間表信息可用時要返回的值：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'expires_at' => $this->whenPivotLoaded('role_user', function () {
                return $this->pivot->expires_at;
            }),
        ];
    }
}

如果你的中間表使用的是 pivot 以外的訪問器，你可以使用 whenPivotLoadedAs方法：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\JsonResource;

class User extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'expires_at' => $this->whenPivotLoadedAs('subscription', 'role_user', function () {
                return $this->subscription->expires_at;
            }),
        ];
    }
}

添加元數據

一些 JSON API 標準需要你在資源和資源集合響應中添加元數據。這通常包括資源或相關資源的 links ，或一些關於資源本身的元數據。如果你需要返回有關資源的其他元數據，只需要將它們包含在 toArray 方法中即可。例如在轉換資源集合時你可能需要添加 links 信息：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }
}

當添加額外的元數據到你的資源中時，你不必擔心會覆蓋在返回分頁響應時自動添加的 links 或 meta 鍵。你添加的任何其他 links 會與分頁響應添加的 links 相合並。

頂層元數據

有時候你可能希望當資源被作為頂層資源返回時添加某些元數據到資源響應中。這通常包括整個響應的元信息。你可以在資源類中添加 with 方法來定義元數據。此方法應返回一個元數據數組，當資源被作為頂層資源渲染時，這個數組將會被包含在資源響應中：

<?php

namespace App\Resource;

use Hyperf\Resource\Json\ResourceCollection;

class UserCollection extends ResourceCollection
{
    /**
     * Transform the resource collection into an array.
     *
     * @return array
     */
    public function toArray(): array
    {
        return [
            'data' => $this->collection,
            'links' => [
                'self' => 'link-value',
            ],
        ];
    }

    public function with() : array
    {
        return [
            'meta' => [
                'key' => 'value',
            ],
        ];
    }
}

構造資源時添加元數據

你還可以在控制器中構造資源實例時添加頂層數據。所有資源都可以使用 additional 方法來接受應該被添加到資源響應中的數據數組：

<?php

namespace App\Controller;

use App\Model\User;
use App\Resource\UserCollection;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserCollection(User::all()->load('roles')))
            ->additional(['meta' => [
                'key' => 'value',
            ]])->toResponse();    
    }
}

響應資源

就像你知道的那樣，資源可以直接在控制器中被返回：

<?php

namespace App\Controller;

use App\Model\User;
use App\Resource\User as UserResource;

class IndexController extends AbstractController
{
    public function index()
    {
        return (new UserResource(User::find(1)))->toResponse();
    }

    public function info()
    {
        return new UserResource(User::find(1));
    }
}

如你想設置響應頭信息, 狀態碼等, 通過調用 toResponse() 方法獲取到響應對象進行設置.

23 KiB Raw Blame History

API 資源構造器

簡介

安裝

生成資源

資源集合

gRPC 資源

概念綜述

資源集合

保護集合的鍵

自定義基礎資源類

編寫資源

關聯

資源集合

數據包裹

包裹嵌套資源

分頁

條件屬性

有條件的合併數據

條件關聯

條件中間表信息

添加元數據

頂層元數據

構造資源時添加元數據

響應資源

23 KiB

Raw Blame History