TypeGraphQL 安装与 TypeScript 环境配置指南：依赖安装、tsconfig 与前端 Shim 全解

后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载本篇指南聚焦于 type-graphql 项目当前仓库版本2.0.0-rc.4的安装与工程化配置。读完本文你将掌握完整的依赖安装清单含graphql、graphql-scalars等 peer dependencies 与reflect-metadata反射垫片、tsconfig.json中装饰器元数据与 ES2021 目标编译选项的精确配置以及在前端浏览器场景下使用shim复用类型类的高级做法为后续基于装饰器构建 GraphQL schema 与 resolver 打下可运行的工程基础。安装前的环境准备在开始安装之前首先确认开发环境已具备 Node.js 与 npm。从当前仓库的 package.json 可以看到TypeGraphQL 声明的运行时要求为node 20.11.1因此建议使用满足该版本要求的 Node.js LTS 版本。安装文档docs/installation.md也明确指出 TypeGraphQL 面向 Node.js LTS 及最新的稳定版设计并在运行时使用 ES2021 及以后的语言特性。包依赖安装主包与 peer dependenciesTypeGraphQL 本身不会替你安装graphql而是将它们声明为 peer dependencies需要你显式安装。执行以下命令一次性安装主包与两个 peer dependenciesnpm install graphql graphql-scalars type-graphqlgraphqlGraphQL 规范与执行引擎本体schema、类型解析、查询执行全部依赖它。graphql-scalars提供额外的常用标量类型如DateTime、Timestamp等方便在类型定义中直接使用。type-graphql项目主包提供ObjectType、Field、Query、Mutation、Resolver等装饰器与buildSchema等工具函数。从仓库的 package.json 可以看到完整的 peerDependencies 声明peerDependencies: { class-validator: 0.14.3, graphql: ^16.12.0, graphql-scalars: ^1.25.0 }, peerDependenciesMeta: { class-validator: { optional: true } }其中graphql的版本约束为^16.12.0。仓库在运行时会做严格的版本校验位于 src/utils/graphql-version.ts 的ensureInstalledCorrectGraphQLPackage函数使用semver检查当前安装的graphql版本是否满足^16.12.0若不满足会抛出 UnmetGraphQLPeerDependencyError错误信息会明确给出当前版本与期望版本帮助你快速定位问题。此外class-validator虽然也被声明为 peer dependency但它被标记为 optional——只有在需要使用Length、Min、Max等自动字段校验装饰器时才需要安装它。安装命令为npm install class-validator安装 reflect-metadata 反射垫片装饰器依赖 ES 的反射元数据 APIReflect.metadata()而 Node.js 原生并不内置这一 API因此必须安装一个 polyfill垫片npm install reflect-metadata # 或 npm install core-js两者任选其一即可reflect-metadata是专门针对Reflect.metadata()的轻量垫片core-js则提供了更全面的 ES 特性填充其中包含features/reflect。当前仓库的 devDependencies 中使用的正是reflect-metadata0.1.13见 package.json。垫片必须在入口文件的最顶部、在使用/导入type-graphql或任何 resolver 之前导入import reflect-metadata; // 或 import core-js/features/reflect;如果遗漏这一步运行时会在构建 schema 或解析元数据时抛出 ReflectMetadataMissingError错误信息会直接提示请阅读安装说明也就是本篇指南。安装完成后快速验证安装完成后可以通过以下命令验证安装结果与 Node 运行时版本node -v # 确认 Node.js 版本满足 20.11.1 npm -v # 确认 npm 可用 npm ls graphql graphql-scalars type-graphql reflect-metadatanpm ls会列出上述包的安装层级与版本若存在版本冲突会明确提示便于及时处理。TypeScript 编译配置tsconfig.json装饰器相关的两个核心开关TypeGraphQL 依靠 TypeScript 装饰器与设计类型元数据来完成从类到 GraphQL schema的映射因此必须在项目的tsconfig.json中开启以下两个选项{ compilerOptions: { emitDecoratorMetadata: true, experimentalDecorators: true } }两个选项缺一不可experimentalDecorators启用 TypeScript 的实验性装饰器语法支持没有它装饰器代码会直接编译报错emitDecoratorMetadata让编译器在装饰器代码中自动注入设计类型元数据design:type等TypeGraphQL 正是通过这一元数据在运行时推断字段类型从而免去大量显式类型标注。以仓库自身的构建配置 tsconfig.cjs.json 与 examples/tsconfig.json 为例examples 的配置在继承公共配置的基础上显式开启了emitDecoratorMetadata: true这正是编译仓库自带示例所必需的开关。你可以对照 examples/tsconfig.json 查看真实项目的最小配置。target 目标版本ES2021TypeGraphQL 源码使用了 ES2021 的语言特性因此编译目标不能低于es2021{ compilerOptions: { target: es2021 } }如果 Node.js 版本支持更新的标准如 ES2022也可以将target设置为更新的版本完全没问题。最小可用 tsconfig.json 完整示例综合以上全部要求一个最小的、可直接跑通 TypeGraphQL 项目的tsconfig.json如下{ compilerOptions: { target: es2021, module: commonjs, experimentalDecorators: true, emitDecoratorMetadata: true } }需要说明的是module选项的具体取值取决于你的模块体系选择使用 CommonJSNode.js 传统默认时设为commonjs即可若项目采用 ESM请参阅下文ESM 项目配置一节。仓库自身的根 tsconfig.json 展示了更完整的生产级配置参考——它额外开启了strict、esModuleInterop、skipLibCheck等严格编译选项其中target: es2021与experimentalDecorators: true均与本文一致可作为工程化配置的进阶参考。配置完成后如何验证将上述配置写入项目的tsconfig.json后运行npx tsc --noEmit若装饰器与元数据相关配置有误编译器会立即报错如experimental support for decorators相关提示此时请对照上面的配置逐项检查。ESM 项目的安装配置从仓库的 docs/esm.md 可以了解到自v2.0.0起 TypeGraphQL 已兼容 ECMAScript Modules。如果你的项目使用 ESM除了上文的基础配置外还需额外调整两处tsconfig.json中设置module与moduleResolution为NodeNext{ compilerOptions: { target: es2021, module: NodeNext, moduleResolution: NodeNext, experimentalDecorators: true, emitDecoratorMetadata: true } }package.json中设置type: module{ type: module }本地文件导入必须使用.js后缀即使源码是.tsimport { MyResolver } from ./resolvers/MyResolver.js;这与 TypeScript 在NodeNext模块解析下的 ESM 导入规则一致可以让import的type-graphql包在 ESM 项目中正常工作。前端场景使用 decorator shim 复用类型类TypeGraphQL 是一个面向 Node.js 的框架无法直接在浏览器环境中运行。但有时我们希望在浏览器端复用已经用装饰器标注的类例如带class-validator装饰器的 args/input 类或带有实用方法的 object type 类。直接打包通常会出现类似ERROR in ./node_modules/fs.realpath/index.js或utils1_promisify is not a function的错误。解决方案是使用仓库提供的decorator shim它把全部装饰器替换为空实现dummy decorators在浏览器端保留类的可复用性同时避免把整个 TypeGraphQL 运行时打进前端包显著减小打包体积。仓库中的实现位于 src/shim.ts并作为独立的子路径导出见 package.json 中的./shim导出同时 package.json 也将其声明为browser字段指向的入口。根据前端框架的不同配置方式有两种Webpack 系CRA 等在 webpack 配置中加入NormalModuleReplacementPlugin将type-graphql替换为type-graphql/shimmodule.exports { // ... Rest of Webpack configuration plugins: [ // ... Other existing plugins new webpack.NormalModuleReplacementPlugin(/type-graphql$/, resource { resource.request resource.request.replace(/type-graphql/, type-graphql/shim); }), ]; }Angular / Next.js 等 TypeScript 编译器场景在tsconfig.json的paths中直接映射到 shim 的.ts源文件Angular AoT 编译器要求提供完整的*.ts文件{ compilerOptions: { baseUrl: ., paths: { type-graphql: [./node_modules/type-graphql/build/typings/shim.ts] } } }在 Next.js 场景下由于服务端预渲染SSR在开发模式会跳过webpack: {}配置建议同样采用上述paths映射方式处理客户端打包。若使用该方式还需要安装tsconfig-paths并启用运行时注册npm install -D tsconfig-pathsNODE_OPTIONS-r tsconfig-paths/register # 在环境变量中启用关于浏览器场景 shim 的更多细节包括 Cypress 场景如何复用 webpack 插件方案可以参阅仓库文档 docs/browser-usage.md。安装完成后的下一步完成以上安装与配置后你的工程就已具备了运行 TypeGraphQL 的全部前置条件。接下来可以参考仓库文档 docs/getting-started.md 动手创建第一个示例用ObjectType()定义Recipe类型用Resolver/Query/Mutation定义查询与变更操作最后通过buildSchema生成可执行的 GraphQL schema构建 schema 的完整说明见 docs/bootstrap.md。仓库还提供了大量可直接运行验证的示例工程位于 examples 目录如simple-usage、automatic-validation、middlewares-custom-decorators等每个示例都包含配套的tsconfig.json与完整的类型、resolver 代码可以作为检验本地安装配置是否正确的最快途径将任一示例中的包依赖与 tsconfig 配置与你的工程对比再运行npx tsc --noEmit与示例的入口文件即可确认整套环境链路reflect-metadata 垫片、peer dependencies、装饰器元数据是否就绪。常见问题速查现象可能原因解决方式报错 Looks like youve forgot to provide experimental metadata API polyfill未安装/未导入reflect-metadata安装并在入口文件顶部import reflect-metadata;报错 use an incorrect version of the graphql package本地graphql版本不满足^16.12.0升级graphql至满足要求的版本装饰器编译报错未开启experimentalDecorators在tsconfig.json中开启类型推断缺失、schema 字段类型异常未开启emitDecoratorMetadata在tsconfig.json中开启浏览器打包报fs.realpath/promisify相关错误前端误打包完整 TypeGraphQL 运行时改用type-graphql/shim见上文 shim 一节赞分享后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载相关推荐geektime-nginx高级技巧Websocket代理与HTTP/2配置详解geektime nginx高级技巧Websocket代理与HTTP/2配置详解 geektime nginx是极客时间《Nginx核心知识100讲》的配置文Apache MXNet mxnet-cu110 包安装指南CUDA 11.0 环境下 PyPI 安装、前置依赖与构建配置详解Apache MXNet mxnet cu110 包安装指南CUDA 11.0 环境下 PyPI 安装、前置依赖与构建配置详解 Apache MXNet 以人工智能深度学习机器学习Android 开发者的一天用柚坛工具箱NT把刷机、调试和设备维护串成一条流水线Android 开发者的一天用柚坛工具箱NT把刷机、调试和设备维护串成一条流水线 如果你也曾经历过这样的早晨电脑上开着四五个终端窗口一边敲着 fastbo桌面应用开发工具上一篇X-Spider专业级推特媒体批量下载解决方案下一篇ArduPilot自动驾驶系统核心技术架构深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考