typed-graphqlify 2.x 到 3.x 迁移指南TypeScript 类型化 GraphQL 查询升级避坑完整手册【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlifytyped-graphqlify 是一个用 TypeScript 构建类型化 GraphQL 查询Typed GraphQL Queries的开源库其核心理念是无需代码生成让查询字符串与 TypeScript 类型推断始终保持单一事实来源。当你的项目从 2.x 升级到 3.x 时query、mutation、subscription的返回值会从普通字符串变为CompiledResult对象这是本次迁移的核心变化。本手册为你梳理完整的升级步骤与高频踩坑点帮你快速完成 typed-graphqlify 迁移。上图展示了 typed-graphqlify 在 3.x 中的典型工作方式定义查询对象后toString()生成 GraphQL 字符串.data提供完整的 TypeScript 类型推断编辑器自动补全清晰可见。一、为什么必须关注 3.x 的破坏性变更在 2.x 中query()直接返回 GraphQL 字符串类型要从原始queryObject推导const queryObject { user: { id: types.number, name: types.string, }, } const queryString query(GetUser, queryObject) // 2.x直接返回字符串 type Result typeof queryObject // 2.x从对象取类型而在 3.x 中返回的是一个包含toString、data、variable、result的CompiledResult对象定义见 src/graphqlify.tsinterface CompiledResultD, V { toString: () string // 生成 GraphQL 字符串 data: D // 查询结果的 TypeScript 类型 variable: V // 变量类型 result: { data: D } }这一设计让“字符串”与“类型”彻底解耦字符串靠.toString()类型靠.data。二、迁移前准备确认当前版本与依赖在动手前建议先完成两项检查确认当前版本在项目根目录执行npm ls typed-graphqlify或查看package.json中的依赖版本。了解升级跨度如果当前是 2.1.x 之前的版本还需要先处理 2.1.0 的变更如params取代__params、操作函数变为顶层导出。完整变更记录可参考 CHANGELOG.md。 提示3.1.6 已移除typescript作为 peer dependency升级后依赖树更轻冲突更少。三、三步完成核心迁移最快上手路径第 1 步修改查询构造代码将 2.x 写法中的“直接取字符串”改为“先构造对象再调用toString()”// 3.x 新写法 const q query(GetUser, { user: { id: types.number, name: types.string, }, }) const queryString q.toString() // 通过 toString() 获取 GraphQL 字符串 type Result typeof q.data // 通过 data 获取结果类型第 2 步替换类型来源全局搜索typeof queryObject或类似的类型断言统一改为typeof q.data。这一改动让类型与查询定义保持同步这正是 3.x 的核心收益。第 3 步执行请求处统一改法const data: typeof q.data await executeGraphql(q.toString())如果你的代码中大量使用query结果直接传给graphql()或gql记得补上.toString()这是最常见的漏改点。四、升级避坑清单这些坑 90% 的人都会踩 ⚠️坑 1忘记调用toString()query()不再返回字符串直接当作字符串拼接或传入请求库会得到[object Object]。建议在封装请求工具函数时统一处理。坑 2类型取错位置type Result typeof queryObject在 3.x 中不再成立必须使用typeof q.data。测试可参考 test-d/index.test-d.ts 中的expectType用法。坑 3React Native / ES5 环境缺少 polyfilltyped-graphqlify 内部依赖Symbol和MapReact Native 或 ES5 目标环境需要引入babel-polyfill等方案否则会直接运行报错。坑 4params中的null处理3.0.1 修复了params中null值的渲染问题如果你在参数里传过null升级后请回归验证生成的查询字符串是否正确。坑 5参数数组的写法3.1.0 起支持参数数组Parameter Arrays嵌套参数渲染更灵活。相关渲染逻辑可查看 src/render.ts。坑 6枚举类型推断陷阱types.oneOf优先使用数组as const或普通对象定义枚举官方明确不推荐使用 TypeScript 原生enum因为无法保证推断类型完全正确。坑 7空对象与直接类型会抛错query({})、字段直接写原始值如str: string都会在toString()时抛出异常相关校验逻辑与错误用例见 src/tests/errors.test.ts。五、迁移前后对照速查表 场景2.x 写法3.x 写法获取查询字符串query(GetUser, obj)query(GetUser, obj).toString()推导结果类型typeof queryObjecttypeof q.data请求调用execute(queryString)execute(q.toString())Mutation 参数mutation(..., obj)mutation(..., obj).toString()六、总结typed-graphqlify 3.x 的迁移本质只有一句话字符串交给toString()类型交给.data。按照本手册的三步流程走一遍再对照避坑清单逐一检查大多数项目半小时内即可完成升级。更多进阶用法fragment、inline fragment、onUnion、指令模拟等可查阅官方示例 examples/index.ts类型级测试覆盖可参考 test-d/index.test-d.ts。升级完成后你就能享受到“写一份查询、类型自动同步”的开发体验彻底告别手写 interface 与查询字符串的重复劳动 【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考