实现Relay全局对象标识时GraphQL ID格式兼容问题排查

我正尝试为GraphQL查询添加Relay/全局对象标识功能，类型定义如下：

[Node]
public class Speaker
{
    [ID]
    public int Id { get; set; }

    public string? Name { get; set; }

    public string? Bio { get; set; }

    public virtual string? WebSite { get; set; }

    public ICollection<SessionSpeaker> SessionSpeakers { get; set; } = new List<SessionSpeaker>();
}

执行以下查询时：

query {
  node(id: 1) {
    id
    ... on Speaker {
      bio
      id
      name
      webSite
    }
  }
}

收到错误：

The argument literal representation is HotChocolate.Language.IntValueNode which is not compatible with the request literal type HotChocolate.Language.StringValueNode

将Id改为string类型后，执行查询：

query {
  node(id: "1") {
    id
    ... on Speaker {
      bio
      id
      name
      webSite
    }
  }
}

又收到错误：

Unable to decode the id string.

按照文档尝试传入类型名+ID的Base64编码值（"Speaker1"编码为"U3BlYWtlcjE="）：

query {
  node(id: "U3BlYWtlcjE=") {
    ... on Speaker {
      bio
      id
      name
      webSite
    }
  }
}

仍然报错：

Unable to decode the id string.

请问我哪里操作错误？应该传入何种格式的ID？另外，我的服务使用int作为ID，最佳实现方式是什么？

1. 错误根源 #

HotChocolate的Relay全局ID格式并非直接拼接类型名和原始ID，而是要求类型名与原始ID用冒号分隔后再做Base64编码。你之前用Speaker1拼接编码，解码后无法被框架识别为合法的全局ID结构，因此报错。

2. 正确的ID格式 #

生成合法全局ID的步骤：

• 拼接规则：{类型名}:{原始ID}，比如ID为1的Speaker，拼接后是Speaker:1
• 对该字符串做Base64编码，得到U3BlYWtlcjox
• 查询时传入这个编码值即可：

query {
  node(id: "U3BlYWtlcjox") {
    ... on Speaker {
      bio
      id
      name
      webSite
    }
  }
}

3. 基于int类型ID的最佳实现 #

无需修改实体类的Id类型，保持int即可：

• 实体类中Id字段保留int类型，[ID]特性会自动处理全局ID的编码和解码逻辑
• 确保服务已正确配置Relay支持，示例配置代码：

builder.Services.AddGraphQLServer()
    .AddQueryType<Query>()
    .AddMutationType<Mutation>()
    .AddRelaySupport() // 启用Relay全局ID支持
    .AddNode<Speaker>(); // 注册Speaker节点类型

• 查询返回id字段时，框架会自动返回编码后的全局ID；通过node查询时，框架会自动解码全局ID，提取原始int类型ID用于数据查询

额外注意 #

• 不要手动修改实体类的Id类型，[ID]特性负责在GraphQL层面完成int到全局ID字符串的转换
• 若自定义节点解析器，需确保正确处理全局ID的解码逻辑，从编码字符串中拆分出类型名和原始ID

内容的提问来源于stack exchange，提问作者V. A.