企业官网建设流程全解析

typed-graphqlify 快速上手：10分钟写出你的第一个类型化 GraphQL 查询

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

typed-graphqlify 是一款让你在 TypeScript 中无需代码生成即可构建类型化 GraphQL 查询的轻量级工具。对于正在寻找"TypeScript GraphQL 客户端最佳实践"的开发者来说，它把查询定义与类型定义合并为一份代码，彻底告别手工维护接口的痛点。本文将带你用 10 分钟完成从安装、编写到执行的完整流程，轻松掌握这门高效的 GraphQL 类型化开发技巧。

为什么需要 typed-graphqlify？

在传统写法里，使用 Apollo 等 GraphQL 客户端时，你需要同时维护两份代码：一份 GraphQL 查询字符串，一份对应的 TypeScript 接口。例如查询user时，既要写id、name、bankAccount的查询语句，又要手写一模一样的嵌套接口，任何字段增删都得同步修改两处，非常容易出错。

typed-graphqlify 的核心思想是单一事实来源：只写一次类 GraphQL 的 JS 对象，既能渲染成查询字符串，又能自动推导出返回值的 TypeScript 类型，从根源上消除重复代码。

如上图所示，当你在 VSCode 中悬停result.user，编辑器会立刻展示由 typed-graphqlify 自动推导出的完整嵌套类型（如branch?: string），这种"写查询即得类型"的开发体验正是它的最大魅力。

第一步：一键安装 typed-graphqlify

安装非常简单，在项目目录执行一条命令即可：

npm install --save typed-graphqlify

使用 Yarn 同样方便：

yarn add typed-graphqlify

安装完成后，你不需要配置任何插件、不需要修改 tsconfig，直接就能开始使用。如果你希望先查看完整的示例代码，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/ty/typed-graphqlify

第二步：用对象定义你的第一个类型化查询

引入核心 API 后，像写普通 JavaScript 对象一样定义查询。关键在于：字段的值使用types辅助类标注类型。

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类在 src/types.ts 中定义，提供了number、string、boolean等常用标量类型，以及optional、constant、oneOf、custom等进阶类型工具，足以覆盖绝大多数业务场景。

第三步：一行代码转成 GraphQL 字符串

定义好的查询对象自带toString()方法，调用它就能得到标准的 GraphQL 查询语句，直接交给任何客户端执行：

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

查询对象的渲染逻辑集中在 src/render.ts，支持嵌套对象、数组、参数、别名等复杂结构的完整渲染，细节可参考 examples/index.ts 中的实例。

第四步：获得 100% 类型安全的结果

这是最激动人心的一步。执行查询后，用typeof getUserQuery.data直接标注返回结果类型：

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

此时data的 TypeScript 类型会自动推导为：

// { // user: { // id: number // name: string // bankAccount: { // id: number // branch?: string // 可选项自动变成 string | undefined // } // } // }

字段是数组、可选还是枚举，类型系统都会精确感知。这意味着一旦写错字段名或类型，编译器立刻报错，把错误消灭在开发阶段而非线上。

第五步：掌握 4 个高频进阶技巧

1. 查询别名与参数 🎯

使用alias给字段起别名并携带参数：

import { alias, query, types } from 'typed-graphqlify' query('getUsers', { [alias('activeUsers', 'users(status: "active")')]: [{ id: types.number, name: types.string, }], })

2. 枚举字段 🔢

用types.oneOf把枚举约束进类型系统：

const userType = ['STUDENT', 'TEACHER'] as const query('getUser', { user: { id: types.number, type: types.oneOf(userType), // 类型为 'STUDENT' | 'TEACHER' }, })

3. Mutation 与内联参数 ⚡

mutation函数配合params与rawString可优雅处理带参数的操作：

import { mutation, params, rawString } from 'typed-graphqlify' mutation('updateUserMutation', { updateUser: params( { input: { name: rawString('Ben'), slug: rawString('/ben') } }, { id: types.number, name: types.string }, ), })

4. Fragment 复用 🧩

fragment让公共字段复用变得轻松：

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

与传统 codegen 方案相比的优势

很多团队使用 Apollo codegen 从 Schema 生成类型，但 typed-graphqlify 有几个独特优势：

• 零配置零依赖：不需要下载 Schema、不需要构建步骤，开箱即用
• 天然支持多 Schema：不存在同名类型冲突问题
• 支持动态编程式查询：运行时根据条件构建查询依然保有完整类型
• 代码量极小：整个库逻辑简单清晰，出问题易于排查修复

核心 API（query、mutation、alias、params、fragment）都定义在 src/graphqlify.ts 中，几十行代码即可通读全貌。

总结

通过这 10 分钟的学习，你已经掌握了 typed-graphqlify 构建类型化 GraphQL 查询的完整流程：安装、定义、渲染、执行、类型安全结果，以及别名、枚举、Mutation、Fragment 四大进阶技巧。它用一份代码同时解决查询编写与类型定义，让 TypeScript 与 GraphQL 的结合变得前所未有的顺滑。想深入了解更多用法，不妨查看测试文件 src/tests/index.test.ts 中的丰富示例，立刻动手试试吧！🚀

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