后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载导读TypeGraphQL 是运行在 Node.js 环境中的 GraphQL 框架但我们在业务中经常需要把标注了装饰器的输入类、参数类或对象类型类复用到浏览器端例如配合class-validator做前端校验。本指南基于 type-graphql 仓库中 docs/browser-usage.md 与 src/shim.ts 源码系统讲解 decorator shim 的工作原理并分别给出 CRA/Webpack、Angular、Next.js 等主流前端方案的完整配置步骤帮助读者在不打包整个框架的前提下安全复用共享类。为什么 TypeGraphQL 无法直接在浏览器运行TypeGraphQL 是面向 Node.js 服务端的框架它的职责是根据装饰器元数据构建 GraphQL Schema、解析 Resolver 并驱动数据源。整个构建链路依赖 Node.js 环境特性文件系统、反射元数据、GraphQL 依赖图等而这些在浏览器打包环境中并不成立。因此当我们在前端项目例如基于 Webpack 的 Create React App中直接 importtype-graphql时很容易在构建阶段遇到两类典型报错ERROR in ./node_modules/fs.realpath/index.js—— 框架依赖了 Node 核心模块如fs浏览器打包器无法解析utils1_promisify is not a function—— 打包过程中对 Node 工具函数的处理在浏览器环境下失效。这两个报错说明浏览器端真正需要的其实不是 TypeGraphQL 的完整实现而是那些装饰器函数本身的“存在”——只有装饰器在运行时被调用、且不抛错共享类上的注解才能被class-validator等库读取。这正是 decorator shim 存在的意义。shim 的工作原理dummy 装饰器 完整类型签名shim 的实现位于 src/shim.ts。它不是把框架搬进浏览器而是为每一个公共装饰器/函数提供“空实现”同时保留与真实模块完全一致的 TypeScript 类型签名。装饰器全部替换为 dummy 实现源码中所有装饰器都被映射为dummyDecorator而函数则映射为dummyFnexport function dummyFn() {} export function dummyDecorator() { return dummyFn; } export const ObjectType: typeof src.ObjectType dummyDecorator; export const Field: typeof src.Field dummyDecorator; export const InputType: typeof src.InputType dummyDecorator; export const ArgsType: typeof src.ArgsType dummyDecorator; export const Resolver: typeof src.Resolver dummyDecorator; export const Query: typeof src.Query dummyDecorator; export const Mutation: typeof src.Mutation dummyDecorator; // ... Arg、Args、Ctx、Root、Info、FieldResolver、Authorized、 // UseMiddleware、Directive、Extensions、Subscription、InterfaceType 等同理这些被替换的装饰器与 src/decorators/index.ts 导出的公共 API 一一对应。例如真实的ObjectType会调用getMetadataStorage().collectObjectMetadata(...)收集元数据见 src/decorators/ObjectType.ts而 shim 中的ObjectType只是返回一个空函数让装饰器语法合法地“跑过去”。对于非装饰器形态的 APIshim 也提供了 dummy 版本export const createParameterDecorator: typeof src.createParameterDecorator dummyFn as any; export const createMethodMiddlewareDecorator: typeof src.createMethodMiddlewareDecorator dummyFn as any; export const createResolverClassMiddlewareDecorator: typeof src.createResolverClassMiddlewareDecorator dummyFn as any; export const registerEnumType: typeof src.registerEnumType dummyFn; export const createUnionType: typeof src.createUnionType dummyFn as any;标量类型导出为占位值shim 还把常用标量导出为占位空字符串避免前端因引用缺失的 GraphQL 标量而崩溃export const Int: typeof src.Int dummyValue as any; export const Float: typeof src.Float dummyValue as any; export const ID: typeof src.ID dummyValue as any; export const GraphQLISODateTime: typeof src.GraphQLISODateTime dummyValue as any; export const GraphQLTimestamp: typeof src.GraphQLTimestamp dummyValue as any;类型保真是关键设计注意所有导出都使用了typeof src.Arg、typeof src.ObjectType这类“值类型镜像”写法import type * as src from ./index这意味着前端代码依旧可以拿到完整的 IntelliSense 与编译期类型检查装饰器参数、返回类型与真实模块完全一致共享类文件不需要做任何浏览器端改造编译期正常运行时零开销——这正是 shim 可以放心嵌入前端包的原因。打包产物中的 shim 入口在 package.json 中shim 被作为独立的子路径导出暴露给打包器exports: { .: { require: ./build/cjs/index.js, import: ./build/esm/index.js, types: ./build/typings/index.d.ts }, ./shim: { require: ./build/cjs/shim.js, import: ./build/esm/shim.js, types: ./build/typings/shim.ts } }同时browser字段被显式指向 shim 的 CJS 产物browser: ./build/cjs/shim.js从源码结构看构建脚本postbuild会把 src/shim.ts 原样拷贝进build/typings目录见 package.json 的postbuild脚本确保node_modules/type-graphql/build/typings/shim.ts这个路径在安装后真实存在——这正是下文 Angular/Next.js 方案中paths映射能生效的前提。方案一CRA 与一般 Webpack 工程 —— NormalModuleReplacementPlugin对 Create React App以及任何使用 Webpack 的工程最直接的方式是使用 Webpack 的NormalModuleReplacementPlugin把type-graphql模块请求重写为type-graphql/shimmodule.exports { // ... Webpack 其余配置 plugins: [ // ... 已有的其他插件 new webpack.NormalModuleReplacementPlugin(/type-graphql$/, resource { resource.request resource.request.replace(/type-graphql/, type-graphql/shim); }), ], };关键点说明正则type-graphql$精确匹配模块请求结尾避免误伤其他以type-graphql开头的路径回调中把请求字符串整体替换为type-graphql/shim打包器会命中 package.json 中./shim的 exports 映射解析到build/cjs/shim.jsCRA 场景下需要借助react-app-rewired或craco等工具覆写 webpack 配置将上述代码合并进最终配置。采用 shim 之后前端 bundle 不再嵌入完整的 TypeGraphQL 库代码体积会显著变小——因为浏览器端根本不需要 Schema 生成、元数据收集等逻辑只保留“装饰器可被调用”的最小骨架。方案二Cypress 端到端测试场景如果前端使用了 Cypress 编写端到端测试且测试代码同样复用了 TypeGraphQL 装饰类可以复用完全相同的 Webpack 重写技巧在 Cypress 的 webpack 预处理阶段应用上述NormalModuleReplacementPlugin配置即通过cypress-webpack-preprocessor插件挂载同一份 webpack 配置即可让 Cypress 的浏览器运行时也加载 shim 版本避免打包 Node 端依赖时报错。方案三Angular 及 AoT 编译类工程 —— tsconfig paths 映射Angular 的 AoTAhead-of-Time编译器要求直接提供完整的*.ts源文件而不是仅提供编译后的*.js与*.d.ts声明文件。此时无法依赖 exports 字段解析而需要在tsconfig.json中把type-graphql的模块路径直接指到 shim 的 TypeScript 源文件{ compilerOptions: { baseUrl: ., paths: { type-graphql: [node_modules/type-graphql/build/typings/shim.ts] } } }要点baseUrl设为.项目根目录使paths中的相对路径可解析node_modules/type-graphql/build/typings/shim.ts正是构建产物中保存的 shim 源码见上文postbuild拷贝逻辑文件确实存在TypeScript 编译器在遇到import { ObjectType } from type-graphql时会改用该路径完成类型解析与编译Angular 编译器随后编译的是真实可用的.ts文件。此思路同样适用于其他要求源码级引用、或不便改动打包器配置的 TypeScript 工程——只要工具链支持paths模块别名即可。方案四Next.js —— tsconfig paths tsconfig-paths 运行时注册Next.js 同时承担前端渲染与“专用前端服务器”pre-render两种角色情况比纯 SPA 复杂一些服务端预渲染阶段开发模式下next.config.js中的webpack: {}配置会被跳过完整版type-graphql会被打包进服务端 bundle——这在服务端是无害的客户端打包阶段无论开发还是生产客户端 bundle 依然由 Webpack 完成因此仍然需要把type-graphql重定向到 shim。最简单的做法与 Angular 相同先在tsconfig.json中声明路径映射{ compilerOptions: { baseUrl: ., paths: { type-graphql: [node_modules/type-graphql/build/typings/shim.ts] } } }但 Next.js 服务端运行时的模块解析并不读取tsconfig.json的paths它由tsconfig-paths这类库在运行时注入所以还需要两步安装运行时路径注册库npm install -D tsconfig-paths在环境变量中启用其 Node 注册钩子让服务端 Node 进程在 require 模块时也遵循tsconfig.json的paths映射NODE_OPTIONS-r tsconfig-paths/register配置完成后客户端 Webpack 打包与 Next.js 服务端预渲染都会把type-graphql解析到 shim两侧行为保持一致。如何选择适合自己的方案前端工程类型推荐方案核心配置位置CRA / 通用 Webpack 工程NormalModuleReplacementPluginwebpack 配置需 react-app-rewired / craco 覆写Cypress 端到端测试同一 Webpack 插件 cypress-webpack-preprocessorCypress webpack 预处理配置AngularAoT 编译tsconfig.json的paths映射compilerOptions.baseUrlpathsNext.js前后端一体tsconfig.json的paths映射 tsconfig-pathstsconfig.jsonNODE_OPTIONS环境变量注意事项与最佳实践仅共享类型与校验逻辑shim 只保证装饰器语法在前端“合法存在”不要在浏览器端调用buildSchema、createResolversMap等 Schema 构建 API——这些能力在 shim 中没有实现对应 src/utils 目录下的真实实现仅在 Node 端可用。shim 的正确使用场景是复用InputType/ArgsType标注的参数校验类、或带自定义方法的ObjectType类browser字段是补充手段从仓库 package.json 看browser字段已指向 shim 的 CJS 产物部分识别该字段的打包器如 Webpack 5 的默认解析可能自动生效但为了结果可控本文给出的显式配置Webpack 插件或paths映射仍然是跨工具链最稳妥的方案保持前后端依赖版本一致shim 的类型签名来自import type * as src from ./index如果前端安装的type-graphql版本与后端不同可能出现类型签名漂移建议两端锁定同一版本验证 bundle 是否生效配置完成后检查产物中是否仍包含fs.realpath等 Node 模块报错即可快速验证也可以直接在构建产物中搜索dummyDecorator字样确认已切换到 shim。通过本文的配置你可以在完全不影响服务端 Schema 构建的前提下把 TypeGraphQL 的共享类安全地复用到浏览器端同时保持 bundle 轻量、类型完整、构建无报错。更完整的文档原文可参阅 docs/browser-usage.mdshim 的全部实现细节见 src/shim.ts。赞分享后端GraphQLAPI设计【免费下载链接】type-graphqlCreate GraphQL schema and resolvers with TypeScript, using classes and decorators!项目地址https://gitcode.com/gh_mirrors/ty/type-graphql点击查看免费下载相关推荐TypeGraphQL 浏览器端使用指南借助 Decorator Shim 在 Web 客户端复用共享类TypeGraphQL 浏览器端使用指南借助 Decorator Shim 在 Web 客户端复用共享类 TypeGraphQL 是一个基于 TypeScri后端GraphQLAPI设计TypeGraphQL 浏览器端使用指南用 Decorator Shim 在前后端共享类型类TypeGraphQL 浏览器端使用指南用 Decorator Shim 在前后端共享类型类 TypeGraphQL 是一个基于 TypeScript 类与装后端GraphQLAPI设计TypeGraphQL 浏览器端使用指南用 Decorator Shim 在前端安全复用共享类TypeGraphQL 浏览器端使用指南用 Decorator Shim 在前端安全复用共享类 TypeGraphQL 是一个运行在 Node.js 环境的后端GraphQLAPI设计上一篇A-Tune性能对比测试传统调优与AI调优的效果差异分析下一篇10分钟上手witty-opentunex自动模式性能诊断快速教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考