在開發 rest api 時，實現 hateoas 是一個常見但復雜的任務。hateoas 通過在 api 響應中添加超媒體鏈接，幫助客戶端發現資源和操作，從而提高 api 的可發現性和用戶體驗。然而，在實際開發中，如何動態生成這些鏈接和嵌入資源，常常成為一個難題。
最近，我在開發一個用戶管理系統的 API 時，遇到了這個問題。我希望在返回用戶數據時，能夠自動生成指向用戶詳細信息、相關資源（如用戶的管理者）的鏈接，以及嵌入用戶的相關數據（如用戶的帖子列表）。手動編寫這些邏輯不僅繁瑣，而且容易出錯。
在嘗試了多種方法后，我發現了 willdurand/hateoas 庫。這個庫通過 composer 可以輕松安裝，并且提供了豐富的功能來簡化 HATEOAS 的實現。讓我們看看如何使用它來解決這個問題。
首先，通過 Composer 安裝 willdurand/hateoas 庫：
composer require willdurand/hateoas
安裝完成后，我們可以開始配置和使用這個庫。假設我們有一個 User 類，我們希望在其 API 響應中添加 self 鏈接和嵌入用戶的管理者信息。我們可以使用注解（Annotations）或屬性（Attributes，php 8.1 及以上版本）來配置這些關系。
對于 PHP 8.1 及以上版本，我們可以使用屬性來配置：
use JMSSerializerAnnotation as Serializer; use HateoasConfigurationAnnotation as Hateoas; #[SerializerxmlRoot('user')] #[HateoasRelation('self', href: "expr('/api/users/' ~ object.getId())")] #[HateoasRelation( 'manager', href: "expr('/api/users/' ~ object.getManager().getId())", embedded: "expr(object.getManager())", exclusion: new HateoasExclusion(excludeIf: "expr(object.getManager() === null)") )] class User { #[SerializerXmlAttribute] private $id; private $firstName; private $lastName; private $manager; public function getId() {} public function getManager() {} }
通過這種配置，Hateoas 庫會在序列化 User 對象時自動生成 self 鏈接和嵌入管理者信息。使用 HateoasBuilder 可以輕松構建和序列化這些對象：
use HateoasHateoasBuilder; $hateoas = HateoasBuilder::create()->build(); $user = new User(42, 'Adrien', 'Brault', new User(23, 'Will', 'Durand')); $json = $hateoas->serialize($user, 'json');
這樣，我們就得到了一個包含 HATEOAS 鏈接和嵌入資源的 JSON 響應：
{ "id": 42, "first_name": "Adrien", "last_name": "Brault", "_links": { "self": { "href": "/api/users/42" }, "manager": { "href": "/api/users/23" } }, "_embedded": { "manager": { "id": 23, "first_name": "Will", "last_name": "Durand", "_links": { "self": { "href": "/api/users/23" } } } } }
使用 willdurand/hateoas 庫帶來的優勢顯而易見：
- 簡化配置：通過注解或屬性，我們可以輕松配置鏈接和嵌入資源，無需手動編寫復雜的邏輯。
- 提高可維護性：配置集中在模型類中，易于管理和修改。
- 支持多種格式：Hateoas 支持 JSON 和 XML 格式，并且可以輕松擴展到其他格式。
- 動態生成：利用表達式語言，可以根據對象的狀態動態生成鏈接和嵌入資源。
在實際應用中，使用 willdurand/hateoas 庫大大簡化了我的 API 開發過程。API 響應變得更加豐富和易于使用，客戶端可以更容易地發現和操作資源。通過 Composer 安裝和使用這個庫，不僅解決了 HATEOAS 實現的復雜性問題，還提升了整個項目的開發效率和代碼質量。
