PHP集成GraphQL连接Dutchie API的实现与报错排查

背景 #

在Dutchie.com运营店铺，需通过API密钥对接GraphQL协议的Dutchie API获取店铺商品数据，后续功能将嵌入WordPress页面。

已知对接参数 #

• 示例API密钥：public-eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJBUEktQ0xJRU5UIiwiZXhwIjozMzE4NjM5Mjc0NSwiaWF0IjoxNjI5NDgzOTQ1LCJpc3MiOiJodHRwczovL2R1dGNoY29tIiwianRpIjoiNGMtOTMyOC00MjhkLWEyYTMtOWQzMTc2ZTUwODY0IiwiZW50ZXJwcmlzZV9pZChLWExYTctNDM3OC05NWY4LTNlYzVzBiNSIsInV1aWQiOiI0M2ZlMjdkNy1iZWU2LTQxOTgtYWNhMi03N2Y5Y2I3MjI5MGIifQ.hCQWpcQ5uhKnZOSVQDA5SCMkx5kopC7H3upeU-1jMpg
• GraphQL Ping测试mutation示例：

mutation Ping {
  ping {
    id,
    time
  }
}

• API端点地址：https://plus.dutchie.com/plus/2021-07/graphql
• 请求头要求：必须携带Authorization字段，值格式为Bearer 替换为实际API密钥
• Ping接口预期返回参考：

原有代码报错原因 #

原有代码存在两个核心问题，导致触发Guzzle PSR7 MessageTrait相关报错：

1. 请求头格式错误：请求头数组的键值对未正确闭合引号，'Authorization => Bearer API Key here'是非法的数组元素，Guzzle无法解析为合法HTTP头
2. 测试残留代码：$results->getData()->pokemon是其他项目的测试残留字段，Dutchie接口不会返回该字段，运行到该行必然报错
   原有报错参考截图：

可运行对接代码 #

方案1：基于php-graphql-client库实现 #

先通过composer安装依赖：

composer require gmostafa/php-graphql-client

对接代码：

<?php
require __DIR__ . '/vendor/autoload.php';

use GraphQL\Client;
use GraphQL\Mutation;
use GraphQL\Exception\QueryError;

// 配置项
$apiKey = '替换为你的实际API密钥';
$endpoint = 'https://plus.dutchie.com/plus/2021-07/graphql';

// 初始化客户端，请求头使用正确键值格式
$client = new Client(
    $endpoint,
    [
        'Authorization' => 'Bearer ' . $apiKey,
        'Content-Type' => 'application/json'
    ]
);

// 构造Ping测试请求
$gql = (new Mutation('Ping'))
    ->setSelectionSet(['id', 'time']);

try {
    // 第二个参数传true直接返回格式化数组
    $results = $client->runQuery($gql, true);
    $response = $results->getData();
    echo "接口调用成功，返回数据：\n";
    print_r($response);
} catch (QueryError $e) {
    echo "GraphQL查询错误：\n";
    print_r($e->getErrorDetails());
} catch (\Exception $e) {
    echo "请求异常：" . $e->getMessage() . "\n";
}

方案2：原生CURL实现（无第三方依赖，适合WordPress嵌入） #

无需安装额外库，可直接写入WordPress主题函数文件：

<?php
function dutchie_api_request($query, $variables = []) {
    $apiKey = '替换为你的实际API密钥';
    $endpoint = 'https://plus.dutchie.com/plus/2021-07/graphql';
    
    $ch = curl_init($endpoint);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'query' => $query,
            'variables' => $variables
        ]),
        CURLOPT_TIMEOUT => 10,
    ]);

    $response = curl_exec($ch);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error) return new WP_Error('api_error', $error);
    return json_decode($response, true);
}

// 测试Ping调用
$pingQuery = <<<GQL
mutation Ping {
  ping { id time }
}
GQL;
$result = dutchie_api_request($pingQuery);
print_r($result);

WordPress嵌入注意事项 #

• 所有API请求必须在服务端执行，禁止把API密钥写入前端JS代码，避免密钥泄露
• 建议增加商品数据缓存逻辑，缓存周期设置为1-6小时，减少API请求频次，提升页面加载速度
• 前端获取数据通过WordPress原生AJAX接口实现，不要直接跨域调用Dutchie接口

内容的提问来源于stack exchange，提问作者Sumith Harshan