.jpg)
最近向 laravel 框架提交了一個 想法 — 在 PaginatedResourceResponse 中添加一個自定義分頁信息方法的檢測，以便在使用 Resource 類輸出信息時，能夠非常方便地自定義分頁信息。
為什么需要它
我基本上都是在開發(fā) API。早期時候我都是直接返回，但是這種方式有時候會出現(xiàn)一些問題，也不方便維護(hù)，加上經(jīng)常需要添加自定義字段和針對不同端給出不同數(shù)據(jù)的情況，我后來就一直在使用 Resource 來定義返回的數(shù)據(jù)。【推薦：laravel視頻教程】
使用 Resource 很方便也能夠讓邏輯清晰。但它有個不好的地方，那就是分頁信息太多了。針對 API 項(xiàng)目而言，大多數(shù)情況下，默認(rèn)輸出的分頁信息里很多字段并不需要，并且由于經(jīng)常對接的是一些老項(xiàng)目，需要沿用老的數(shù)據(jù)格式或者做兼容，分頁信息的字段大不相同，沒辦法直接使用默認(rèn)返回的分頁信息。
我不知道大家是怎么處理類似情況時的分頁信息的，但在此之前，為了能夠達(dá)到目的，我通常有兩種做法，一是自定義 Response，在這里面把數(shù)據(jù)信息進(jìn)行重新定義，二是將 Resource 相關(guān)的類全部自定義一遍。
我對 Laravel 底層并不是很了解，我也不擅長做抽象的框架開發(fā)，但是在經(jīng)歷這些之后，我發(fā)現(xiàn)事情能夠變得簡單很多，正如我在 PR 闡述的那樣，如果可以在 src/Illuminate/Http/Resources/Json/PaginatedResourceResponse.php 中組建分頁信息時，能夠使用其對應(yīng) Resource 類的組件分頁信息，那不就不需要每次大費(fèi)周章的進(jìn)行自定義很多類了嗎。于是我就提交了這個想法給 Laravel 框架。這個提交在一開始并沒有被直接接受，而是在經(jīng)過 Taylor 調(diào)整后被合并，并發(fā)布在 v8.73.2。
這是我第一次向 Laravel 貢獻(xiàn)代碼，也是第一次向這么大的代碼庫提交合并請求，雖然沒有被直接采用，但結(jié)果足以振奮人心。
使用示例
那么，我來簡單的示例一下如何使用吧。
默認(rèn)輸出
{ "data": [], "links": { "first": "http://cooman.cootab-v4.test/api/favicons?page=1", "last": "http://cooman.cootab-v4.test/api/favicons?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« 上一頁", "active": false }, { "url": "http://cooman.cootab-v4.test/api/favicons?page=1", "label": "1", "active": true }, { "url": null, "label": "下一頁 »", "active": false } ], "path": "http://cooman.cootab-v4.test/api/favicons", "per_page": 15, "to": 5, "total": 5 }}
這是 Laravel 默認(rèn)輸出的分頁信息，是不是很多字段，當(dāng)然這足夠應(yīng)對很多場景的使用。但有時候也會因此犯難。我們需要一點(diǎn)靈活。
使用 ResourceCollection 類時
我們先來看看底層邏輯吧！
當(dāng)在控制器返回一個 ResourceCollection 時，最終會調(diào)用其 toResponse 方法以響應(yīng)。那么可以直接找到該方法看看：
/** * Create an HTTP response that represents the object. * * @param IlluminateHttpRequest $request * @return IlluminateHttpJsonResponse */ public function toResponse($request) { if ($this->resource instanceof AbstractPaginator || $this->resource instanceof AbstractCursorPaginator) { return $this->preparePaginatedResponse($request); } return parent::toResponse($request); }
看到?jīng)]，如果當(dāng)前資源是個分頁對象時，它就把任務(wù)轉(zhuǎn)向處理分頁響應(yīng)了。接著看：
/** * Create a paginate-aware HTTP response. * * @param IlluminateHttpRequest $request * @return IlluminateHttpJsonResponse */ protected function preparePaginatedResponse($request) { if ($this->preserveAllQueryParameters) { $this->resource->appends($request->query()); } elseif (! is_null($this->queryParameters)) { $this->resource->appends($this->queryParameters); } return (new PaginatedResourceResponse($this))->toResponse($request); }
噢，它又轉(zhuǎn)給了 PaginatedResourceResponse ，這是我們最終需要修改的類，由于 toResponse 的內(nèi)容太長，就不在這里貼出，反正就是在這里開始組建響應(yīng)的數(shù)據(jù)，分頁信息當(dāng)然也是在這里面做的處理，不過它有個獨(dú)立的方法。該方法就是 paginationInformation, 這是在提交 PR 前的邏輯：
/** * Add the pagination information to the response. * * @param IlluminateHttpRequest $request * @return array */ protected function paginationInformation($request) { $paginated = $this->resource->resource->toArray(); return [ 'links' => $this->paginationLinks($paginated), 'meta' => $this->meta($paginated), ]; }
如果你細(xì)心的話，你應(yīng)該能夠想到，這里的 $this->resource 其實(shí)就是上面的 ResourceCollection 的實(shí)例，那么它的 resource 就是我們的列表數(shù)據(jù)，也就是分頁信息實(shí)例。既然如此，那我們?yōu)楹尾荒茉?ResourceCollection 中進(jìn)行分頁信息的處理呢？當(dāng)然可以，但我們需要加點(diǎn)東西，這就是我提交的想法。
合并 PR 之后，它的邏輯是這樣的：
/** * Add the pagination information to the response. * * @param IlluminateHttpRequest $request * @return array */ protected function paginationInformation($request) { $paginated = $this->resource->resource->toArray(); $default = [ 'links' => $this->paginationLinks($paginated), 'meta' => $this->meta($paginated), ]; if (method_exists($this->resource, 'paginationInformation')) { return $this->resource->paginationInformation($request, $paginated, $default); } return $default; }
很簡單的處理方式，如果對應(yīng)資源類中有自定義的分頁信息組建方法，那就使用它自己的，目前而言，這確實(shí)是個好想法。
于此，如何自定義分頁信息應(yīng)該很清晰了。那就是在自己相應(yīng)的 ResourceCollection 類中添加 paginationInformation 方法即可，比如：
public function paginationInformation($request, $paginated, $default): array { return [ 'page' => $paginated['current_page'], 'per_page' => $paginated['per_page'], 'total' => $paginated['total'], 'total_page' => $paginated['last_page'], ]; }
這是自定義后的數(shù)據(jù)輸出情況：
{ "data": [], "page": 1, "per_page": 15, "total": 5, "total_page": 1}
結(jié)果如我所愿。
使用 Resource 類時
我通常只喜歡定義一個 Resource 類來應(yīng)對單個對象和列表的情況，這里主要關(guān)注如何處理列表數(shù)據(jù)的分頁自定義。
在控制器中，我一般都是這樣使用：
public function Index(){ // .... return SomeResource::collection($paginatedData);}
再來看看 collection 方法里做了什么：
/** * Create a new anonymous resource collection. * * @param mixed $resource * @return IlluminateHttpResourcesJsonAnonymousResourceCollection */ public static function collection($resource) { return tap(new AnonymousResourceCollection($resource, static::class), function ($collection) { if (property_exists(static::class, 'preserveKeys')) { $collection->preserveKeys = (new static([]))->preserveKeys === true; } }); }
原來它把數(shù)據(jù)轉(zhuǎn)給了 ResourceCollection，那么只需要將這個 ?AnonymousResourceCollection 做個自定義不就可以了。
總結(jié)
這是一個很小優(yōu)化，但是很有用。
在此之前，如果想要隨著 Resource 返回自定義分頁信息，會比較麻煩，需要自定義很多東西，這樣的方式，對老用戶而言小菜一碟，但是對新手就可能是件棘手的問題。那么自此之后，無論是老用戶還是新手這件事將變得易如反掌。只需要在對應(yīng)的 ResourceCollection 類中添加 paginationInformation 方法，類似下面這樣：
public function paginationInformation($request, $paginated, $default): array { return [ 'page' => $paginated['current_page'], 'per_page' => $paginated['per_page'], 'total' => $paginated['total'], 'total_page' => $paginated['last_page'], ]; }
不過，如果你使用的是 Resource::collection($pageData) 方式，那么還需要額外自定義一個 ResourceCollection 類，并重寫對應(yīng) Resource 類的 collection 方法。
我通常會定義一個對應(yīng)的基類，然后其它的都繼承它。也可以做個 trait，然后共用。
最后
其實(shí)，這個想法我很早就想提交的，但是我一直比較猶豫，這到底是不是一個很大眾的需求。不過我最后想明白了，這樣做既然能為我節(jié)省大量重復(fù)且危險的工作，有那么多的開發(fā)者，總會有人需要的，所以我提交了，同時也是驗(yàn)證下我的想法到底是否可行，我的做法是否最優(yōu)，結(jié)果當(dāng)然是我學(xué)到了很多，比如寫稍微復(fù)雜的測試用例。
另外，我想知道大家有沒其它方法，或你們是怎么對待不同情況的分頁信息的。
最后的最后，你如果也有好的想法，那么盡快提交吧！? ? ? ? ??? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
.png)
