Grafast 复杂输入处理实战：Baking 与 Applying 双模式完全指南

Grafast 复杂输入处理实战Baking 与 Applying 双模式完全指南【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址: https://gitcode.com/gh_mirrors/cry/crystal本文是 GrafastGraphile Crystal 仓库中的执行引擎处理复杂 GraphQL 输入的高级指南。当输入数据嵌套较深、需要对输入做数据变换如把 GraphQL 输入对象映射为后端字段格式或行为变换如让请求步骤支持动态过滤、排序、分页时Baking 与 Applying 两套可选机制能帮你把重复的输入处理代码收敛为类型级的声明式逻辑保持代码整洁、可组合、易于推理。读完本文你将掌握fieldArgs.getBaked()与fieldArgs.apply()的完整用法、Modifier的 fan-out/fan-in 原理以及如何编写支持动态输入修改的 applyable step。何时需要这两套机制原文档开篇给出了一个重要的免责声明把原始输入值参数从 plan resolver 直接传给 step、留到执行期再处理是正常且被推荐的做法如果你的输入不复杂、这样直传没有带来任何问题那么本文介绍的进阶特性完全可以跳过。只有当出现以下信号时才值得引入 Baking / Applying输入数据结构复杂处理代码在多处重复出现难以维护需要为不同的输入对象类型 / 输入字段定制统一的变换或应用逻辑希望让逻辑更整洁、可组合、易于推理。在深入之前先区分处理复杂输入数据的两种模式Baking烘焙数据变换——把输入数据变换成另一种形态例如后端的表示形式。典型场景GraphQL 的camelCase输入对象 → 后端snake_case的 DTO。Applying应用行为变换——让输入数据去修改 step 将要执行的行为。典型场景分页、过滤、自定义排序——输入不产生新数据而是告诉 step 你要怎么干。两种模式的共同点是在运行时递归遍历输入值树对象、列表、标量按需调用每个字段或每种类型对应的逻辑。Baking把输入数据烘焙成后端表示Baking 的本质是data in, data out。你拿到一个 GraphQL 输入对象值把它变换为后端需要的表示。例如input AvatarInput { url: String! # ... } input UserInput { userId: Int! avatar: AvatarInput # ... }运行时可能收到{ userId: 27, avatar: { url: http://... } }经烘焙后变为后端表示{ user_id: 27, avatar_url: http://... }在 Schema 中定义烘焙Baking 按输入对象类型定义通过extensions.grafast.baked(input, info)方法挂载其类型为InputObjectTypeBakedResolver。该类型的精确定义见 interfaces.tstype InputObjectTypeBakedInfo { schema: GraphQLSchema; type: GraphQLInputObjectType; applyChildren(val: any): void; }; type InputObjectTypeBakedResolver ( input: Recordstring, any, info: InputObjectTypeBakedInfo, ) any;参数含义input—— 原始 GraphQL 输入对象值info.applyChildren(parent)—— 如果你希望以不同的 parent 对象继续递归处理子字段就调用它这会复用下方 Applying 的运行时行为inputArgsApply返回值 —— 即最终烘焙后的表示。如果某输入对象类型没有实现baked原始输入会原样透传——这是默认行为。对应地bakedInput()辅助函数见 bakedInput.ts只有在类型是列表、或输入对象类型上定义了baked函数时才会创建专门的BakedInputStep否则直接返回原始$value零额外开销。运行时机制与 applyChildrenBakedInputStep在unbatchedExecute中调用bakedInputRuntime()见 bakedInput.ts完成真正的递归变换其细节值得注意值为null/undefined时原样返回列表类型逐项递归调用类型的baked函数并把applyChildren(parent)注入到info中applyChildren内部用inputArgsApply以你传入的parent为靶向递归应用各子字段的变换逻辑若你的baked没有调用applyChildren框架会自动以baked的返回值作为 parent去应用各子字段——保证子字段逻辑不会丢失整个烘焙过程被withModifiers()包裹意味着烘焙过程中产生的Modifier也会被收集并按反向顺序执行详见下文 Applying 的 fan-in 部分。在 plan resolver 中获取烘焙值在 plan resolver 中使用fieldArgs.getBaked(path)即可产出某个原始输入值的烘焙版本const $baked fieldArgs.getBaked([path, to, input]);path可以是字符串参数名也可以是string | number组成的路径数组用于深入到嵌套对象或列表元素。其实现见 operationPlan-input.ts先通过getRaw(path)拿到原始输入 step再用typeAt(path)解析路径对应的输入类型最后调用bakedInput(inputType, $raw)生成烘焙 step。Applying让输入改变 step 的行为Applying 关注的是用输入值去改变 step 会做什么。它不产出烘焙值而是把输入应用到一个知道如何接收它们的 step 上——例如一个使用 request builder 去构造发送给数据库、URL 端点或其他数据源请求的 step。在 Schema 中定义应用Applying 按输入字段定义通过inputField.extensions.grafast.apply(target, input, info)方法挂载其类型为InputObjectFieldApplyResolver定义同样在 interfaces.tstype InputObjectFieldApplyResolverTParent any, TData any, TScope any ( target: TParent, input: TData, info: { schema: GraphQLSchema; fieldName: string; field: GraphQLInputField; scope: TScope; }, ) any;参数含义target—— 传入的父对象例如 request builderinput—— 该输入字段的原始值info—— 包含 schema、字段名、字段定义与 scope实验性见下文底层原理。apply 方法被期望修改target——可以直接改也可以通过返回Modifier间接改见下文 fan-out 与 fan-in。apply 方法的返回值有三种可能返回undefined—— 不做进一步递归返回一个新的父对象 —— 子字段递归时将以它为 parent列表类型时返回一个工厂函数—— 每个列表元素调用一次工厂函数为该元素生成各自的 parent 对象。返回工厂函数例如() new Thing()是OR这类过滤器的关键列表中的每个条目都拥有自己的子条件。示例简化自postgraphile-plugin-connection-filterfields[or] { apply( parent: PgCondition, value: ReadonlyArrayLogicalOperatorInput | null, ) { if (value null) return; const orCondition parent.orPlan(); // 每个列表条目只有在自身被完整处理后才会加入 orCondition—— // 如果单个条目产生多个子句必须先以 AND 连接再并入整个 OR。 return () orCondition.andPlan(); }, type: new GraphQLList(new GraphQLNonNull(UserFilter)), };Fan-out 与 fan-inModifier类当你返回一个新对象供子字段使用时就发生了fan-out扇出每个子字段可以在隔离的状态下添加自己的修改。但如果你需要在之后fan back in扇回——例如收集所有子条件、用OR组合、再把组合结果应用到父对象上——该怎么办这就是Modifier登场的地方。如果返回的对象继承了Modifier类Grafast会在 apply 过程中跟踪它当整个输入树遍历完成后Grafast会以逆序回头遍历收集到的 modifiers并调用它们的apply()方法。这给了你一个最终钩子把组合结果推回父对象。Modifier类的实际实现位于 applyInput.ts/** 扇出完成后会以逆序应用 */ const currentModifiers: Modifierany[] []; /** * Modifier 修改它们的 parentparent 可能是另一个 modifier 或任何其他对象。 * 首先它们从被应用到其上的子对象如果有收集全部需求 * 然后通过 apply() 方法把自己应用到 parent 上。 */ export abstract class ModifierTParent { protected readonly parent: TParent; constructor(parent: TParent) { this.parent parent; if (applyingModifiers) { throw new Error( Must not create new modifier whilst modifiers are being applied!, ); } currentModifiers.push(this); } /** * 在此方法中你应该把修改应用到 this.parent 上 */ abstract apply(): void; }配套的withModifiers()见 applyInput.ts负责收集与逆序执行cb()执行期间新构造的 modifier 进入当前集合cb结束即整个输入树遍历完成后从后往前依次调用每个 modifier 的apply()。这也解释了为何在 modifier 应用期间禁止再创建新的 modifier构造函数会抛错。使用 modifier 让OR示例更加干净每个子条目把条件贡献给 modifier所有条目处理完毕后modifier 的apply()被调用把组合好的OR子句加到它的 parent 上。在 plan resolver 中应用输入FieldArgs.apply()是把输入参数应用到 step 上的入口function usersPlan($query, fieldArgs) { const $users UsersStep.find(); // 把所有参数应用到 users step 上 fieldArgs.apply($users); return $users; }也可以只针对某个参数路径并可选地提供回调在应用前先变换 step 的值fieldArgs.apply($target, [filter], (requestBuilder, inputValue) { // 把 step 的值如 request builder转换成 filter builder 对象 return new FilterBuilder(requestBuilder, inputValue); // 一个 Modifier });apply()的实现细节见 operationPlan-input.ts有几个值得注意的行为路径为空时fieldArgs.apply($target)会自动禁用 autoApply并遍历所有参数逐个应用同一个输入路径不能重复应用重复调用会抛出错误Multiple applications are not currently supported若路径对应的值在规划期就是ConstantStep且数据为undefined即未传参会跳过应用——不会产生多余的依赖内部会调用$target.apply(applyInput(typeAtPath, $valueAtPath, getTargetFromParent))把应用动作作为一元依赖注册到目标 step 上。Applyable step能被输入驱动的 step要让 applying 生效传给fieldArgs.apply($target)的$target必须是一个applyable step——即一个支持在运行时接受输入驱动的修改的 step。其类型定义在 applyInput.ts// 简化后的类型 type ApplyableStep Step { apply($cb: Step(arg: any) void): void; };另有配套的类型守卫isApplyableStep()通过检测typeof s.apply function判断。一个 applyable step 有两项职责确保所有输入在 step 执行其动作之前都有机会修改 builder职责一规划期收集回调 stepstep 必须实现apply($cb: Step(parent: any) void)方法把$cb注册为一个一元依赖unary dependency。由于多个参数可能作用于同一个 step.apply()可能被调用多次因此要把所有依赖 ID 存进一个数组class MyRequestStep extends Step { applyDepIds: number[] []; apply($cb: Step(parent: any) void) { this.applyDepIds.push(this.addUnaryDependency($cb)); } // ... }职责二运行期执行收集到的回调在execute()中step 先准备好内部对象例如 request builder。注意这个对象绝不能是Modifier它应当是那个可被修改的可变事物。然后按顺序遍历收集到的回调把该对象传进去执行最后用填充完毕的 builder 发起请求class MyRequestStep extends Step { // ... async execute(details) { const { values, indexMap } details; const builder { //... // 用你已经知道的东西填充 request builder }; // 应用所有 .apply($cb) 调用带来的修改 for (const applyDepId of this.applyDepIds) { const applyCallback values[applyDepId].unaryValue(); applyCallback(builder); } // 执行底层请求并把结果与输入关联回来 const results await builder.execute(); return indexMap((batchIndex) results.getResultForIndex(batchIndex)); } }下面是一个更完整的示例演示如何用.apply()根据用户输入动态改变数据库结果的排序方式import { Step, ExecutionDetails, GrafastResultsList, Maybe } from grafast; interface MyQueryBuilder { orderBy(columnName: string, ascending?: boolean): void; } type Callback (builder: MyQueryBuilder) void; class MyQueryStep extends Step { private applyDepIds: number[] []; // [...] // this.foreignKeyDepId this.addDependency($fkey); // [...] // 只处理 StepCallback 已够用但组合类型最灵活。 apply($cb: StepMaybeCallback | ReadonlyArrayCallback) { this.applyDepIds.push(this.addUnaryDependency($cb)); } async execute( executionDetails: ExecutionDetails, ): PromiseGrafastResultsListRecordstring, any { const { values, indexMap } executionDetails; const foreignKeyEV values[this.foreignKeyDepId]; // 创建 query builder 收集 orderBy 值 const orderBys: string[] []; const builder: MyQueryBuilder { orderBy(columnName, asc true) { orderBys.push(${columnName} ${asc ? ASC : DESC}); }, }; // 对每个 apply() 回调把它作用于 query builder for (const applyDepId of this.applyDepIds) { const callback values[applyDepId].unaryValue(); if (Array.isArray(callback)) { callback.forEach((cb) cb(builder)); } else if (callback ! null) { callback(builder); } } // 现在可以用 orderBys 构建查询了 const query select * from my_table where foreign_key any($1) order by ${orderBys} ; // 然后获取数据 const allForeignKeys indexMap((i) foreignKeyEV.at(i)); const rows await runQuery(query, [allForeignKeys]); // 并把与每个输入值对应的正确数据返回 return indexMap((i) { const foreignKey foreignKeyEV.at(i); return rows.filter((r) r.foreign_key foreignKey); }); } }底层原理fieldArgs.apply()内部使用了applyInput()step定义于 applyInput.ts。正常情况下你不应直接调用它但在 plan 图中你会看到ApplyInput节点——它是定位规划问题的线索。applyInput()的另一个作用点是applyScope这是实验性功能可提供额外的 scope 值在 applying 过程中透传。scope 值挂在输入对象或枚举类型的extensions.grafast.applyScope()上applyInput在构造ApplyInputStep时读取namedType.extensions?.grafast?.applyScope?.()作为$scope依赖并最终出现在InputObjectFieldApplyResolver的info.scope中。inputArgsApply递归见 applyInput.ts完整覆盖了非空、列表、输入对象、标量、枚举五类情况其中值得注意的规则列表类型下每个列表项都会调用工厂函数若 target 是函数生成独立子目标并且每个列表项独立包裹在withModifiers()中保证顺序正确输入对象仅对有extensions.grafast.apply的字段调用 apply 逻辑枚举值的extensions.grafast.apply也会被执行undefined值直接跳过。在 schema 构建端baked与apply由 makeGrafastSchema.ts 统一接线InputObjectTypeBakedResolver、InputObjectFieldApplyResolver被读取后写入对应输入类型/字段的extensions.grafast上。如何选择 Baking 还是 Applying如果你只是需要把数据变换成后端期望的形态用bakingbakedfieldArgs.getBaked()如果你需要影响行为——例如告诉 step 如何过滤、排序或分页——用applyingapplyfieldArgs.apply()。两种模式可以在同一个 schema 中自由混用按每个输入的具体诉求选择最合理的方案即可。完整可运行示例仓库中的 complexInputs.mts 是一个可直接运行grafast执行并带断言的完整示例它同时演示了三件事用fieldArgs.getBaked(patch)inputObject.baked实现 Baking用fieldArgs.apply($request, filter)实现 Applying通过Modifier实现or: [UserFilterInput!]列表的 fan-out/fan-in。Schema 与输入input AvatarPatchInput { url: String! width: Int } input UserPatchInput { displayName: String marketingOptIn: Boolean avatar: AvatarPatchInput } input UserFilterInput { usernameStartsWith: String minAge: Int or: [UserFilterInput!] } type SearchPreview { sql: String! patchJSON: String! } type Query { previewSearch(filter: UserFilterInput, patch: UserPatchInput): SearchPreview! }执行时传入的变量{ filter: { usernameStartsWith: benj, minAge: 18, or: [{ minAge: 30 }, { usernameStartsWith: alice, minAge: 25 }] }, patch: { displayName: Benjie, marketingOptIn: true, avatar: { url: https://cdn.example.com/avatar.png, width: 128 } } }烘焙端patch 输入 → 后端 DTOinputObjects: { AvatarPatchInput: { baked(_input, info) { const baked: PartialBakedAvatarPatch {}; info.applyChildren(baked); // 递归把子字段烘焙进新对象 return baked as BakedAvatarPatch; }, plans: { url(target: PartialBakedAvatarPatch, value: string) { target.avatar_url value; // camelCase → snake_case }, width(target: PartialBakedAvatarPatch, value: number | null) { if (value ! null) { target.avatar_width value; } }, }, }, UserPatchInput: { baked(_input, info) { const baked: PartialBakedUserPatch {}; info.applyChildren(baked); return baked as BakedUserPatch; }, plans: { displayName(target: PartialBakedUserPatch, value: string | null) { if (value ! null) { target.display_name value; } }, marketingOptIn(target: PartialBakedUserPatch, value: boolean | null) { if (value ! null) { target.marketing_opt_in value; } }, avatar(target: PartialBakedUserPatch, value: unknown) { if (value null) return; const bakedAvatar: PartialBakedAvatarPatch {}; target.avatar bakedAvatar as BakedAvatarPatch; return bakedAvatar; // 返回新对象以继续递归 }, }, }, // ... }注意这里的plans在makeGrafastSchema的inputObjects配置中实际承载的就是前面文档说的extensions.grafast.baked/extensions.grafast.apply逻辑——baked 定义对象级变换plans 中的每个字段定义当该字段出现在输入中时对 parent 做什么。应用端filter 输入 → SQL 条件UserFilterInput: { plans: { usernameStartsWith(target: Filterable, value: Maybestring) { if (value null) return; target.addClause(username ilike ${value.replace(//g, )}%); }, minAge(target: Filterable, value: Maybenumber) { if (value null) return; target.addClause(age ${value}); }, or(target: Filterable, value: MaybeReadonlyArrayunknown) { if (value null) return; if (value.length 0) return; // 列表条目之间用 or 连接 const or new FilterModifier(target, or); // 但每个条目自身是对象其内部属性之间要用 and 连接 return () new FilterModifier(or, and); }, }, }Modifier 与 applyable stepclass FilterModifier extends ModifierFilterable implements Filterable { private type: BooleanOp; private clauses: string[] []; constructor(input: Filterable, type: BooleanOp) { super(input); this.type type; } addClause(clause: string) { this.clauses.push(clause); } apply(): void { if (this.clauses.length 0) return; if (this.type and) { this.parent.addClause(this.clauses.join( and )); } else { if (this.clauses.length 1) { this.parent.addClause((${this.clauses[0]})); } else { this.parent.addClause(((${this.clauses.join() or ()}))); } } } }SearchRequestStep同时展示了两个职责构造时以烘焙后的 patch step 为普通依赖addDependency运行时把apply回调收集到的 clause 与 patch 数据合并最终通过details.indexMap()把结果与输入一一对应class SearchRequestStep extends Step{ sql: string; patchJSON: string } { private readonly patchDepId: number; private readonly applyDepIds: number[] []; constructor($patch: StepBakedUserPatch) { super(); this.patchDepId this.addDependency($patch); } apply($cb: StepFilterCallbacks) { this.applyDepIds.push(this.addUnaryDependency($cb)); } execute(details: ExecutionDetails) { const patchDep details.values[this.patchDepId] as ExecutionValueBakedUserPatch; const clauses: string[] []; // 可放入初始子句 const applyCallbacks this.applyDepIds .flatMap((id) details.values[id].unaryValue() as FilterCallbacks) .filter((cb) cb ! null); const filterable: Filterable { addClause: (clause) void clauses.push(clause), }; for (const callback of applyCallbacks) { callback(filterable); } const sql select * from users${ clauses.length 0 ? where ${clauses.join( and )} : }; // 这里才是真正执行查询的位置——整个 execute 只调用一次 return details.indexMap((i) { const patch patchDep.at(i); return { sql, patchJSON: JSON.stringify(patch) }; }); } }plan resolver 与运行结果objects: { Query: { plans: { previewSearch(_parent, fieldArgs) { // 把 patch 输入经过其 baked 变换得到变换后的值 const $bakedPatch fieldArgs.getBaked(patch); // 创建代表搜索请求的 step const $request searchRequest($bakedPatch); // 把 filter 参数递归地应用到请求上 fieldArgs.apply($request, filter); return $request; }, }, }, }示例的断言结果显示了两套机制协同的产物{ previewSearch: { sql: select * from users where username ilike benj% and age 18 and ((age 30) or (username ilike alice% and age 25)), patchJSON: {\display_name\:\Benjie\,\marketing_opt_in\:true,\avatar\:{\avatar_url\:\https://cdn.example.com/avatar.png\,\avatar_width\:128}} } }可以看到patch 被正确烘焙为snake_case的 DTOfilter 被应用为带括号分组、正确结合AND/OR优先级的 SQL 条件。测试佐证列表输入的 apply 行为applyInput-list-object-test.ts 是覆盖 Applying 在列表输入上行为的测试其中FilterModifier每个列表项一个与FilterCollectorStep规划期通过ConstantStep判断实现常量应用优化、运行期执行动态回调给出了另一个可参考的 applyable step 写法。四个用例分别验证字面量列表filters: [{field:name,value:1},{field:email,value:2}]正确产出[name1,email2]整个输入是变量input: $input同样正确列表字段是变量input: { filters: $filters }正确列表中某个元素是变量filters: [{...}, $filter]也正确——说明 apply 的递归对变量与字面量混合嵌套的输入树同样成立。这份测试证实了 Applying 机制在设计上完整支持 GraphQL 变量、字面量以及两者任意嵌套组合的输入形态值得在实现自己的 applyable step 时对标参考。【免费下载链接】crystal Graphiles Crystal Monorepo; home to Grafast, PostGraphile, pg-introspection, pg-sql2 and much more!项目地址: https://gitcode.com/gh_mirrors/cry/crystal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考