typed-graphqlify 可选字段与枚举实战optional 与 oneOf 的完整使用指南【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlifytyped-graphqlify 是一个无需代码生成即可在 TypeScript 中构建类型安全 GraphQL 查询的轻量级库。本文是面向新手的 typed-graphqlify 可选字段与枚举实战指南完整讲解 optional 与 oneOf 的使用方法。通过本文你将学会用types.optional标记可空字段、用types.oneOf定义枚举并把两者组合出优雅的类型安全查询——告别手写接口 手写查询字符串的双份维护痛苦。typed-graphqlify 是什么为什么值得一试传统 GraphQL 开发中使用 Apollo 等库时你需要同时维护 GraphQL 查询字符串和对应的 TypeScript 接口。新增一个字段就要改两处代码一旦忘记同步类型检查完全失效。typed-graphqlify 的核心思路是单一事实来源用类似 GraphQL 的 JS 对象一次性描述查询结构TypeScript 类型自动随之生成。安装只需一行命令npm install --save typed-graphqlify上图展示了它的典型工作流定义查询对象后返回结果的类型提示清晰可见可选字段branch被正确推断为string | undefined这就是 optional 带来的类型安全保障。可选字段详解types.optional 的完整使用方式GraphQL 返回的数据并不总是一定存在。比如用户的银行账户可能没有填写支行名称这时就需要 optional 把字段标记为可选。typed-graphqlify 提供了两种 optional 用法定义都集中在源码 types.ts 中。标量字段types.optional.string / number / boolean标记单个标量字段为可选直接在类型前加上optional即可import { query, types } from typed-graphqlify const getUserQuery query(getUser, { user: { id: types.number, name: types.optional.string, // 类型为 string | undefined isActive: types.optional.boolean, // 类型为 boolean | undefined }, })查询渲染结果与普通字段完全一致但在类型层面name和isActive会被推断为可空类型提醒你处理字段可能不存在的情况。嵌套对象optional() 辅助函数当整个嵌套对象都可能不存在时使用optional()函数包裹对象字面量import { optional, query, types } from typed-graphqlify query(getUser, { user: { id: types.number, bankAccount: optional({ id: types.number, branch: types.string, }), // 类型为 { id: number; branch: string } | undefined }, })可选自定义类型types.optional.custom对于服务端自定义标量同样支持 optional 版本例如日期、JSON 等特殊类型types.optional.custom{ lastLogin: string }()枚举实战types.oneOf 的三种定义方式GraphQL 中的枚举Enum表示字段只能取固定的几个值例如用户类型只能是STUDENT或TEACHER。typed-graphqlify 的types.oneOf接受数组、普通对象和 TypeScript enum 三种输入渲染时都会输出字段名类型则被收窄为联合类型。方式一as const 数组推荐使用as const断言让数组元素成为字面量类型这是类型推断最准确的方式import { query, types } from typed-graphqlify const userType [STUDENT, TEACHER] as const query(getUser, { user: { id: types.number, type: types.oneOf(userType), // 类型为 STUDENT | TEACHER }, })方式二普通对象当枚举值需要与键不同时可以使用普通对象映射const userType { STUDENT: student, TEACHER: teacher, } query(getUser, { user: { type: types.oneOf(userType), // 类型为 STUDENT | TEACHER }, })方式三TypeScript enum已弃用虽然官方文档曾支持直接传入 enum但官方明确标注已弃用typed-graphqlify 无法保证 enum 的推断类型完全正确。建议优先使用数组或普通对象。optional 与 oneOf 组合实战可选枚举字段实际业务中枚举字段也可能缺失是常见需求比如用户的性别可能未设置。将两者组合起来非常简单只需使用types.optional.oneOfimport { query, types } from typed-graphqlify const Gender [MALE, FEMALE, UNKNOWN] as const query(getUser, { user: { id: types.number, gender: types.optional.oneOf(Gender), // 类型为 MALE | FEMALE | UNKNOWN | undefined }, })对照测试用例见 src/tests/index.test.ts 中 render optional enums 一节可以看到渲染输出与普通枚举字段无异但 TypeScript 类型自动附加了undefined从根源上避免了访问不存在的枚举值这类运行时错误。5 分钟快速上手清单 ✅跟着下面的步骤你就能跑通第一个 typed-graphqlify 查询安装依赖执行npm install --save typed-graphqlify定义查询用query()包裹对象字段用types.number、types.string等描述标记可选字段标量用types.optional.string嵌套对象用optional({...})定义枚举字段用as const数组 types.oneOf(...)可选枚举用types.optional.oneOf(...)获取类型通过typeof getUserQuery.data直接获得结果类型无需手写接口发送请求调用getUserQuery.toString()得到 GraphQL 字符串交给任意请求库执行常见问题 FAQ Qoptional 会影响渲染出的 GraphQL 字符串吗A不会。types.optional和optional()仅在类型层面起作用渲染结果与普通字段一致这保证了查询字符串的干净简洁。Qtypes.optional 支持哪些类型A支持number、string、boolean、constant、oneOf、custom全部六种覆盖标量、常量和枚举场景。Q想给字段加参数怎么办A可选字段也可以与params结合使用参数定义与类型标注互不干扰具体可参考 graphqlify.ts 中的params说明。掌握 optional 与 oneOf你就掌握了 typed-graphqlify 类型安全的两个核心支柱。从现在开始把 GraphQL 查询的双份维护交给类型系统把精力留给真正的业务逻辑吧【免费下载链接】typed-graphqlifyBuild Typed GraphQL Queries in TypeScript without the code generation项目地址: https://gitcode.com/gh_mirrors/ty/typed-graphqlify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
