如何以向后兼容方式在GraphQL中使用新增字段？

问题根源 #

Chilli Cream（Hot Chocolate）在查询解析阶段会严格校验所有显式声明的字段，即便字段带有@include(if: false)指令，服务器仍会先检查字段是否存在，这就是直接用@include仍报错的核心原因。

无需维护双查询的解决方案 #

方案1：内省判断+条件片段（纯客户端实现） #

核心思路是把新增字段放到GraphQL片段中，通过@include指令控制片段是否被应用——当片段未被引用时，服务器不会校验片段内的字段，自然不会触发「字段不存在」的错误。

步骤：

1. 先通过内省查询确认服务器是否支持目标字段，得到hasNewField布尔变量；
2. 在主查询中定义包含新增字段的片段，用@include(if: $hasNewField)控制片段的应用：

query FetchResource($hasNewField: Boolean!) {
  resource {
    id
    title
    # 原有字段
    ...NewFeatureFields @include(if: $hasNewField)
  }
}

fragment NewFeatureFields on Resource {
  newField # 新增的字段
}

当hasNewField为false时，片段不会被解析，服务器不会检查newField的存在性；为true时则正常返回该字段。

方案2：服务器端自定义@optional指令（需修改服务器） #

如果有权限修改Chilli Cream服务器代码，可以自定义一个@optional指令，让服务器遇到标记了该指令的字段时，若字段不存在则自动忽略，而非抛出错误。

1. 定义指令类型：

public class OptionalDirective : DirectiveType
{
    protected override void Configure(IDirectiveTypeDescriptor descriptor)
    {
        descriptor.Name("optional");
        descriptor.Location(DirectiveLocation.Field);
    }
}

2. 在Schema配置中注册指令，并添加字段校验逻辑：
   在Hot Chocolate的配置中，扩展字段解析的错误处理，当字段不存在且带有@optional指令时，跳过错误并返回null：

services.AddGraphQLServer()
    .AddDirectiveType<OptionalDirective>()
    .AddErrorFilter<OptionalFieldErrorFilter>();

// 自定义错误过滤器
public class OptionalFieldErrorFilter : IErrorFilter
{
    public IError OnError(IError error)
    {
        if (error.Code == "FIELD_NOT_FOUND" 
            && error.Path != null 
            && error.Extensions.TryGetValue("directives", out var directives)
            && directives is List<object> dirs 
            && dirs.Any(d => ((Dictionary<string, object>)d)["name"] == "optional"))
        {
            return error.Ignore();
        }
        return error;
    }
}

3. 客户端查询时直接在新增字段上标记@optional：

query FetchResource {
  resource {
    id
    title
    newField @optional
  }
}

无论服务器是否支持newField，都不会抛出错误——存在则返回字段值，不存在则忽略该字段。

内容的提问来源于stack exchange，提问作者Jan Hudec