typed-graphqlify 完全指南：在 TypeScript 中构建类型安全 GraphQL 查询，无需代码生成

typed-graphqlify 完全指南：在 TypeScript 中构建类型安全 GraphQL 查询，无需代码生成

【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlify

在 TypeScript 项目中写 GraphQL 查询时，你是否厌倦了手动维护查询字符串和接口类型之间的同步？typed-graphqlify 是一款优雅的开源工具，它让你用 GraphQL 风格的 JavaScript 对象直接定义查询，自动推导出完整的 TypeScript 类型，真正做到类型安全 GraphQL 查询无需代码生成。本指南将带你从零上手，掌握最快捷的配置方法与核心技巧。

typed-graphqlify 是什么？为何值得一试

typed-graphqlify 的核心思想很简单：只维护一份真相。你不必再为同一个查询同时编写 GraphQL 字符串和 TypeScript interface，而是通过类似 GraphQL 的嵌套对象一次性描述查询结构，库会自动帮你：

• 把对象渲染成合法的 GraphQL 查询字符串
• 根据对象结构推导出精确的 TypeScript 返回类型
• 让 IDE 自动补全、类型检查全程护航

如果你经历过"改了查询忘了改类型"导致的线上事故，这个库正是对症的良药。

传统方式的痛点：类型与查询容易脱节

在使用 Apollo 等客户端时，通常需要这样写：

interface GetUserQueryData { getUser: { id: number name: string } } const query = gql` query getUser { user { id name } } `

问题显而易见：查询与类型是两份独立代码，任何一边改动，另一边都可能悄然失联，而 TypeScript 无法帮你发现这种错误。typed-graphqlify 正是为解决这一冗余而生。

快速上手：3 步完成安装配置

第 1 步：安装依赖

npm install --save typed-graphqlify

使用 Yarn 的朋友可以执行：

yarn add typed-graphqlify

第 2 步：引入核心 API

第 3 步：定义第一个查询（见下文）

整个安装配置过程不到一分钟，无需生成器、无需额外配置文件。

核心用法：用对象构建类型安全 GraphQL 查询

以一个查询用户信息的例子来说明，用法和写普通对象一样直观：

import { query, types } from 'typed-graphqlify' const getUserQuery = query('GetUser', { user: { id: types.number, name: types.string, bankAccount: { id: types.number, branch: types.optional.string, }, }, })

这里的types助手用来标注字段的标量类型。调用toString()即可得到标准 GraphQL 字符串：

console.log(getUserQuery.toString()) // query GetUser { // user { // id // name // bankAccount { // id // branch // } // } // }

而最关键的一步——获取类型——只需要引用查询对象的data属性：

const data: typeof getUserQuery.data = await executeGraphql(getUserQuery.toString())

此时data已被自动推导为精确的嵌套类型，branch由于使用了types.optional.string会被识别为string | undefined，IDE 自动补全立即生效，如上图所示。

进阶技巧：可选字段、枚举与常量

• 可选字段：types.optional.string或optional({...})，让类型自动带上undefined
• 枚举字段：types.oneOf(['STUDENT', 'TEACHER'] as const)，返回精确的字面量联合类型
• 常量字段：types.constant('User')，适合__typename这类固定返回值
• 带参数查询：params({ format: rawString('d.m.Y') }, types.string)，rawString防止字符串被误渲染成枚举
• 字段别名：alias('maleUser', 'user')，轻松实现重命名
• Mutation：使用mutation函数，配合params传入内联参数

Fragment 复用：让查询更优雅

typed-graphqlify 同样支持标准 Fragment 和行内 Fragment：

import { fragment, on, query, types } from 'typed-graphqlify' const userFragment = fragment('userFragment', 'User', { id: types.number, name: types.string, })

行内片段使用on助手，处理接口联合类型（如 Droid / Human）时，还能用onUnion自动生成可辨识联合类型，配合kind字段做类型收窄，体验非常丝滑。

为什么不用 apollo codegen？

你可能好奇：既然有apollo client:codegen这类代码生成工具，为何还要手动写对象？几个关键差异：

• 简单直接：typed-graphqlify 核心逻辑极简，出问题容易排查修复，而代码生成工具往往庞大复杂
• 多 schema 场景：Apollo codegen 对多 schema 支持不佳，而 typed-graphqlify 天然无此困扰
• 无需 schema 也能工作：有些框架无法导出 schema，此时 typed-graphqlify 依然游刃有余
• 可编程构建：像 AWS 控制台那样动态拼接查询时，用对象构建显然更灵活

React Native 兼容性说明

如果你在 React Native 中使用，请注意该库依赖Symbol和Map，在 ES5 及更低目标环境下需要引入 polyfill：

import 'babel-polyfill'

总结

typed-graphqlify 用极小的学习成本，换来了"查询即类型"的清爽体验。无论是快速原型还是长期维护的大型项目，它都能帮你告别查询与类型脱节的噩梦，真正把类型安全 GraphQL 查询变成一件轻松的事。感兴趣的话，不妨从它的核心实现（src/graphqlify.ts、src/types.ts、src/render.ts）和示例代码（examples/index.ts）开始探索，相信你会喜欢这种简洁的设计。

【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlify