告别繁琐的API交互：如何使用Composer与woohoolabs/yang高效构建JSON:API客户端-composer-PHP中文网

告别繁琐的api交互：如何使用composer与woohoolabs/yang高效构建json:api客户端

可以通过一下地址学习composer：学习地址

实际问题：JSON:API交互的痛点

在处理一个需要与多个JSON:API后端服务集成的项目时，我遇到了以下几个主要困难：

请求构建的复杂性： JSON:API规范对请求的格式有严格要求，例如Content-Type头必须是application/vnd.api+json，查询参数（如fields、include、filter、sort、page）的格式也比较特殊。手动拼接这些参数不仅耗时，还容易出错，尤其是在需要动态调整请求内容时。
响应解析的繁琐： JSON:API的响应结构通常包含data、included、links、meta和errors等顶级成员，并且data内部可能是单个资源对象或资源对象集合，资源对象内部又包含attributes和relationships。手动遍历和解析这些深层嵌套的结构，以提取所需数据并将其映射到PHP对象，代码量巨大且难以维护。
规范合规性挑战： 确保每次请求和响应都完全符合JSON:API规范是一项挑战，任何微小的偏差都可能导致API拒绝请求或返回意想不到的结果。

这些问题导致我花费了大量时间在API的“管道”工作上，而不是聚焦于核心业务逻辑，开发效率大打折扣。

解决方案：`woohoolabs/yang`的登场

在一番探索之后，我发现了woohoolabs/yang。它是一个专为PHP开发者设计的JSON:API客户端框架，旨在简化与JSON:API服务器的通信过程。它严格遵循JSON:API 1.1规范，并提供了构建请求、发送请求、解析响应以及将响应数据映射到PHP对象的全套解决方案。

woohoolabs/yang的核心优势在于：

100% PSR-7 兼容性： 与现代PHP HTTP消息标准无缝集成。
高度符合JSON:API 1.1 规范： 自动处理规范中的各种细节，让你无需担心合规性问题。
强大的请求构建器： 提供流畅的API来构造复杂的JSON:API请求。
易于使用的HTTP客户端： 通过PSR-18和HTTPlug支持多种HTTP客户端。
开箱即用的数据水合器（Hydrator）： 轻松将API响应转换为可操作的PHP对象。

如何使用Composer安装与`woohoolabs/yang`

使用Composer安装woohoolabs/yang非常简单。由于它需要一个HTTP客户端实现，我们通常会先安装一个，例如Guzzle的适配器：

<pre class="brush:php;toolbar:false;"># 首先安装一个HTTP客户端实现，例如Guzzle 7的适配器
composer require php-http/guzzle7-adapter

# 然后安装woohoolabs/yang库
composer require woohoolabs/yang

登录后复制

简单两行命令，即可将这个强大的工具引入你的项目。

核心功能与实战：告别繁琐，拥抱优雅

让我们通过几个实际例子，看看woohoolabs/yang是如何解决我之前遇到的痛点的。

1. 轻松构建JSON:API请求 (Request Builder)

woohoolabs/yang提供了一个JsonApiRequestBuilder，它允许你以非常直观的方式构建JSON:API请求，包括设置URL、HTTP方法、查询参数（如fields、include、filter、sort、page）以及请求体。

<pre class="brush:php;toolbar:false;"><?php

require 'vendor/autoload.php';

use GuzzleHttp\Psr7\Request;
use WoohooLabs\Yang\JsonApi\Request\JsonApiRequestBuilder;
use WoohooLabs\Yang\JsonApi\Schema\Resource\ResourceObject;

// 1. 实例化一个空的PSR-7请求对象
$psr7Request = new Request('GET', '');

// 2. 实例化请求构建器
$requestBuilder = new JsonApiRequestBuilder($psr7Request);

// 3. 构建一个获取用户列表的请求
$requestBuilder
    ->setMethod('GET')
    ->setUri('https://api.example.com/users')
    ->setJsonApiFields([ // 稀疏字段集，只获取用户的first_name和last_name
        'users' => ['first_name', 'last_name'],
        'addresses' => ['city', 'country']
    ])
    ->setJsonApiIncludes([ // 包含相关资源，例如用户的地址
        'address'
    ])
    ->setJsonApiPage([ // 分页参数
        'number' => 1,
        'size' => 10
    ])
    ->setJsonApiFilter([ // 过滤参数
        'status' => 'active'
    ]);

// 4. 如果是POST/PATCH请求，可以设置请求体
// 例如，创建一个新用户
/*
$requestBuilder
    ->setMethod('POST')
    ->setUri('https://api.example.com/users')
    ->setJsonApiBody(
        new ResourceObject('users', null) // type为'users'，id为null表示创建
            ->setAttribute('first_name', 'John')
            ->setAttribute('last_name', 'Doe')
            ->setAttribute('email', 'john.doe@example.com')
    );
*/

