后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载导读TypeGraphQLtype-graphql允许开发者用 TypeScript 的类class与装饰器decorator声明式地创建 GraphQL Schema 与 Resolver。官方仓库在examples/目录下维护了一系列短小精悍的示例覆盖从字段、基础类型、Resolver 到枚举、联合、订阅、依赖注入、鉴权、校验、泛型类型乃至 TypeORM、Typegoose、Apollo 等第三方生态集成。本文以版本 0.17.4 的 Examples 文档 为主线逐一拆解每个示例的技术要点并结合仓库源码给出可直接复制运行的配置与实现细节帮助读者快速定位自己需要的场景、理解 TypeGraphQL 各特性背后的实际调用方式。示例总览与文件约定所有示例都存放在 examples/ 目录下每个示例目录均包含完整的index.ts启动入口、*.resolver.ts/*.type.ts等源码文件以及一份examples.gql文件里面预置了可直接执行的查询Query、变更Mutation与订阅Subscription语句方便在 GraphQL Playground 或客户端中逐条验证效果。官方文档将它们分为四个层级基础Basics、进阶Advanced、特性用法Features usage与第三方库集成3rd party libs integration。其中与第三方库集成相关的两个示例需要注意前置条件TypeORM 示例需要编辑其index.ts填入本地数据库的凭据Apollo EngineApollo Cache Control示例则需要提供APOLLO_ENGINE_API_KEY环境变量对应当前仓库中的 apollo-cache 示例。基础篇字段、基础类型与 Resolversimple-usagesimple-usage 是最完整也最推荐优先阅读的入门示例它把 TypeGraphQL 的核心概念浓缩在一个“食谱Recipe”业务模型中。启动入口与 Schema 生成示例的 index.ts 展示了标准的三步流程引入reflect-metadataTypeGraphQL 依赖反射元数据驱动 Schema 生成必须放在最前面调用buildSchema({ resolvers: [RecipeResolver], emitSchemaFile: ... })构建可执行的 GraphQL Schema其中emitSchemaFile会把生成的 SDL 写入指定路径将 schema 交给ApolloServer并调用startStandaloneServer在 4000 端口启动服务。这里buildSchema的resolvers数组是必填核心配置emitSchemaFile则是调试利器——生成的 schema.graphql 文件让开发者能直观核对 TypeGraphQL 根据装饰器推导出的类型定义。用类与装饰器定义 ObjectTyperecipe.type.ts 展示了ObjectType的完整能力Field()标注普通字段如title: string、creationDate: DateGraphQL 侧被映射为DateTimeISO标量Field(_type [Int])声明数组类型字段ratings: number[]对应 SDL 中的[Int!]!Field({ nullable: true, description: ... })控制可空性与字段描述Field({ deprecationReason: Use description field instead })输出deprecated指令在 getter 上使用Field(_type Float, { nullable: true })声明计算字段averageRating无需额外存储。这些装饰器与生成 SDL 的对应关系可以对照 schema.graphql 逐行验证例如ratingsCount(minRate: Int! 0): Int!就来自 FieldResolver 的默认参数。Query、Mutation 与 FieldResolverrecipe.resolver.ts 展示了 Resolver 的四种典型写法Query(_returns Recipe, { nullable: true })配合Arg(title)实现单条查询Query(_returns [Recipe], { description: ... })实现列表查询Mutation(_returns Recipe)配合Arg(recipe)输入类型实现写入FieldResolver()配合Root()为对象类型补充跨字段派生数据ratingsCount接收Arg(minRate, _type Int, { defaultValue: 0 })参数演示了 Resolver 参数默认值的使用。输入侧由 recipe.input.ts 中的InputType()定义RecipeInput implements PartialRecipe复用了对象类型的形状对应 SDL 中的input RecipeInput。整条数据链路创建 → 存储 → 查询都能用 examples.graphql 里的AddRecipe、GetRecipe1、GetRecipes三个操作完整走通。进阶篇枚举、联合、订阅与接口枚举Enum与联合类型Unionenums-and-unionsenums-and-unions 示例解决“如何在 GraphQL 中表达 TS 枚举和联合结果”的问题。枚举TS 原生enum Difficulty必须先通过registerEnumType(Difficulty, { name: Difficulty, description: ... })注册才能被Field(_type Difficulty)引用。注册时的name即最终暴露给 GraphQL 的类型名description会写入 SDL 注释。联合类型使用createUnionType({ name: SearchResult, types: () [Recipe, Cook] as const })创建search-result.union.ts 中types用函数返回既解决循环引用问题也让search查询可以返回“食谱或厨师”两种异构结果。查询方需要使用内联片段inline fragment按__typename分别取字段。订阅Subscriptionsimple-subscriptions 与 redis-subscriptionssimple-subscriptions 使用graphql-yoga/subscription的createPubSub()作为内存事件总线在 pubsub.ts 中通过 TS 泛型精确声明每个 topic 的载荷类型。其 notification.resolver.ts 几乎覆盖了订阅的全部形态基础订阅Subscription({ topics: Topic.NOTIFICATIONS })方法体接收Root()载荷并返回给客户端的数据带过滤的订阅filter: ({ payload }) ...在触发时先判断payload.id % 2 0再决定是否推送多 topic 订阅topics: [Topic.NOTIFICATIONS, NOTIFICATIONS_2]动态 topictopics: ({ args }) args.topic根据订阅参数决定监听哪个频道动态 topic idtopicId: ({ args }) args.topicId为同一频道按业务 ID 分流发布端对应pubSub.publish(Topic.DYNAMIC_ID_TOPIC, topicId, payload)。配套的 examples.graphql 中给出了订阅操作的书写范例。当应用需要跨进程/跨实例广播时可以切换到 redis-subscriptions 示例它把 PubSub 后端替换为 Redis适用于多实例部署场景。接口与继承interfaces-inheritanceinterfaces-inheritance 一个目录同时演示了两种继承能力接口类型InterfaceType()定义Person接口person.interface.tsObjectType({ implements: Person })的Employee、Student等实现类自动继承字段Schema 中生成interface Person类型继承字段装饰器与类型定义均可沿类继承链传递同时该示例还包含ArgsType的参数对象用法见 person.input.ts。与之配套的 resolvers-inheritance 则专门演示 Resolver 类的继承子 Resolver 复用父 Resolver 的Query/Mutation方法及字段解析逻辑适合“多实体共享增删改查模板”的场景。特性篇IoC 容器、鉴权、校验与泛型类型依赖注入using-container 与 using-scoped-containerusing-container 演示了 TypeGraphQL 与typediTypeScript 的依赖注入容器的无缝集成。要点在于 recipe.resolver.ts 中的组合使用服务类RecipeService标注Service()Resolver 构造函数通过Inject() private readonly recipeService: RecipeService注入依赖在buildSchema时传入container选项让 TypeGraphQL 从容器实例化 Resolver才能让构造注入生效。using-scoped-container 是进阶版引入“每请求作用域”每个 GraphQL 请求创建独立的容器实例配合logger.ts演示请求级状态适合需要隔离用户态数据的应用。鉴权Authorizationauthorizationauthorization 示例展示了声明式鉴权的完整链路核心是两个文件auth-checker.ts 定义AuthCheckerContext无用户返回falseAuthorized()无角色参数时仅要求登录带角色参数时检查user.roles与要求角色是否有交集recipe.resolver.ts 用Authorized()仅登录保护addRecipe、Authorized(ADMIN)限定角色保护deleteRecipe未加装饰器的recipes查询保持公开。在buildSchema中通过authChecker选项注册该函数后所有鉴权判定都会在 Resolver 执行前完成拒绝访问时抛出AuthorizationError参见 errors/graphql/AuthorizationError.ts。该目录同时包含context.type.ts定义携带user的 Context与user.type.ts构成一个可直接照搬的最小鉴权骨架。自动校验Automatic Validationautomatic-validationautomatic-validation 演示 TypeGraphQL 与class-validator的整合在InputType/ArgsType类的字段上书写IsNotEmpty、Length、Min等校验装饰器TypeGraphQL 会在参数反序列化后、Resolver 执行前自动校验失败时抛出ArgumentValidationErrorsrc/errors/graphql/ArgumentValidationError.ts前端可据此回显错误信息。helpers.ts中提供了复用校验逻辑的辅助函数recipes.arguments.ts 展示了ArgsType参数对象与校验器组合的写法。若需要自定义错误格式化或分组校验可参考 custom-validation 示例。泛型类型与 Mixingeneric-types 与 mixin-classesgeneric-types 解决“分页包装类如何复用”的经典问题。paginated-response.type.ts 中的PaginatedResponseTItemsFieldValue工厂函数接收ClassType或基础类型动态生成带items、total、hasMore字段的ObjectType类业务侧只需PaginatedResponse(Recipe)即可获得对应的分页类型。相同思路的 mixin-classes 则演示通过类组合mixin复用字段定义如WithId、WithPassword混入用户类型。中间件与自定义装饰器middlewares-custom-decoratorsmiddlewares-custom-decorators 是“横切关注点”的合集目录结构即教程middlewares/ 内含error-logger异常日志、log-access访问日志、resolve-time耗时统计、number-interceptor返回值拦截四个中间件覆盖UseMiddleware的典型场景decorators/ 内含current-user从 context 取当前用户、random-id-arg注入随机 ID 参数、validate-args参数校验三个自定义参数装饰器分别对应createParameterDecorator与createMethodMiddlewareDecorator两种工厂函数。这一示例充分体现了 TypeGraphQL“装饰器驱动”的扩展哲学任何可复用的逻辑都可以封装成装饰器或中间件业务 Resolver 保持极简。第三方库集成篇TypeORM、Typegoose 与 ApolloORM 集成typeorm-basic-usage 与 typeorm-lazy-relationsTypeORM 集成有两档示例手动同步的 typeorm-basic-usage 与自动懒加载关系的 typeorm-lazy-relations。前者在 entities/ 中用EntityObjectType双装饰器标注实体由datasource.ts负责数据库连接需按文档提示编辑index.ts填入本地数据库凭据Resolver 手工调用getRepository完成读写后者演示 TypeORM 的Promise型懒加载关系如ManyToMany(() Rating, rating rating.recipe)在 TypeGraphQL 侧的解析方式——TypeGraphQL 会自动await被Field标注的 Promise 字段并借助 FieldResolver 展开关联数据。两套示例都配套schema.graphql与examples.graphql可以直接对比“手动组装关系”与“自动加载关系”在代码量上的差异。仓库中还提供了同思路的 typegooseMongoose ODM 装饰器与 mikro-orm 示例作为扩展参考。Apollo 生态apollo-cache 与联邦apollo-cache对应文档中的 Apollo Engine演示 TypeGraphQL 与 Apollo Cache Control 的结合通过Extensions与缓存指令为字段声明cacheControl提示helpers/RequireAtLeastOne.d.ts与getTime.ts提供辅助类型与逻辑可用于设计基于缓存的响应头策略。该示例需要设置APOLLO_ENGINE_API_KEY环境变量才能连接 Apollo 引擎服务。若应用采用微服务架构仓库还额外提供了 apollo-federation 与 apollo-federation-2 示例演示如何借助buildFederatedSchema见 helpers/buildFederatedSchema.ts把 accounts、products、inventory、reviews 等子图组合成联邦 Schema并为跨服务实体编写ResolverReference引用解析器如user.reference.ts、product.reference.ts这正是“实体由上游服务持有、下游服务按引用解析”的联邦模式落地写法。如何快速上手这些示例定位示例按上文分类找到与需求最接近的目录如入门选simple-usage鉴权选authorization多实例实时推送选redis-subscriptions对照阅读每个目录的examples.gql是“需求文档”index.ts是“启动模板”*.resolver.ts/*.type.ts是“核心实现”三者结合即可理解完整链路运行验证安装依赖后运行ts-node/tsx执行对应目录的index.ts服务默认监听 4000 端口simple-usage等示例的startStandaloneServer配置随后在 GraphQL Playground 中逐条执行examples.gql里的操作对照 SDL开启emitSchemaFile后检查生成的schema.graphql确认装饰器推导出的类型、可空性与默认值是否符合预期这是排查“为什么类型不对”的最直接手段。小结TypeGraphQL 的示例目录本身就是一套按场景组织的“活文档”simple-usage打底理解类与装饰器映射 Schema 的机制enums-and-unions、interfaces-inheritance、resolvers-inheritance、generic-types覆盖语言层面的类型表达using-container、authorization、automatic-validation、middlewares-custom-decorators解决工程化横切问题而 TypeORM、Typegoose、Apollo 系列则展示如何把 TypeGraphQL 平滑嵌入既有技术栈。对照 官方文档 中对应的功能章节如 resolvers.md、subscriptions.md、middlewares.md阅读示例源码可以在最短时间内掌握从“定义类型”到“上线部署”的完整开发范式。赞分享后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载相关推荐TypeGraphQL 官方示例实战指南从基础用法到第三方库集成全解析TypeGraphQL 官方示例实战指南从基础用法到第三方库集成全解析 导读 TypeGraphQL 是一个基于 TypeScript 装饰器语法创建 Gra后端GraphQLAPI设计TypeGraphQL 0.17.2 官方示例全览从基础类型到第三方库集成TypeGraphQL 0.17.2 官方示例全览从基础类型到第三方库集成 本篇文章基于 TypeGraphQL 仓库 v0.17.2 版本官方文档中的 Ex后端GraphQLAPI设计TypeGraphQL 官方示例全解析从入门到第三方库集成TypeGraphQL 官方示例全解析从入门到第三方库集成 TypeGraphQL 官方仓库在 examples/ https://link.gitcode.后端GraphQLAPI设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
