Webonyx GraphQL-PHP 中的 Schema 定义语言详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00521/article/details/148523691

Webonyx GraphQL-PHP 中的 Schema 定义语言详解

graphql-php PHP implementation of the GraphQL specification based on the reference implementation in JavaScript 项目地址: https://gitcode.com/gh_mirrors/gr/graphql-php

什么是 Schema 定义语言

Schema 定义语言（Schema Definition Language，简称 SDL）是 GraphQL 中用于定义 API 结构的专用语法。在 Webonyx GraphQL-PHP 项目中，SDL 提供了一种简洁明了的方式来描述你的 GraphQL 服务能够提供哪些数据类型和操作。

与直接在 PHP 代码中定义 Schema 相比，使用 SDL 有以下优势：

语法简洁直观，易于阅读和维护
支持 IDE 的自动补全和语法验证
可以将 Schema 定义与业务逻辑分离

基础 Schema 定义示例

一个典型的 SDL 文件（通常命名为 schema.graphql）可能如下所示：

type Query {
  greetings(input: HelloInput!): String!
}

input HelloInput {
  firstName: String!
  lastName: String
}

这个例子定义了一个简单的 GraphQL API：

有一个 Query 类型，包含 greetings 字段
greetings 字段接受 HelloInput 类型的输入参数
返回一个非空的字符串
HelloInput 类型有两个字段，firstName 是必填的，lastName 是可选的

从 SDL 创建可执行 Schema

在 Webonyx GraphQL-PHP 中，可以使用 BuildSchema 工具将 SDL 转换为可执行的 Schema 实例：

use GraphQL\Utils\BuildSchema;

$contents = file_get_contents('schema.graphql');
$schema = BuildSchema::build($contents);

需要注意的是，这样创建的 Schema 默认不包含任何解析器（resolver）。系统会依赖默认字段解析器和根值（root value）来执行查询。

添加解析器支持

为了支持更复杂的场景，如接口（Interfaces）、联合类型（Unions）和自定义字段解析器，可以向 BuildSchema::build() 方法传递第二个参数——一个可调用的类型配置装饰器（typeConfigDecorator）。

这个装饰器接收构建器生成的默认类型配置，并可以添加缺失的选项：

use GraphQL\Utils\BuildSchema;
use GraphQL\Language\AST\TypeDefinitionNode;

$typeConfigDecorator = function (array $typeConfig, TypeDefinitionNode $typeDefinitionNode): array {
    $name = $typeConfig['name'];
    // 根据类型名称 $name 向 $typeConfig 添加缺失的选项
    return $typeConfig;
};

$contents = file_get_contents('schema.graphql');
$schema = BuildSchema::build($contents, $typeConfigDecorator);

通过这种方式，你可以为接口类型添加 resolveType 解析器，或为对象类型添加 resolveField 解析器。

性能优化建议

BuildSchema::build() 方法会自动生成一个惰性加载（lazy schema）的 Schema，因此即使处理大型 Schema 也能保持高效。

然而，每次请求都解析 Schema 定义文件并不是最优的做法。在生产环境中，建议缓存 Schema 的中间解析表示：

use GraphQL\Language\Parser;
use GraphQL\Validator\DocumentValidator;
use GraphQL\Utils\BuildSchema;
use GraphQL\Utils\AST;

$cacheFilename = 'cached_schema.php';

if (!file_exists($cacheFilename)) {
    $document = Parser::parse(file_get_contents('./schema.graphql'));
    DocumentValidator::assertValidSDL($document);
    file_put_contents($cacheFilename, "<?php\nreturn " . var_export(AST::toArray($document), true) . ";\n");
} else {
    $document = AST::fromArray(require $cacheFilename); // fromArray() 也是惰性操作
}

$typeConfigDecorator = function () {};
$schema = BuildSchema::build($document, $typeConfigDecorator, ['assumeValidSDL' => true]);

这种缓存机制可以显著提高性能，特别是在生产环境中。