// 5. 获取最终构建好的PSR-7请求对象
$jsonApiRequest = $requestBuilder->getRequest();

echo "构建的请求URI: " . $jsonApiRequest->getUri() . "\n";
echo "请求头 Content-Type: " . $jsonApiRequest->getHeaderLine('Content-Type') . "\n";
echo "请求头 Accept: " . $jsonApiRequest->getHeaderLine('Accept') . "\n";
// Output:
// 构建的请求URI: https://api.example.com/users?fields%5Busers%5D=first_name%2Clast_name&fields%5Baddresses%5D=city%2Ccountry&include=address&page%5Bnumber%5D=1&page%5Bsize%5D=10&filter%5Bstatus%5D=active
// 请求头 Content-Type: application/vnd.api+json
// 请求头 Accept: application/vnd.api+json

登录后复制

可以看到，复杂的查询参数和必要的HTTP头都由JsonApiRequestBuilder自动处理，极大地简化了请求构建过程。

2. 发送请求与处理响应 (HTTP Clients & Response)

woohoolabs/yang通过JsonApiClient和JsonApiAsyncClient封装了HTTP客户端，让你能够方便地发送同步或异步请求，并返回一个JsonApiResponse对象。

影像之匠PixPretty

商业级AI人像后期软件，专注于人像精修，色彩调节及批量图片编辑，支持Windows、Mac多平台使用。适用于写真、婚纱、旅拍、外景等批量修图场景。

299

查看详情

<pre class="brush:php;toolbar:false;"><?php

require 'vendor/autoload.php';

use GuzzleHttp\Psr7\Request;
use Http\Adapter\Guzzle7\Client as GuzzleClient;
use WoohooLabs\Yang\JsonApi\Client\JsonApiClient;
use WoohooLabs\Yang\JsonApi\Request\JsonApiRequestBuilder;

// 假设我们已经构建了一个请求（同上例）
$psr7Request = new Request('GET', '');
$requestBuilder = new JsonApiRequestBuilder($psr7Request);
$requestBuilder
    ->setMethod('GET')
    ->setUri('https://api.example.com/users')
    ->setJsonApiFields(['users' => ['first_name', 'last_name']]);
$jsonApiRequest = $requestBuilder->getRequest();

// 实例化Guzzle HTTP客户端
$guzzleHttpClient = GuzzleClient::createWithConfig([]);

// 实例化JSON:API客户端
$jsonApiClient = new JsonApiClient($guzzleHttpClient);

try {
    // 发送请求并获取JSON:API响应
    $jsonApiResponse = $jsonApiClient->sendRequest($jsonApiRequest);

    // 检查响应是否成功
    if ($jsonApiResponse->isSuccessful()) {
        echo "请求成功！\n";

        // 获取响应文档
        $document = $jsonApiResponse->document();

        // 检查文档是否有主数据
        if ($document->hasAnyPrimaryResources()) {
            // 如果是资源集合，获取所有主资源
            if ($document->isResourceCollectionDocument()) {
                echo "获取到用户列表：\n";
                foreach ($document->primaryResources() as $userResource) {
                    echo "  ID: " . $userResource->id() . ", ";
                    echo "  姓名: " . $userResource->attribute('first_name') . " " . $userResource->attribute('last_name') . "\n";
                }
            }
            // 如果是单个资源
            else if ($document->isSingleResourceDocument()) {
                $userResource = $document->primaryResource();
                echo "获取到单个用户：\n";
                echo "  ID: " . $userResource->id() . ", ";
                echo "  姓名: " . $userResource->attribute('first_name') . " " . $userResource->attribute('last_name') . "\n";
            }
        } else {
            echo "响应中没有主要数据。\n";
        }

        // 检查是否有包含的资源
        if ($document->hasAnyIncludedResources()) {
            echo "包含的资源：\n";
            foreach ($document->includedResources() as $includedResource) {
                echo "  Type: " . $includedResource->type() . ", ID: " . $includedResource->id() . "\n";
            }
        }

        // 检查是否有错误
        if ($document->hasErrors()) {
            echo "响应中包含错误：\n";
            foreach ($document->errors() as $error) {
                echo "  Title: " . $error->title() . ", Detail: " . $error->detail() . "\n";
            }
        }
    } else {
        echo "请求失败，HTTP状态码: " . $jsonApiResponse->getStatusCode() . "\n";
        if ($jsonApiResponse->hasDocument() && $jsonApiResponse->document()->hasErrors()) {
            echo "错误详情：\n";
            foreach ($jsonApiResponse->document()->errors() as $error) {
                echo "  Title: " . $error->title() . ", Detail: " . $error->detail() . "\n";
            }
        }
    }
} catch (Exception $e) {
    echo "发送请求时发生异常: " . $e->getMessage() . "\n";
}

