wrapPlans resolver emulation warning
You're probably here because you just saw a warning like:
你之所以会看到这个页面,多半是因为遇到了类似下面的警告:
[WARNING]: `wrapPlans(...)` plugin WrapPlansPlugin_1 has wrapped the default
plan resolver at field coordinate User.email. If this is an impure schema (one
that mixes traditional resolvers with Gra*fast* plan resolvers) then this may
result in hard to track down issues - hence this warning. See
https://err.red/pwpr for full explanation and proposed solutions.
Plan resolvers vs traditional resolversPlan resolver 与传统 resolver
Grafast, the GraphQL engine powering PostGraphile, runs on the basis of plan resolvers. Everything built in to PostGraphile uses these plan resolvers - by default, PostGraphile produced a "pure" Grafast schema.
驱动 PostGraphile 的 GraphQL 引擎 Grafast 是基于 plan resolver 运行的。PostGraphile 的所有内置功能都使用这类 plan resolver——默认情况下,PostGraphile 生成的都是“纯” Grafast schema。
However, Grafast also supports emulating traditional resolvers (see Using
with existing
schema
in the Grafast docs) for compatibility with traditional GraphQL.js-style
schemas, and it's possible to add these traditional resolvers to a PostGraphile
schema via extendSchema() or other methods. Adding traditional resolvers to a
Grafast schema makes the schema "impure" - it should still work fine, but
it's less performant and there are caveats to be aware of, such as this one.
不过,为了兼容传统的 GraphQL.js 风格 schema,Grafast 也支持模拟传统 resolver(参见 Grafast 文档中的在现有 schema 中使用);你也可以通过 extendSchema() 等方式,将这类传统 resolver 添加到 PostGraphile 的 schema 中。往 Grafast schema 中加入传统 resolver 后,schema 就会变成“非纯(impure)”状态——虽然整体仍能正常运行,但性能会有所下降,而且还存在一些需要注意的隐患,本警告正是其中之一。
Pure Grafast schemas纯 Grafast schema
If you have a pure Grafast schema - a schema that only uses plan resolvers (no
resolve or subscribe traditional resolvers) - then you can safely ignore
this warning, and can even prevent it being emitted using
disableResolverEmulationWarnings: true.
如果你的 schema 是纯 Grafast schema——即只使用了 plan resolver(没有任何传统的 resolve 或 subscribe resolver)——那么可以安全地忽略此警告,甚至可以配置 disableResolverEmulationWarnings: true 来关闭它的输出。
Impure Grafast schemas非纯 Grafast schema
When a traditional resolver is seen, Grafast enters "resolver emulation" mode. In this mode, among other changes it no longer uses the default plan resolver when a field has no plan.
一旦检测到传统 resolver,Grafast 就会进入“resolver 模拟”模式。在此模式下,除了其他行为变化外,当字段没有定义 plan 时,系统将不再使用默认 plan resolver。
However, wrapPlans() will always ensure the field has a plan, and if there is
no plan to wrap then it will default to wrapping the
defaultPlanResolver.
然而,wrapPlans() 始终会确保字段拥有一个 plan;如果该字段原本没有可包装的 plan,它就会默认去包装 defaultPlanResolver。
Adding a plan to a field that was called in resolver emulation mode will change the data to be fed into the resolver, thereby causing breakage.
在 resolver 模拟模式下调用的字段如果被额外加上了 plan,就会改变传入该 resolver 的数据,进而导致运行出错。
Since plan wrapping occurs at schema build time, not at runtime, PostGraphile cannot know whether or not resolver emulation will be enabled. Since the issues this cause can be hard to track down otherwise, out of an abundance of caution we raise this warning for users who are applying very broad plan wrapping logic to help them know which specific fields might surface an issue.
由于 plan 包装发生在 schema 构建阶段而非运行时,PostGraphile 无法提前判断后续是否会开启 resolver 模拟。这类问题一旦发生往往极难排查,因此出于审慎考虑,当用户应用了覆盖范围很广的 plan 包装逻辑时,我们会触发这条警告,帮助你定位具体哪些字段可能会出现隐患。
Resolution解决方案
To resolve this:
要解决该警告,可以采取以下任意一种方式:
-
Add a (non-default) plan resolver for the field you are wrapping, or
为你所包装的字段提供一个(非默认的)plan resolver;或
-
Avoid wrapping the default plan resolver, or
避免包装默认的 plan resolver;或
-
Set
disableResolverEmulationWarnings: truewhen callingwrapPlans()once you have confirmed it is safe for your schema.在确认对当前 schema 无影响后,于调用
wrapPlans()时设置disableResolverEmulationWarnings: true。
Avoid wrapping default plan resolvers避免包装默认 plan resolver
To avoid wrapping the default plan resolver, consider logic like this:
要避免包装默认的 plan resolver,可以参考以下写法:
const MyPlugin = wrapPlans(
(context, build, field) => {
const {
grafast: { defaultPlanResolver },
} = build;
const plan = field.extensions?.grafast?.plan ?? defaultPlanResolver;
// Don't wrap the default plan resolver
if (plan === defaultPlanResolver) return null;
// ...
},
// ...
);
Disable the warning关闭该警告
If you're sure this part of the schema won't be impacted by resolver emulation, you can disable the warning:
如果你确定 schema 的这一部分不会受到 resolver 模拟的影响,可以直接关闭该警告:
const MyPlanWrapperPlugin = wrapPlans(rules, {
name: "MyPlanWrapperPlugin",
disableResolverEmulationWarnings: true,
});
// Or:
const MyOtherPlanWrapperPlugin = wrapPlans(filterFn, ruleFn, {
name: "MyOtherPlanWrapperPlugin",
disableResolverEmulationWarnings: true,
});