PostGraphile V5 Schema 导出实战：用 exportSchema 将可执行 GraphQL Schema 变成代码

后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载本文是 PostGraphile V5 系列技术指南中的一篇聚焦 V5 引入的旗舰能力——将已经构建好的 GraphQL Schema 导出为可直接运行的 JavaScript/TypeScript 代码。读完本文你将掌握exportSchema的完整用法、SDL 与 introspection JSON 的轻量导出方式、EXPORTABLE与eslint-plugin-graphile-export的配合策略以及如何用postgraphile/presets/minify为 serverless 环境产出最小体积的导出产物并能从仓库源码层面理解导出器的工作原理与边界。为什么要把 Schema 导出成代码PostGraphile V5 的一个核心新特性是把 Schema 导出为可执行代码。导出后你可以Eject弹出Schema把生成 Schema 的工作接管过来Schema 变成你仓库里一个实实在在的.mjs文件之后可以完全脱离生成器自行维护加速生产环境启动导出的 Schema 不再需要 introspection也不再需要运行 graphile-build 的插件系统省去了启动时构建 Schema 的开销深入理解 Schema 的结构导出的代码是可读的——你可以直接看到每个类型、每个字段、每个 plan resolver 是如何定义的。无论你出于哪种目的用法都只有两步先构建 Schema再对它调用exportSchema。只想导出 SDL 或 introspection JSON用配置项即可如果你的需求只是拿到一份 GraphQL SDL 文件或 introspection JSON用于类型系统层面的检查、文档生成、前端 codegen 等不需要导出可执行代码那么不必动用exportSchema——在配置里设置两个路径即可preset.schema.exportSchemaSDLPath可选preset.schema.exportSchemaIntrospectionResultPath这两个配置项在 config/reference.mdx 中声明为string | undefined。设置后PostGraphile每次重建 Schema 时都会自动刷新这两个文件你无需编写任何额外代码。在 v4 兼容层源码 中可以看到这两个配置项与 V4 时代选项的对应关系exportSchemaSDLPath映射自options.exportGqlSchemaPathexportSchemaIntrospectionResultPath映射自options.exportJsonSchemaPath同时sortExport也被透传——从 V4 迁移的用户可以直接沿用旧配置。注意SDL 只描述类型系统不包含任何实现细节没有 plan resolver、没有 resolve 函数。如果你要导出的是带完整计划解析器的可执行 Schema请继续往下读。核心用法调用 exportSchema下面是一份完整的导出脚本示例来自官方文档它构建 Schema 后将其导出为exported-schema.mjsimport { exportSchema } from graphile-export; import { postgraphile } from postgraphile; import config from ./graphile.config.js; import * as jsonwebtoken from jsonwebtoken; const pgl postgraphile(config); async function main() { const { schema, resolvedPreset } await pgl.getSchemaResult(); const exportFileLocation ${__dirname}/exported-schema.mjs; await exportSchema(schema, exportFileLocation, { mode: graphql-js, // or: // mode: typeDefs, modules: { jsonwebtoken: jsonwebtoken, }, }); } main() .finally(() pgl.release()) .catch((e) { console.error(e); process.exit(1); });运行该文件后你会得到一个包含可执行 Schema的exported-schema.mjs。它不会 importgraphile-build、graphile-build-pg这类构建期模块只 import 真正用到的运行时依赖graphql、grafast及类似模块。exportSchema 的入口与选项exportSchema定义于 utils/graphile-export/src/exportSchema.ts并在 index.ts 中与exportSchemaAsString、exportValueAsString、EXPORTABLE一起对外导出。它接受三个参数schemaGraphQLSchema、导出文件路径、以及ExportOptions。ExportOptions 接口 完整定义如下选项类型默认值说明modegraphql-js \| typeDefs无导出风格见下文两种模式modules{ [moduleName: string]: any }无传入模块命名空间导出时遇到这些模块的顶层导出会自动以 import 形式引用prettierbooleanfalse是否用 prettier 格式化导出的代码disableOptimizeboolean无已废弃请改用optimizeLoops: 0optimizeLoopsnumber2优化轮数。0跳过优化适合导出超大 Schema 时内存吃紧的场景1只做一轮优化大于2一般收益递减两种导出模式graphql-js 与 typeDefsmode: graphql-js导出结果是一份用 GraphQL.js 构造函数new GraphQLObjectType({...})、new GraphQLSchema({...})等重建 Schema 的 ES Module 文件。这是最接近可执行 Schema 实体的产物适合直接交给运行时使用。源码中对应 exportSchemaGraphQLJS它会遍历config.query、config.mutation、config.subscription、types、directives等配置逐个调用declareType/declareDirective生成声明语句。mode: typeDefs实验性模式源码注释标注EXPERIMENTAL!导出结果为typeDefs加各类型plans的组合便于人类阅读。对应 exportSchemaTypeDefs它用printSchema(schema)生成 SDL 模板字符串并遍历每种类型Object / Interface / Union / InputObject / Scalar / Enum把extensions.grafast.plan、subscribePlan、resolve、applyPlan等导出为具名函数。modules 选项与 well-known 机制modules的核心作用是当你传入了某个模块的命名空间对象后导出器一旦在 Schema 中遇到该模块顶层导出的函数或值就会直接生成对应的 import 语句来引用它而不是试图把整个函数体复制出来。这是通过 wellKnown.ts 中的makeWellKnownFromOptions实现的。该函数在导出启动时建立一张值 → 模块/导出名的映射表并预置了四个内置模块的映射cryptografastgrafast/graphqlGraphQL.js 的类型与工具util此外还专门为内置标量的serialize/parseValue/parseLiteral方法建立了到graphql模块的引用便于自定义标量复用内建实现。之后才是处理你通过options.modules传入的模块。文档示例中传入jsonwebtoken的原因正在于此如果某个 plan resolver 中使用了jsonwebtoken的函数例如在 JWT 鉴权逻辑中导出器才能把它正确映射为import * as jsonwebtoken from jsonwebtoken否则会因无法序列化该函数而导出失败或产生错误的引用。导出器如何工作AST 生成与外部引用检测要理解什么情况下导出会失败需要看导出器把任意值转换为代码的核心逻辑每个需要导出的值都会被转换成一个 Babel AST 节点通过 CodegenFile 统一管理变量命名、import 收集、类型/指令声明与语句排布toAST()会把收集到的 import 语句按模块名排序后置于文件顶部。函数体的序列化通过funcToAst完成先对fn.toString()用 Babel 解析出函数表达式 AST再 遍历其中的 Identifier凡是被引用、但既不是局部绑定也不是函数参数的标识符都会被记入externalReferences。如果存在外部引用除了Buffer、console、process、setTimeout、setInterval等被放行的全局导出器会直接抛错The function being exported as locationHint references external variables: a, b. Please ensure this function is wrapped in EXPORTABLE(() ...).这正是官方文档警告导出函数必须用EXPORTABLE包裹或来自已声明模块的底层原因。EXPORTABLE显式声明闭包依赖EXPORTABLE 定义在 helpers.ts调用方式类似于 React Hooks——把工厂函数和它的依赖数组显式传给它const { EXPORTABLE } require(graphile-export); const a 7; const add EXPORTABLE( (a) function add(b) { return a b; }, [a], );EXPORTABLE(factory, args, nameHint)会立即调用factory(...args)得到函数并给它挂上三个隐藏属性见源码$exporter$factory工厂函数本身$exporter$args依赖数组$exporter$name可选的名字提示。导出器识别到这些属性后会走 factoryAst 路径先把工厂函数转成 AST再把依赖数组中的每个值逐一导出为表达式作为实参传入最终生成调用工厂、注入依赖的代码。factoryASTInner还做了优化当工厂参数名与传入实参的标识符同名时会直接删除参数声明并依赖外层作用域的同名变量参见shouldOptimizeFactoryCalls逻辑从而减少 IIFE 的包裹层级让导出代码更短、更可读。经验法则所有闭包捕获了外部变量的函数都必须包在EXPORTABLE里有时EXPORTABLE的入参本身也需要再包一层EXPORTABLE。最直接的排查方式是查看导出的代码找到引用断裂未定义变量的地方再回去补包。一些会直接导出失败的禁区从 exportSchema.ts 的_convertToAST可以看到几类明确拒绝导出的值sql模板对象报错提示 Exporting of sql values is not supported... please wrap in EXPORTABLE因此所有 SQL 片段都应放进EXPORTABLE工厂内部构造类实例 / 非 POJO 对象报错提示 you should wrap this definition in EXPORTABLE!类Class不支持直接导出类而是要求通过Object.defineProperty(MyClass, $$export, { value: { moduleName, exportName } })将其标记为可导入以__开头的变量名不允许生成canRepresentAsIdentifier正则排除了这类名称。导出前的三个必要检查1. 所有插件必须支持导出并非所有 PostGraphile 插件都支持 Schema 导出。如果使用了不支持导出的插件导出的 Schema 很可能会出现运行时错误甚至安全漏洞。因此在依赖导出 Schema 之前务必对其做充分测试。插件作者包括内部项目插件与发布到 npm 的插件应当完整阅读 graphile-export 文档并尽量启用eslint-plugin-graphile-export的规则确保自己添加的 plan resolver 等本身是可导出的。2. 用 eslint-plugin-graphile-export 拦截引用错误导出失败的主要模式是某个被导出的函数试图引用父作用域的变量而该变量没有通过EXPORTABLE正确处理。eslint-plugin-graphile-export仓库位于 utils/eslint-plugin-graphile-export能自动发现这类问题把要导出的值包上EXPORTABLE(() ...)后运行eslint --fix它会自动分析闭包捕获的依赖并补全依赖数组详见 graphile-export README 中的 ESLint 章节。该插件仍处于实验阶段官方建议只对包含 PostGraphile 插件的文件启用这套规则并且频繁提交代码以便任何意外改动都能回退。3. 对导出产物做代码级校验可以对导出的代码运行 ESLint、TypeScript 等校验工具确认不存在未定义变量引用等问题——因为导出的文件本身就是普通源码这些常规工具都能直接生效。开发、CI 与预发布环境请一并使用导出 Schema官方强烈建议如果你要导出 Schema就把导出产物纳入开发流程的每一个环节——开发环境用它、跑测试时用它、staging 环境也用它。这样做能让开发者和 QA 有大量机会尽早发现导出中的缺陷避免导出没问题的错觉只在生产环境被打破。服务端渲染与 serverless使用 minify preset在 serverless 环境中每个字节都重要——无论对打包、读取还是执行。而 serverless 端点通常不需要 introspection没有 GraphiQL、也没有构建工具去自省这个端点因此官方提供了专门的压缩 presetimport { PostGraphileAmberPreset } from postgraphile/presets/amber; import { PgMinifySchemaPreset } from postgraphile/presets/minify; const preset: GraphileConfig.Preset { extends: [PostGraphileAmberPreset, PgMinifySchemaPreset], /* ... */ }; export default preset;从 minify.ts 源码 可以看到它只是两个插件的组合PgRegistryReductionPlugin来自 graphile-build-pg缩减 registry 中的 extensions和MinifySchemaPlugin来自 graphile-build作用是剥离 Schema 中所有的描述description与废弃deprecation信息并清除多余的元数据。效果是需要导出的代码更少、打包体积更小、serverless 启动更快。由于它移除了描述与废弃信息最适合以毫秒计的生产导出场景如 serverless而不适合传统服务器或面向开发者的 Schema。该 preset 标注为experimental具体行为后续可能演进。运行导出的 Schema只 import 你需要的部分导出完成后用下面的方式启动一个最小服务器官方示例import { grafserv } from postgraphile/grafserv/node; import { createServer } from node:http; import preset from ./graphile.config.js; import { schema } from ./exported-schema.mjs; const server createServer(); const serv grafserv({ preset, schema }); serv.addTo(server); server.listen(5555); console.log(Listening on http://localhost:5555/);注意这里只 import 了三样东西node版 grafserv 适配器、导出的 schema、以及你的 preset——没有 importpostgraphile本身也没有 graphile-build 系统因为 Schema 已经构建完毕。Schema 导出文件自身会拉入少量其他模块但运行时不再需要构建期依赖这有助于降低常驻内存占用同时更少的 import 意味着更快的启动如果为 serverless 打包包体也更小。小结从构建 Schema到运行 Schema的工作流轻量场景设置schema.exportSchemaSDLPath/schema.exportSchemaIntrospectionResultPath让 PostGraphile 在每次重建时自动输出 SDL / introspection JSON可执行场景通过pgl.getSchemaResult()拿到schema与resolvedPreset调用exportSchema(schema, path, { mode: graphql-js, modules: {...} })生成exported-schema.mjs质量保障所有自定义 plan resolver 用EXPORTABLE包裹闭包依赖插件文件启用eslint-plugin-graphile-export并在 dev / CI / staging 全链路使用导出产物运行只 import grafserv 适配器、导出 Schema 与 preset即可用任意 Node HTTP 框架如示例中的node:http对外提供服务性能serverless 场景追加PgMinifySchemaPreset压缩导出体积必要时可通过optimizeLoops: 0关闭导出优化以应对超大 Schema 的内存压力。相关参考exportSchema 完整实现、ExportOptions 定义、EXPORTABLE 与依赖检测、graphile-export 使用文档、minify preset 源码。赞分享后端API网关【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址https://gitcode.com/gh_mirrors/cry/crystal点击查看免费下载相关推荐PostGraphile V5 导出可执行 Schema用 graphile-export 把运行时构建的 GraphQL 模式固化为代码PostGraphile V5 导出可执行 Schema用 graphile export 把运行时构建的 GraphQL 模式固化为代码 导读 PostGr后端API网关在 Excel 里画出三种比例图饼图、环形图与华夫饼图在 Excel 里画出三种比例图饼图、环形图与华夫饼图 手上一堆分类数据想让人一眼看出各占多少——画圆的、戳洞的、还是画格子的别纠结用同一份蘑菇数据在后端API网关graphile-export 原理与实战把内存中的 GraphQL Schema 导出为可执行的 JavaScript 代码graphile export 原理与实战把内存中的 GraphQL Schema 导出为可执行的 JavaScript 代码 graphile export后端API网关创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考