登录后复制

通过JsonApiResponse，我们可以清晰地访问响应的各个部分，如主数据、包含资源、链接、元数据和错误，而无需手动解析JSON字符串。

3. 响应数据到PHP对象的自动化映射 (Hydration)

这是woohoolabs/yang最强大的功能之一，它解决了将复杂的JSON:API响应手动映射到PHP对象的痛点。ClassDocumentHydrator可以将响应文档自动转换为stdClass对象，其属性和关系会以直观的方式呈现。

假设我们有一个Dog资源，它有一个breed（品种）关系和一个owners（主人）关系，每个owner又有一个address关系。手动解析会非常复杂：

<pre class="brush:php;toolbar:false;">// 假设 $document 是一个包含Dog、Breed、Owner和Address的复杂响应文档
// 传统手动解析（简化版，实际更复杂）
/*
$dogResource = $document->primaryResource();
$dog = new stdClass();
$dog->name = $dogResource->attribute("name");
$dog->age = $dogResource->attribute("age");

$breedResource = $dogResource->relationship("breed")->resource();
$dog->breed = new stdClass();
$dog->breed->name = $breedResource->attribute("name");

foreach ($dogResource->relationship("owners")->resources() as $ownerResource) {
    $owner = new stdClass();
    $owner->name = $ownerResource->attribute("name");

    $addressResource = $ownerResource->relationship("address")->resource();
    $owner->address = new stdClass();
    $owner->address->city = $addressResource->attribute("city");
    $owner->address->addressLine = $addressResource->attribute("address_line");

    $dog->owners[] = $owner;
}
// ... 这样的代码会非常长
*/

登录后复制

现在，使用ClassDocumentHydrator：

<pre class="brush:php;toolbar:false;"><?php

require 'vendor/autoload.php';

use WoohooLabs\Yang\JsonApi\Hydrator\ClassDocumentHydrator;
use WoohooLabs\Yang\JsonApi\Response\JsonApiResponse;
use GuzzleHttp\Psr7\Response;

// 模拟一个复杂的JSON:API响应
$jsonResponseString = '{
    "data": {
        "type": "dogs",
        "id": "1",
        "attributes": {
            "name": "Buddy",
            "age": 5
        },
        "relationships": {
            "breed": {
                "data": { "type": "breeds", "id": "101" }
            },
            "owners": {
                "data": [
                    { "type": "people", "id": "201" },
                    { "type": "people", "id": "202" }
                ]
            }
        }
    },
    "included": [
        {
            "type": "breeds",
            "id": "101",
            "attributes": {
                "name": "Golden Retriever"
            }
        },
        {
            "type": "people",
            "id": "201",
            "attributes": {
                "name": "Alice"
            },
            "relationships": {
                "address": {
                    "data": { "type": "addresses", "id": "301" }
                }
            }
        },
        {
            "type": "people",
            "id": "202",
            "attributes": {
                "name": "Bob"
            },
            "relationships": {
                "address": {
                    "data": { "type": "addresses", "id": "302" }
                }
            }
        },
        {
            "type": "addresses",
            "id": "301",
            "attributes": {
                "city": "New York",
                "address_line": "123 Main St"
            }
        },
        {
            "type": "addresses",
            "id": "302",
            "attributes": {
                "city": "Los Angeles",
                "address_line": "456 Oak Ave"
            }
        }
    ]
}';

// 实例化一个PSR-7响应对象
$psr7Response = new Response(200, ['Content-Type' => 'application/vnd.api+json'], $jsonResponseString);
$jsonApiResponse = new JsonApiResponse($psr7Response);
$document = $jsonApiResponse->document();

// 实例化水合器
$hydrator = new ClassDocumentHydrator();

// 水合单个资源
if ($document->isSingleResourceDocument()) {
    $dog = $hydrator->hydrateSingleResource($document);

    echo "水合后的Dog对象：\n";
    echo "名称: " . $dog->name . "\n";
    echo "年龄: " . $dog->age . "\n";
    echo "品种: " . $dog->breed->name . "\n\n";

    echo "主人列表：\n";
    foreach ($dog->owners as $owner) {
        echo "  姓名: " . $owner->name . "\n";
        echo "  地址: " . $owner->address->city . ", " . $owner->address->address_line . "\n";
        echo "  ------------------\n";
    }
} else {
    echo "这不是一个单资源文档，无法进行水合。\n";
}

登录后复制

通过水合器，复杂的嵌套关系被自动映射为PHP对象的属性，你可以像访问普通PHP对象一样访问它们，代码变得极其简洁和易读。