GraphQL-PHP 中自定义错误路径的实现与限制

理解 GraphQL 错误处理机制

在 GraphQL-PHP 中，错误处理是一个核心功能，它允许开发者清晰地传达执行过程中出现的问题。当查询执行失败时，GraphQL 会返回一个标准的错误响应格式，其中包含错误消息、位置信息以及错误路径等重要数据。

自定义错误类的实现

开发者经常需要创建自定义错误类来满足特定业务需求。一个常见的例子是创建 NotFoundError 类，用于表示资源未找到的错误情况。在 GraphQL-PHP 中，可以通过扩展基础的 Error 类并实现 ClientAware 接口来实现这一点。

class NotFoundError extends Error implements ClientAware {
    public function __construct(string $message, array $path) {
        parent::__construct(
            $message,
            null,
            null,
            null,
            $path,
            null,
            ['status_code' => 404]
        );
    }
    
    public function isClientSafe(): bool { 
        return true; 
    }
}

错误路径的特殊性

在 GraphQL 执行过程中，错误路径(path)是一个特殊属性。它表示错误在查询中的位置，通常由执行引擎自动确定。当错误发生时，GraphQL-PHP 会捕获错误发生时的执行路径，并将其作为错误响应的一部分返回给客户端。

自定义路径的限制

尽管 Error 类的构造函数允许传递路径参数，但在实际执行中，这个路径会被执行引擎覆盖。这是因为 GraphQL 规范要求错误路径必须准确反映错误在查询中的实际位置，而不是开发者指定的任意路径。这种设计确保了错误定位的一致性和准确性。

推荐的解决方案

如果需要传递额外的位置信息，建议使用扩展(extensions)机制。扩展允许开发者附加任意自定义数据到错误响应中，而不会干扰标准的错误处理流程。

class NotFoundError extends Error implements ClientAware, ProvidesExtensions {
    private array $customPath;
    
    public function __construct(string $message, array $customPath) {
        $this->customPath = $customPath;
        parent::__construct(
            $message,
            null,
            null,
            null,
            null,
            null,
            [
                'status_code' => 404,
                'custom_path' => $customPath
            ]
        );
    }
    
    public function isClientSafe(): bool { 
        return true; 
    }
    
    public function getExtensions(): array {
        return ['custom_path' => $this->customPath];
    }
}

最佳实践

1. 对于标准错误定位，依赖 GraphQL 自动生成的路径
2. 使用扩展传递额外的位置信息或元数据
3. 确保自定义错误实现 ClientAware 接口以标记为客户端安全错误
4. 考虑实现 ProvidesExtensions 接口来结构化扩展数据

通过遵循这些实践，开发者可以在保持 GraphQL 规范兼容性的同时，提供丰富的错误信息来改善 API 的可用性。