GraphQL-Request 项目中的 Raw 客户端优化思路

GraphQL-Request 是一个流行的 GraphQL 客户端库，最近社区对其 Raw 客户端的体验进行了深入讨论。本文将详细解析当前 Raw 客户端存在的问题以及提出的优化方案。

当前问题分析

现有的 Raw 客户端存在几个明显的体验问题：

1. 字符串和 DocumentNode 两种 API 分离，增加了学习成本
2. 用户需要自行选择字符串或 DocumentNode，而库内部其实可以更智能地处理
3. 类型推断实现困难，特别是变量与操作名称的类型关联
4. 整体使用体验不够直观和流畅

优化方案详解

模板字面量方案

建议引入了一种基于模板字面量的链式调用方式：

const data = await graffle
  .gql`
    query pokemonByName ($Name: String!) {
      pokemonByName (name: $Name) {
        name
        continent {
          name
        }
      }
    }
  `
  .run({
    name: `Pikachu`,
  })

这种设计将 GraphQL 查询与变量分离，使代码结构更清晰。同时支持显式指定操作名称：

.run(`pokemonByName`, {
  name: `Pikachu`,
})

类型安全增强

通过泛型参数，可以实现完整的类型安全：

const data = await graffle
  .gql<QueryPokemonByName>`
    query pokemonByName ($Name: String!) {
      pokemonByName (name: $Name) {
        name
        continent {
          name
        }
      }
    }
  `
  .run({
    name: `Pikachu`,
  })

其中 QueryPokemonByName 类型定义了查询结构和变量类型。

与现有 DocumentNode 兼容

优化方案完全兼容现有的 DocumentNode 使用方式：

const document = gql`
  query pokemonByName ($Name: String!) {
    pokemonByName (name: $Name) {
      name
      continent {
        name
      }
    }
  }
`

const data = await graffle
  .gql(document)
  .run({ name: `Pikachu` })

语法糖设计

建议还包含一个简化语法，特别适合简单查询：

const data = await graffle.query.gql`
  pokemonByName (name: ${`Pikachu`}) {
    name
    continent {
      name
    }
  }
`

这种设计将变量直接内联到查询中，进一步简化了代码。

技术优势总结

1. 统一了字符串和 DocumentNode 两种 API，降低学习曲线
2. 智能内部处理，用户无需关心性能优化细节
3. 改进的类型系统，使变量和结果类型更易于推断
4. 链式调用设计，IDE 支持更友好
5. 语法糖使简单查询更加简洁

这些改进将使 GraphQL-Request 的 Raw 客户端既保持灵活性，又提供更优秀的开发体验。