后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载导读本文以 TypeGraphQL 官方发布公告website/blog/2020-08-19-devto-article.md为骨架系统拆解v1.0.0稳定版带来的五大核心变化性能开销削减、Schema 隔离机制、指令与扩展元数据、接口字段的 Resolver 与参数支持以及嵌套输入对象的递归实例化。读完本文你将掌握如何在真实项目中通过simpleResolvers与全局中间件配置控制执行开销、如何利用resolvers数组隔离出 public/private 多份 Schema、如何使用Directive与Extensions附加元数据以及为什么 1.0 之后嵌套输入和数组会被正确转换为对应的输入类型类实例。文中所有结论均可在当前仓库源码与基准测试中验证。背景两年旅程与 1.0 的定位TypeGraphQL 是一个基于 TypeScript 的 GraphQL 工具库核心理念是用类和装饰器同时声明 schema 与 resolver。它从 2018 年 1 月 31 日发布v0.1.0起步经历了 650 次提交、85 个合并 PR最终在v1.0.0迎来首个稳定版本。1.0 的重点并不只是补丁式的修修补补而是围绕性能、隔离性、Schema 表达能力、错误诊断、输入转换这五个维度的一次系统性升级。从当前仓库的 package.json 与源码结构可以看到这个版本的技术栈依然建立在graphql-js之上见 src/utils/buildSchema.ts 中对GraphQLSchema的依赖因此 1.0 的全部优化本质上都是在抽象层的额外开销上做减法同时把元数据驱动建 schema的能力做得更精准。一、性能从 500% 开销到 17% 的基准剖析1.1 基准方法与裸金属 graphql-js 对比TypeGraphQL 是构建在graphql-js之上的抽象层。要衡量抽象层本身的成本最直接的方法就是拿同一份数据与查询分别用 TypeGraphQL 和直接使用graphql-js执行并对比耗时。仓库中的 benchmarks/array 与 benchmarks/simple 目录正是为这个目的设计的。以数组基准为例benchmarks/array/run.ts 定义了ARRAY_ITEMS 2500025,000 个嵌套对象条目与BENCHMARK_ITERATIONS 5050 次迭代对每个 schema 执行同一份multipleNestedObjects查询并断言结果长度与嵌套字段值最终输出整体耗时。benchmarks/array/results.txt 记录了某台机器Core i7 2700K 3.5GHz、Node.js v13.5上的真实测量数据。1.2 官方发布公告中的关键数据发布公告给出了优化前后的两组对比旧版v0.17在返回 25,000 个嵌套对象的最苛刻场景下耗时约为graphql-js的5 倍libraryexecution timeTypeGraphQLv0.171253.28 msgraphql-js265.52 ms通过剖析定位根因其中一条是无条件走异步执行路径后v1.0.0的开销从 500% 降到17%启用simpleResolvers后进一步降到13%execution timegraphql-js265.52 msTypeGraphQLv1.0310.36 mswith simpleResolvers299.61 mswith a global middleware1267.82 ms注意最后一行挂载全局中间件时执行时间会反弹到 1267.82 ms这说明中间件链是执行路径上不可忽视的固定成本也是 1.0 引入按需精简路径simple resolvers的动机之一。1.3 仓库中的实测佐证benchmarks/array/results.txt 记录了同类的相对趋势25,000 条 × 50 次迭代单位秒TypeGraphQL standard15.518ssync field resolvers18.180sasync field resolvers39.934sgetters31.207sstandard with global middleware62.664s约为无中间件路径的 4 倍simpleResolvers: true14.980s接近乃至快于 graphql-js standard 的 13.276s 同量级graphql-js standard13.276s两条数据线共同指向一个结论resolver 的异步化与全局中间件是主要开销来源而simpleResolvers是绕过这些固定成本的有效手段。1.4 如何在代码中开启这些优化simpleResolvers是buildSchema选项之一。从 src/utils/buildSchema.ts 可以看到BuildSchemaOptions是SchemaGeneratorOptions的子集simple选项最终会作用于字段 resolver 的元数据收集见 src/decorators/Field.ts 中FieldOptions.simple的注释Set totrueto disable auth and all middlewares stack for this field resolver。也就是说simple的实际语义是跳过该字段的鉴权与中间件栈从而削减每个字段解析的固定开销import { buildSchema } from type-graphql; const schema await buildSchema({ resolvers: [RecipeResolver], // 全局开启 simple resolvers跳过 auth 与中间件栈以换取更低开销 simpleResolvers: true, });也可以对单个字段精准开启ObjectType() class Recipe { Field({ simple: true }) averageRating: number; }适用前提simple只适合那些不依赖鉴权和中间件处理的字段一旦某个字段需要权限校验或中间件变换就不应开启。仓库的 docs/performance.md 对复杂场景下的更多调优手段有专门说明。二、Schema 隔离用 resolvers 数组切分 public/private Schema2.1 旧版的泄漏问题在0.17.x及更早版本中buildSchema每次都会基于元数据存储metadata storage中累积的全部类型与 resolver生成 schema。后果是无论你传什么样的resolvers数组只要之前有其他模块注册过类型schema 就会泄漏——每次都包含所有能被找到的类型和操作。2.2 1.0 的隔离机制1.0 起schema 构建只从resolvers选项指定的 resolver 集合出发仅发射与这些 resolver 相关的 query、mutation 与类型const firstSchema await buildSchema({ resolvers: [FirstResolver], }); const secondSchema await buildSchema({ resolvers: [SecondResolver], });只需修改resolvers选项就能在同一份代码库上得到操作集合不同的多份 GraphQL Schema典型场景是把 schema 拆成对外的 public schema 与内部的 private schema。从源码实现看这并非只是文档层面的承诺src/utils/buildSchema.ts 的loadResolvers会显式校验resolvers非空空数组直接抛错随后把resolvers交给SchemaGenerator.generateFromMetadata生成 schema生成逻辑位于 src/schema/schema-generator.ts它围绕 resolver 元数据展开类型收集而非全量扫描元数据存储。2.3 对 serverless 的意义公告特别指出正确的隔离让 serverless 开发更顺畅因为它消除了多 schema 叠加产生的Schema must contain uniquely named types一类冲突错误。每个 serverless 实例各自buildSchema时只携带自己需要的类型定义互不干扰。三、指令Directives与扩展Extensions两种元数据方案1.0 同时带来了两套给 schema 元素附加元数据的能力它们互补而非互斥。3.1 Directive把 SDL 指令写进类GraphQL 指令是 SDLSchema Definition Language层的语法特性——一个以 开头的标识符。它除了承载元数据还能在 schema 构建期修改 schema例如为分页生成 connection 类型。在 SDL 中它长这样type Query { foobar: String! auth(requires: USER) }在 TypeGraphQL 中把Directive装饰器放在目标上、传入字符串即可Resolver() class FooBarResolver { Directive(auth(requires: USER)) Query() foobar(): string { return foobar; } }从 src/decorators/Directive.ts 的签名看Directive(sdl: string)实际返回的是一个通用装饰器当它作用于类、字段/方法或参数时会分别调用collectDirectiveClassMetadata、collectDirectiveFieldMetadata或collectDirectiveArgumentMetadata写入元数据存储最终由 schema generator 转换为 SDL 中的真实指令节点。3.2 ExtensionsJS 侧的元数据推荐方案与指令的 SDL 特性相对GraphQL extensions 是JS 方式的元数据也是官方推荐的、在应用自定义逻辑如权限角色、缓存策略标记时放置类型元数据的方式ObjectType() class Foo { Extensions({ roles: [Role.User] }) Field() bar: string; }读取时在 resolver 或中间件里通过GraphQLResolveInfo即可取回这份元数据export const ExtensionsMiddleware: MiddlewareFn async ({ info }, next) { const { extensions } info.parentType.getFields()[info.fieldName]; console.log(extensions?.roles); // 输出元数据 return next(); };实现上src/decorators/Extensions.ts 与Directive对称作用于字段时调用collectExtensionsFieldMetadata作用于类时调用collectExtensionsClassMetadata两者都先拒绝 symbol 属性键。元数据定义见 src/metadata/definitions/extensions-metadata.ts。完整的指令与扩展用法分别见 docs/directives.md 和 docs/extensions.md。四、接口字段的 Resolver 与参数补上 GraphQL 合规的最后一块拼图在 1.0 之前TypeGraphQL 无法为接口InterfaceType的字段提供 resolver 实现或声明参数这正是阻碍 1.0 发布的最后一块拼图。1.0 之后接口字段可以像ObjectType一样定义带参数的 resolverInterfaceType() abstract class IPerson { Field() avatar(Arg(size) size: number): string { return http://i.pravatar.cc/${size}; } }几个注意点抽象方法、继承等边缘场景存在少数例外详见 docs/interfaces.md 的 Resolvers and arguments 小节。结合源码看src/decorators/InterfaceType.ts 通过collectInterfaceMetadata注册接口元数据并支持implements与autoRegisterImplementations等选项src/decorators/Arg.ts 负责把参数元数据name、description、deprecationReason 等通过collectHandlerParamMetadata登记与ObjectType字段 resolver 走同一套参数收集管线src/decorators/Field.ts 中isResolverMethod判断基于design:returntype与descriptor.value的存在性决定该字段是否同时被登记为内部字段 resolvercollectFieldResolverMetadata这正是接口内联 resolver 得以生效的机制。五、更可读的错误信息从谜语到诊断书旧版本里Cannot determine GraphQL input type for users或笼统的Generating schema error这类信息让新手很难定位问题代码。1.0 重写了错误文案让报错同时说明原因与修复方向Unable to infer GraphQL type from TypeScript reflection system. You need to provide explicit type for argument named filter of getUsers of UserResolver class.Some errors occurred while generating GraphQL schema: Interface field IUser.accountBalance expects type String! but Student.accountBalance is of type Float仓库中的错误类与这两条消息一一对应src/errors/NoExplicitTypeError.ts当反射系统无法推断类型、需要显式提供类型时抛出消息会精确拼接出参数名argument named filter或参数下标、方法名与类名。src/errors/GeneratingSchemaError.ts聚合 schema 生成期收集到的全部GraphQLError逐条列出如接口字段类型不匹配并把详细错误暴露在details属性上供程序化检查。这类错误在仓库测试中也有覆盖例如 tests/functional/errors/metadata-polyfill.ts 围绕元数据缺失场景验证了错误抛出行为可作交叉印证。六、嵌套输入与数组的递归实例化6.1 旧版的行为缺陷在 1.0 之前输入类型InputType的实例化只发生在第一层。看这个例子InputType() class SampleInput { Field() sampleStringField: string; Field() nestedField: SomeNestedInput; } Resolver() class SampleResolver { Query() sampleQuery(Arg(input) input: SampleInput): boolean { return input.nestedField instanceof SomeNestedInput; } }旧版里input.nestedField只是一个普通Object而不是SomeNestedInput的实例。这带来一系列麻烦包括对输入与参数校验docs/validation.md的支持受限——校验库往往依赖类装饰器元数据拿到的是裸对象就无法执行类级校验规则。6.2 1.0 的转换管线1.0 起所有嵌套的参数与输入都会被正确转换为对应的输入类型类实例包括深层嵌套的数组src/resolvers/convert-args.ts 是核心实现convertArgToInstance/convertArgsToInstance在调用 resolver 前执行转换转换基于generateInstanceTransformationTree递归构建转换树树的每个节点带getFields会向上合并继承链上的输入字段支持覆盖扩展类型字段convertToInput对数组逐项递归value.map(it convertToInput(tree, it))对非数组则继续下钻嵌套字段最后统一经convertToType实例化目标类generatedTrees缓存Map保证同一输入类型只构建一次转换树避免重复计算对性能的影响。这也解释了公告中的表述all the nested args and inputs are properly transformed ... even including deeply nested arrays—— 现在input.nestedField instanceof SomeNestedInput会稳定返回true。七、1.0 之后项目现状与延伸阅读1.0 不是终点而是 TypeGraphQL 稳定化后的新起点。围绕本文主题仓库内还有大量可直接参考的一手资料性能benchmarks/array 下的standard.ts、simple-resolvers.ts、sync-field-resolvers.ts、async-field-resolvers.ts、sync-getters.ts、with-global-middleware.ts逐一对应上文提到的各条执行路径docs/performance.md 给出更复杂场景的调优建议Schema 构建src/utils/buildSchema.ts含buildSchemaSync与emitSchemaFile支持、src/utils/emitSchemaDefinitionFile.ts可将 schema 输出到schema.graphql指令与扩展docs/directives.md、docs/extensions.md以及示例 examples/extensions接口与继承docs/interfaces.md、docs/inheritance.md示例见 examples/interfaces-inheritance输入与校验docs/validation.md 与示例 examples/automatic-validation、examples/custom-validation快速上手docs/getting-started.md 与 examples/simple-usage。结语TypeGraphQL 1.0 用一次减法完成了稳定化性能上把抽象层开销从 500% 压到 17% 左右架构上引入按resolvers隔离的 schema 构建让 public/private 拆分与 serverless 部署成为可能功能上补齐了接口字段 resolver、嵌套输入递归实例化并把错误信息打磨成可执行的诊断指引。如果你正在评估或已经使用 TypeGraphQL1.0 的这五个变化点都值得对照上面的源码与基准数据逐条验证——它们是理解这个库内部工作原理的最佳入口。赞分享后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载相关推荐TypeGraphQL Resolver 完全指南用 TypeScript 类与方法定义 Query、Mutation 与字段解析器TypeGraphQL Resolver 完全指南用 TypeScript 类与方法定义 Query、Mutation 与字段解析器 TypeGraphQL后端GraphQLAPI设计TypeGraphQL字段解析缓存重复解析的性能优化TypeGraphQL字段解析缓存重复解析的性能优化 在GraphQL API开发中重复数据请求导致的性能问题是常见痛点。TypeGraphQL结合Apol后端GraphQLAPI设计TypeGraphQL接口字段实现检查确保接口一致性TypeGraphQL接口字段实现检查确保接口一致性 在GraphQL API开发中接口Interface作为定义类型契约的核心机制其字段实现的一致性后端GraphQLAPI设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考