GQLPT：用自然语言驾驭 GraphQL 的 AI 查询生成器

从"手写查询"到"说话就行"

想象一下：你接手了一个复杂的 GraphQL API，文档老旧、字段繁多，光是弄清楚 User 类型下的嵌套字段就花了半小时。你只想查"所有年龄超过 25 岁的用户，他们的订单总额"，却要写出一段包含 query、variables、类型注解的完整 GraphQL 语句——稍不留神就会报 400 错误。

GQLPT 解决的就是这个问题：它把这段"翻译工作"交给了 AI，你只需要用自然语言描述想要的数据，剩下的查询构建、Schema 验证、重试机制全部自动完成。

---

项目背景：GraphQL 开发者的真实痛点

GraphQL 自 2015 年由 Facebook 开源以来，已经成为现代 Web API 的主流选择之一。然而它的灵活性也带来了门槛：客户端必须精确构造查询语句，任何字段名拼写错误或类型不匹配都会直接导致运行时错误。

Rocket Connect 团队在构建多个 GraphQL 后端项目时反复遇到同一个问题：开发者花费大量时间在"写对 GraphQL 查询"而非"实现业务逻辑"上。他们在 2023 年启动 GQLPT 项目，目标是做一个 TypeScript 优先的 AI 原生工具，让自然语言直接驱动 GraphQL 查询生成。

项目采用 MIT 许可证，由 Rocket Connect 团队持续维护（当前版本 0.0.0-alpha.33），已通过 npm 发布为核心包 @gqlpt/gqlpt。

---

核心功能：Adapter 模式下的多 AI 支持

GQLPT 的架构设计非常清晰：核心库 gqlpt 负责查询生成逻辑，通过 Adapter 模式 解耦具体的 AI 模型调用层。当前官方支持两种 Adapter：

Adapter	模型	安装包
@gqlpt/adapter-openai	GPT-4o / GPT-4 / GPT-3.5	npm
@gqlpt/adapter-anthropic	Claude 3.5 / Claude 3	npm

用户还可以基于 @gqlpt/adapter-base 自行实现其他 AI 模型的 Adapter（如 Google Gemini、本地 Ollama 等），体现了良好的 里氏替换原则。

核心工作流程如下：

1. Schema 内省：GQLPT 自动读取目标 GraphQL Schema（支持本地 Schema 字符串或远程端点 introspection）
2. Prompt 构建：将自然语言查询 + Schema 信息组合为结构化 Prompt
3. AI 生成：调用 Adapter 中的 LLM 生成 GraphQL 查询语句
4. Schema 验证：生成的查询在执行前必须通过 Schema 验证
5. 自动重试：验证失败时，错误信息会反馈给 AI 并自动重新生成（最多 3 次）

代码示例（演示用自然语言生成查询）：

import { AdapterOpenAI } from "@gqlpt/adapter-openai";
import { GQLPTClient } from "gqlpt";

const client = new GQLPTClient({
  typeDefs: `type User { id: ID! name: String! }`,
  adapter: new AdapterOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
});

const response = await client.generateQueryAndVariables("Find user by id 1");
// 返回: query字段 和 variables字段

---

技术架构：pnpm Monorepo 的工程化实践

GQLPT 采用 pnpm workspaces + Turborepo 构建 monorepo 项目，目录结构如下：

• packages/gqlpt — 核心库（查询生成逻辑）
• packages/adapter-openai — OpenAI 模型适配器
• packages/adapter-anthropic — Anthropic 模型适配器
• packages/adapter-base — 适配器基类（接口定义）
• packages/cli — 命令行工具（TypeScript 类型生成）
• packages/utils — 共享工具函数
• apps/backend — Express.js 后端服务（提供远程调用 API）
• apps/docs — Docusaurus 文档站点（gqlpt.dev）

技术栈选择非常现代：TypeScript 全链路、强类型保证、Jest 测试框架、Tailwind CSS + Docusaurus 文档站点。值得关注的是没有包含 Dockerfile，这意味着该项目定位为 npm 包 + CLI 工具，而非需要容器化部署的独立服务。

---

使用门槛：零配置到完全自定义

入门级（推荐）：安装 npm 包，几行代码即可调用：

npm install gqlpt @gqlpt/adapter-openai

进阶级：使用 CLI 工具从命令行直接生成类型安全的查询代码。

高级用法：

• 连接远程 GraphQL 端点进行 Schema introspection
• 支持 GraphQL Federation / Apollo Supergraph（多子图场景）
• 自定义 Prompt 模板和重试策略
• 通过 apps/backend 部署独立的 HTTP 服务

完全不支持：无 Web 界面（无 Docker 支持，无法一键部署），需要一定的 TypeScript/Node.js 基础。

---

局限与争议

1. 依赖外部 AI API：必须拥有 OpenAI 或 Anthropic API Key，成本由使用者承担
2. Alpha 版本风险：当前版本号 0.0.0-alpha.33，生产环境使用需谨慎评估
3. 无法保证查询正确性：AI 生成的查询虽经 Schema 验证，但业务逻辑正确性仍需人工确认
4. 不处理认证上下文：无法自动携带 GraphQL 端点的认证 Token（如 Authorization Header）

---

行业意义：AI + API 开发工具的新趋势

GQLPT 属于 AI-Augmented Developer Tools 范畴，同赛道的明星项目还包括 GitHub Copilot、Cursor IDE、Text-to-SQL 等。其差异化在于专注于 GraphQL 查询生成 这一细分场景，并通过 Adapter 模式保持对多 AI 模型的开放性。

随着 GraphQL 在微服务架构中的普及（Apollo Federation、AWS AppSync 等），GraphQL 查询编写的效率问题将越来越突出。GQLPT 的出现填补了"AI + GraphQL"工具链的一个空白，未来可期。

---

快速体验：npm install -g gqlpt && npm install @gqlpt/adapter-openai，配合你的 GraphQL Schema 即可开始使用。