后端API设计【免费下载链接】graphql-yoga Rewrite of a fully-featured GraphQL Server with focus on easy setup, performance great developer experience. The core of Yoga implements WHATWG Fetch API and can run/deploy on any JS environment.项目地址https://gitcode.com/gh_mirrors/gr/graphql-yoga点击查看免费下载本文以 envelop/newrelic 插件文档 为核心介绍如何在基于 Envelop / GraphQL Yoga 的 GraphQL 应用中接入 New Relic Node.js Agent通过分布式追踪监控操作operation与解析器resolver的性能和错误。读完本文你将掌握插件的安装配置、全部选项的语义与默认值、基于正则表达式的变量/参数白名单黑名单过滤以及 newrelic.js 与环境变量两种 Agent 配置方式并能从源码与测试层面理解其工作原理。说明envelop/newrelic属于本仓库packages/envelop/plugins/newrelic目录是 Envelop 插件体系的一员可直接与 envelop/core 组合使用GraphQL Yoga 同样基于 Envelop 构建因此该插件也适用于 Yoga 服务。插件能做什么envelop/newrelic为你的 GraphQL 应用提供 New Relic 上报能力核心价值在于分布式追踪Distributed Tracing将 GraphQL 操作接入 New Relic 的跨服务追踪链路定位性能瓶颈与错误根因操作级监控以 GraphQL 操作operation为单位记录事务transaction可携带操作名、操作类型、请求文档、变量与执行结果Resolver 级监控把每个解析器的调用记录为 segment展示根字段root-field与子字段sub-field的逐级耗时错误追踪将执行结果中的GraphQLError上报给 New Relic Agent并支持自定义跳过规则。插件依赖 New Relic 官方 Node.js Agentnewrelicnpm 包自身只负责把 GraphQL 的语义信息桥接到 Agent 的 API 上最终的上报、采样、展示均由 Agent 与 New Relic 平台完成。快速开始按官方文档接入分三步安装依赖 → 配置 Agent → 注册插件。安装yarn add newrelic envelop/newrelic从 package.json 可以看到本插件的版本要求Node.js18.0.0作为peerDependency的envelop/coregraphql支持^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0newrelic支持7 12当前开发环境使用newrelic11.0.0。基本用法在创建 Envelop 实例时将插件加入 plugins 数组import { execute, parse, specifiedRules, subscribe, validate } from graphql import { envelop, useEngine } from envelop/core import { useNewRelic } from envelop/newrelic const getEnveloped envelop({ plugins: [ useEngine({ parse, validate, specifiedRules, execute, subscribe }), // ... other plugins ... useNewRelic({ includeOperationDocument: true, // 默认 false。为 true 时把定义操作与片段的 GraphQL 文档作为属性上报 includeExecuteVariables: false, // 默认 false。为 true 时把操作变量及值全部上报 includeRawResult: false, // 默认 false。为 true 时把执行结果上报 trackResolvers: true, // 默认 false。为 true 时把 resolver 记录为 segment 以监控性能 includeResolverArgs: false, // 默认 false。为 true 时把传给 resolver 的参数及值全部上报 rootFieldsNaming: true, // 默认 false。为 true 时把操作根字段名追加到事务名中 skipError: error { return true // 允许你决定某个错误是否上报给 NewRelic。默认情况下自定义的 EnvelopError 会被跳过 }, extractOperationName: context context.request.body.customOperationName // 从 context 中提取自定义操作名用于事务名与属性 }) ] })所有选项在源码 src/index.ts 中都有明确的默认值const DEFAULT_OPTIONS: UseNewRelicOptions { includeOperationDocument: false, includeExecuteVariables: false, includeRawResult: false, trackResolvers: false, includeResolverArgs: false, rootFieldsNaming: false, skipError: () false, };其中skipError的默认行为需要留意文档与源码注释指出插件默认会跳过EnvelopErrorEnvelop 自定义错误类型的上报避免把业务校验错误当作系统故障而对普通Error则按默认规则上报源码中skipError默认实现为恒返回false即不跳过。重要提示事务transaction与 segment/span 的计时可能受其他插件影响。为了获得更准确的追踪数据官方建议把 New Relic 插件放在插件列表的最后。选项详解与底层实现结合 src/index.ts我们逐项说明各选项的语义及其在源码中的落点。事务命名与操作级属性插件在onExecute阶段执行核心逻辑src/index.ts#L141-L241通过getOperationAST(args.document, args.operationName)解析出根操作拿不到则直接放弃记录确定操作名优先级为extractOperationName(context)→args.operationName→rootOperation.name?.value→ 匿名占位符anonymous源码中的AttributeName.ANONYMOUS_OPERATION如果开启了rootFieldsNaming会从 selectionSet 中收集所有根字段名只统计Kind.FIELD节点事务名被设置为operationType delimiter operationName ( delimiter rootFields.join())例如query/Greetings/hello分隔符来自 Agent 的transactionNameState.delimiter测试见 tests/newrelic.spec.ts通过getSpanContext()向 span 写入自定义属性。插件写入的属性名集中在AttributeName枚举中src/index.ts#L8-L21枚举值属性名含义COMPONENT_NAMEEnvelop_NewRelic_Plugin组件标识同时用于注册Supportability/ExternalModules/Envelop_NewRelic_Plugin指标EXECUTION_OPERATION_NAMEgraphql.execute.operationName操作名EXECUTION_OPERATION_TYPEgraphql.execute.operationType操作类型query / mutation / subscriptionEXECUTION_OPERATION_DOCUMENTgraphql.execute.documentGraphQL 文档字符串开启includeOperationDocument时写入EXECUTION_VARIABLESgraphql.execute.variables操作变量 JSON开启includeExecuteVariables时写入EXECUTION_RESULTgraphql.execute.result执行结果 JSON开启includeRawResult且结果含data时写入RESOLVER_FIELD_PATHgraphql.resolver.fieldPathresolver 字段路径如country/nameRESOLVER_TYPE_NAMEgraphql.resolver.typeName所属类型名如QueryRESOLVER_RESULT_TYPEgraphql.resolver.resultType返回类型如Country、String!RESOLVER_RESULTgraphql.resolver.resultresolver 返回结果 JSON开启includeRawResult时写入RESOLVER_ARGSgraphql.resolver.argsresolver 参数 JSON开启includeResolverArgs时写入includeOperationDocument把定义操作与片段的完整 GraphQL 文档写入graphql.execute.document。文档字符串通过envelop/core的getDocumentString(args.document, print)获取。includeExecuteVariables把操作变量 JSON 写入graphql.execute.variables变量取自args.variableValues。includeRawResult操作成功后把执行结果写入graphql.execute.result同时每个被追踪的 resolver 会把返回值写入graphql.resolver.result仅当includeRawResult开启。extractOperationName接收 Envelop 的DefaultContext返回自定义操作名同时用于事务名与graphql.execute.operationName属性。该能力在 4.0.0 版本由operationNameProperty改为函数式 API见 CHANGELOG.md好处是你可以读取 context 中的嵌套属性或来自其他 Envelop 插件的上下文扩展。错误处理与 skipError在onExecuteDone中插件对执行结果逐条检查错误src/index.ts#L204-L239if (singularResult.errors singularResult.errors.length 0) { const agent instrumentationApi.agent; const transaction instrumentationApi.tracer.getTransaction(); if (transaction) { for (const error of singularResult.errors) { if (options.skipError?.(error)) continue; agent.errors.add(transaction, JSON.stringify(error)); } } }skipError接收每个GraphQLError返回true表示跳过该错误的上报测试用例验证了这一点当skipError: e e.message Ignore me!时抛错 resolver 所在事务的hasError为falsetests/newrelic.spec.ts#L177-L198。流式结果支持对于订阅subscription等异步可迭代结果插件通过isAsyncIterable判断并使用onNext逐条上报、onEnd关闭 operation segmentsrc/index.ts#L226-L235。这一能力在 3.2.0 版本加入support async iterable results保证订阅类操作的错误与数据同样被记录。Resolver 级追踪的工作原理开启trackResolvers: true后插件会在onPluginInit阶段动态注入基于envelop/on-resolve的钩子src/index.ts#L81-L139useOnResolve在onSchemaChange阶段遍历 schema 中所有对象类型的字段把每个字段的 resolver 包上一层拦截逻辑packages/envelop/plugins/on-resolve/src/index.ts默认跳过 introspection 查询在 resolver 调用前插件通过instrumentationApi.getActiveSegment()拿到当前活动 segment为其创建名为resolver/路径的子 segment例如resolver/country、resolver/country/name字段路径由flattenPath递归拼接info.path得到数字类型索引如列表项下标会被跳过src/index.ts#L245-L257为 segment 写入graphql.resolver.fieldPath、graphql.resolver.typeName、graphql.resolver.resultTyperesolver 返回后包括异步 Promise 场景若开启includeRawResult则写入返回结果 JSON并结束 segment回调形式({ result }) { ...; resolverSegment.end(); }若当前没有活动事务或活动 segment例如 Agent 未初始化插件会通过 logger 以trace级别记录原因并跳过不会影响业务执行。另外插件在初始化时会先检查 Agent 是否可用rawOptions?.shim || newRelic?.shim以及instrumentationApi?.agent。若 Agent 不可用未正确安装newrelic、配置缺失或被禁用会打印警告并返回空插件避免应用崩溃src/index.ts#L65-L72。注册成功后还会上报一个Supportability/ExternalModules/Envelop_NewRelic_Plugin指标测试中对此有断言tests/newrelic.spec.ts#L79-L83。高级用法正则过滤变量与参数除了布尔值includeExecuteVariables和includeResolverArgs还接受RegExp用于对追踪内容做白名单/黑名单过滤。这在防止泄露用户数据如 PII的同时保留调试所需的字段非常有用。useNewRelic({ includeExecuteVariables: /client|application/i, // 白名单只追踪名称含 client 或 application 的变量如 clientName、applicationId、xApplicationId trackResolvers: true, // 追踪 resolver因为同时想追踪 resolver 参数 includeResolverArgs: /^(?!name|email|password).*/i, // 黑名单追踪所有名称不等于 name、email、password 的参数 }),实现上插件在初始化时用instanceof RegExp判断是否为正则options.isExecuteVariablesRegex/options.isResolverArgsRegex随后通过filterPropertiesByRegex遍历对象键、用pattern.test(property)逐键筛选src/index.ts#L259-L267。测试用例提供了直观的验证includeExecuteVariables: true 变量{ name: Laurin }→ 上报{name:Laurin}tests/newrelic.spec.ts#L86-L114includeExecuteVariables: /verb/ 变量{ verb: Hi, name: Dotan }→ 只上报{verb:Hi}tests/newrelic.spec.ts#L115-L150。性能提醒过滤变量和参数的方式是循环遍历因此会产生 O(n) 的开销其中n为操作变量个数追踪执行变量时或传给 resolver 的参数个数追踪 resolver 参数时。在生产环境请权衡过滤粒度与开销尤其是高 QPS 的服务。Agent 配置newrelic.js 与环境变量插件本身只负责桥接真正的 Agent 配置需要按 New Relic 官方文档完成。官方推荐两种配置方式newrelic.js 文件放在应用根目录。New Relic 官方仓库提供了该文件的基础示例对应node-newrelic的newrelic.js模板环境变量与 newrelic.js 中的配置项一一对应只需全部大写、以NEW_RELIC_前缀开头并在应用启动前确保变量已就绪。两个必填项描述newrelic.js环境变量应用名app_name: [MyAppName]NEW_RELIC_APP_NAMEMyAppName许可证密钥license_key: 40HexadecimalCharactersNEW_RELIC_LICENSE_KEY40HexadecimalCharacters常用配置项描述newrelic.js环境变量开启分布式追踪distributed_tracing: { enabled: true }NEW_RELIC_DISTRIBUTED_TRACING_ENABLEDtrue日志级别logging: { level: info }NEW_RELIC_LOG_LEVELinfo捕获所有请求头allow_all_headers: trueNEW_RELIC_ALLOW_ALL_HEADERStrue开启错误收集error_collector: { enabled: true }NEW_RELIC_ERROR_COLLECTOR_ENABLEDtrue更多可配置项可参考 New Relic Node.js Agent 的官方配置文档及其lib/config/default.js该文件列出了 newrelic.js 中可包含的全部配置变量均可转换为对应的环境变量。注意分布式追踪是本文场景跨服务定位 GraphQL 请求根因的基础建议显式开启。监控效果一览以下截图来自插件 README展示的是所有插件选项均为true时的 New Relic 界面效果。错误追踪与操作/Resolver 视图成功操作追踪——操作、根字段与子字段 resolver 视图从截图可以看到操作名为myCustomQuery的查询在 New Relic 中被记录为一次分布式追踪右侧 Attributes 面板展示graphql.execute.operationName、graphql.execute.operationType、请求文档、变量与结果span 列表中resolver/country、resolver/language等顶级 resolver 与resolver/country/name等子字段 resolver 被逐级展开错误场景下还会标注具体的GraphQLError错误类与出错 resolver如resolver/country及其入参{code:GB}、字段路径、结果类型等信息帮助快速定位究竟是哪个字段、哪个入参导致耗时异常或失败。小结envelop/newrelic以很小的接入成本为 GraphQL 服务补齐了 APM 能力操作级事务命名与属性、resolver 级 segment、错误上报、基于正则的敏感数据过滤一应俱全且对query/mutation/subscription三类操作均做了处理。其实现完全建立在 Envelop 的onExecute/onExecuteDone钩子与envelop/on-resolve的 resolver 拦截机制之上不侵入业务代码需要留意的是 Agent 未初始化时插件会静默降级打印警告、不记录以及按官方建议将插件置于 plugins 数组末尾以获得更准确的计时。赞分享后端API设计【免费下载链接】graphql-yoga Rewrite of a fully-featured GraphQL Server with focus on easy setup, performance great developer experience. The core of Yoga implements WHATWG Fetch API and can run/deploy on any JS environment.项目地址https://gitcode.com/gh_mirrors/gr/graphql-yoga点击查看免费下载相关推荐使用 redisotel 为 go-redis 接入 OpenTelemetry 分布式追踪与指标监控使用 redisotel 为 go redis 接入 OpenTelemetry 分布式追踪与指标监控 导读 redisotel 是 go redis git云原生存储GraphQL Yoga 与 Envelop 集成 OpenTelemetry 追踪从零接入到 Jaeger 全流程实战GraphQL Yoga 与 Envelop 集成 OpenTelemetry 追踪从零接入到 Jaeger 全流程实战 导读本文以开源仓库 graphql后端API设计Quansheng UV-K5硬件逆向工程从PCB到射频设计的完整技术解析Quansheng UV K5硬件逆向工程从PCB到射频设计的完整技术解析 在开源硬件与业余无线电技术快速融合的今天逆向工程已成为理解复杂射频系统设计的重要硬件开发逆向工程嵌入式智能硬件上一篇OmniGibson完整指南照片级渲染与物理仿真兼备的Embodied AI仿真平台下一篇暗影精灵性能解锁终极指南OmenSuperHub风扇曲线、功耗与灯效控制完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考