从 AVA 快照测试读懂 Prisma Client 的查询文档生成与响应解包机制【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1导读本篇文章以prisma-client-lib包中的 AVA 快照报告 Client.test.js.md 为骨架结合其对应的 Client.test.ts 测试源码与 Client.ts 核心实现系统剖析 Prisma Client 运行时两个最关键的行为链式 API 调用如何被编译成合法的 GraphQL 查询文档特别是自动非标量子字段选择以及服务端返回数据如何按指令链解包成最终结果。读完本文你将能看懂 Prisma Client 生成的查询形状理解__typename自动填充、Relay Connection 展开、嵌入式类型展开与extractPayload解包等底层原理并能借助debug选项与快照测试定位自己项目中的查询问题。一、这份快照报告是什么文件定位与读取方式1.1 文件身份AVA 自动生成的快照报告Client.test.js.md是 AVA 测试框架运行dist/Client.test.js后自动生成的snapshot report快照报告。其头部元信息明确说明了这一点实际快照数据保存在同目录的Client.test.js.snap中The actual snapshot is saved in Client.test.js.snap生成工具为 AVAGenerated by AVA报告按测试用例名如automatic non-scalar sub selection分组每组对应一次t.snapshot(...)断言。需要特别说明的是快照文本中的␊U240ASymbol for Line Feed是换行符的转义显示并非真实字符。例如{␊ users {␊ __typename␊ }␊ }␊ 实际等价于一段标准 GraphQL 文档字符串{ users { __typename } }1.2 16 组快照的全景清单报告共收录 16 组快照可归为四大主题主题快照用例自动非标量子字段选择普通对象 / 枚举 / 标量automatic non-scalar sub selection、... and enums、... and scalars自动非标量子字段选择Connection / 关系... for a connection with scalars、... without scalars、... for relation类型导航与嵌入related type、deep related type、embedded type、nested mbedded type参数变量化top level args、nested args响应解包extractPayloadunpacking extract payload - array、- nested array、- nested object、- null from server这 16 组快照全部能在 Client.test.ts 中找到一一对应的test(...)用例是理解 Prisma Client 运行时行为的官方黄金样本。二、测试基础设施用例如何构建与快照如何生成在深入快照内容前先理解测试是如何运行的。每个用例都遵循相同模式见 Client.test.tsimport { test } from ava import { Client } from ./Client import { print } from graphql const typeDefs type Query { user(where: UserWhereInput): User } input UserWhereInput { id: ID! } type User { id: ID!, name: String!, houses: [House!]! } type House { id: ID!, name: String! } const client: any new Client({ typeDefs, endpoint: http://localhost:4466, models: [], })构造Client需要三个核心配置对应 types.ts 中的ClientOptions配置项类型作用typeDefsstringGraphQL Schema 的 SDL 字符串Client构造时通过buildSchema(typeDefs)编译为内存 Schema见 Client.tsendpointstringGraphQL 服务地址用于创建BatchedGraphQLClient与 WebSocketSubscriptionClientmodelsModel[]模型元信息{ name, embedded }决定嵌入式类型的展开行为测试对查询文档生成类用例统一通过辅助函数取回生成的 AST 并打印为快照function getQueryDocument(client) { return client.getDocumentForInstructions( Object.keys(client._currentInstructions)[0], ) }其原理是链式调用如client.users()并不会立即发请求而是把每一步调用记录为一条Instruction字段名、参数、GraphQL 字段定义、类型名写入_currentInstructions随后由getDocumentForInstructions将指令序列编译成完整的 GraphQL 文档 AST见 Client.ts。快照里print(document)的输出就是这套编译器的最终产物。三、自动非标量子字段选择__typename的兜底机制这是整个快照报告的核心主题。Prisma Client 是查询生成器型客户端当调用方没有显式指定要选择哪些字段时它必须自动为每个非标量字段生成一个合法的子选择集否则生成的 GraphQL 文档就是非法的。3.1 基础兜底无标量字段时的__typename快照automatic non-scalar sub selection{ users { __typename } }对应测试中User类型只有house: House!一个非标量关系字段调用client.users()后编译器发现users字段的 selectionSet 为空且其深层类型是对象类型便自动填入唯一的合法占位字段__typename。这一逻辑实现在 Client.tsif ( node.selectionSet.selections.length 0 type instanceof GraphQLObjectType ) { node.selectionSet.selections [ { kind: Field, name: { kind: Name, value: __typename }, arguments: [], directives: [], }, ] }3.2 枚举与标量字段被自动展开当对象类型含有标量或枚举字段时getFieldAstClient.ts会把它们全部挑选出来automatic non-scalar sub selection and enumsUser含type: UserType!枚举字段调用client.user().type()生成{ user { type } }automatic non-scalar sub selection and scalarsUser含name: String!调用client.user().name()生成{ user { name } }字段过滤的核心是isScalarClient.ts通过getDeepType剥离NonNull/List包装后判断底层类型是否为GraphQLScalarType或GraphQLEnumType非标量字段中只有嵌入式模型embedded: true才会被默认展开其余关系字段一律过滤掉仅当调用方显式导航时才会进入子选择。3.3 关系字段的自动子选择快照automatic non-scalar sub selection for relation展示了跨关系导航时的场景调用链为client.house({ id: id }).user()生成的文档同时演示了参数变量化 关系自动兜底query ($where: HouseWhereInput) { house(where: $where) { user { __typename } } }这里user是User!非标量关系字段调用方没有继续选择其子字段于是同样由__typename兜底。3.4 Relay Connection 的特殊展开规则Prisma 的列表查询返回 Relay 风格 Connection 对象编译器对这类类型做了专门处理。判断依据是isConnectionTypeNameClient.ts类型名以Connection结尾且不等于Connection本身。带标量的 Connection快照... for a connection with scalars{ housesConnection { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } edges { node { id name } cursor } } }编译器自动展开了pageInfo的 4 个字段、edges的node其标量字段id/name与cursor。这依赖 connectionNodeHasScalars.ts 的判断递归找到Connection - edges - node的深层类型若node类型存在标量字段则返回true。无标量的 Connection快照... without scalars当User类型只有关系字段house时{ usersConnection { __typename } }这里isConnectionTypeName(fieldName)为真且relayConnectionHasScalars为假getFieldAst直接返回不含 selectionSet 的节点Client.ts随后由 3.1 的兜底逻辑补上__typename。从源码结构看这套 Connection 展开规则还包含订阅场景的previousValues/node保留逻辑Client.ts即订阅 payload 的结构化展开与查询类似只是允许的字段集合不同。四、类型导航与嵌入式类型models配置如何影响查询形状models数组中每个模型都带有embedded标记它直接决定了关系字段是否被默认展开。以下四组快照恰好形成两组对比实验且它们的 Schema 完全一致唯一差异是models配置。4.1 related type非嵌入式关系默认不展开User拥有posts: [Post!]!关系字段models中Post标记为embedded: false调用client.user()生成{ user { id } }id是User唯一的标量字段posts因非嵌入式被过滤所以 selectionSet 不为空、__typename兜底不会触发。4.2 deep related type显式导航进入关系调用链变为client.user().posts()编译器沿指令链下钻到Post类型展开其标量字段content{ user { posts { content } } }对比 4.1 可以看出非嵌入式关系字段不会自动展开但调用方一旦显式导航编译器就会为最深层对象生成字段选择。4.3 embedded type嵌入式类型自动整体展开models中Post标记为embedded: true此时同样的client.user()调用生成的文档完全不同{ user { id posts { content } } }posts虽然是非标量字段但因为Post是嵌入式模型被getFieldAst的过滤逻辑Client.ts判定为需要默认展开于是其全部标量字段content被自动挑选出来。4.4 nested embedded type嵌入式类型递归展开当嵌入式类型内部又嵌套嵌入式类型时Post.meta: PostMetaPostMeta标记为embedded: true展开会递归进行{ user { id posts { content meta { meta } } } }从源码结构看这正是getFieldAst对node.selectionSet.selections逐字段递归调用自身的结果Client.ts每个被保留的字段都会以其深层类型继续调用getFieldAst直到只剩标量字段为止。isEmbedded的判断依据则是模型名匹配Client.ts。五、参数变量化top level args与nested argsPrisma Client 会把传入的参数统一转换为 GraphQL 变量而不是内联为字面量。两组快照分别验证了扁平与嵌套结构的参数。5.1 top level argsPost类型含id、title、content三个标量字段根字段签名为post(where: PostInput!): Post调用client.post({ id: test })生成query ($where: PostInput!) { post(where: $where) { id title content } }注意三件事调用方传入的{ id: test }被包装为{ where: ... }——这是buildMethods中的隐式约定对Query/Subscription根字段若其只有一个参数则把实参包装为{ where: realArgs }Client.ts对Mutation则按create/delete前缀分别包装为{ data }或{ where }实参值被抽取为变量$where类型直接取自 Schema 中对应入参的astNode.typePostInput!Post的全部标量字段id/title/content被自动选中。5.2 nested args入参类型存在嵌套结构PostInput.author: AuthorInput!调用client.post({ author: { firstName: Lydia, lastName: Hallie } })生成query ($where: PostInput!) { post(where: $where) { id title content } }快照只记录文档变量值{ author: { firstName: Lydia, lastName: Hallie } }在运行时通过generateSelections返回的variables对象与文档一并发送Client.ts。变量化处理中还有一处细节同名参数重复出现时会通过variableCounter生成name_1、name_2等后缀避免变量名冲突Client.ts。六、extractPayload响应解包的四个快照与查询文档生成相对的另一半是响应解包。Prisma Client 期望链式 API 的最终结果恰好落在指令链的末端因此服务端返回的嵌套 JSON 需要按指令链逐层剥壳。相关快照记录了client.extractPayload(result, instructions)的输出测试中指令传[{}, {}]之类空对象即可因为此时仅测试解包逻辑。6.1 顶层数组调用链指向列表字段users返回[{id, name}]解包结果[{id:1,name:Alice},{id:2,name:Bob}]6.2 嵌套数组与嵌套对象数据为user.houses数组与user.house对象两种嵌套形态时解包分别得到[{id:1,name:My House},{id:2,name:Summer House}]{id:1,name:My House}6.3 服务端返回 null当服务端返回{ user: null }时解包结果为字面量null。6.4 解包算法的源码实现extractPayload的核心逻辑在 Client.ts大致分三步extractPayload(result, instructions) { let pointer result let count 0 while ( pointer typeof pointer object !Array.isArray(pointer) count instructions.length ) { pointer pointer[Object.keys(pointer)[0]] // 沿指令链逐层下钻 count } // ... 对 __typename-only 对象的清洗 return pointer }下钻剥壳在对象且未达指令链深度时不断取第一个键的值下钻如result.user.houses直到命中数组、null或指令链末端数组清洗若最终指向非空数组且元素形如{ __typename: ... }仅一个键则替换为同长度的{}数组——这一行为针对 prisma/prisma#3309 所描述的输出形状问题源码注释中明确引用了该 issueClient.ts对象清洗对单个{ __typename }对象同样替换为空对象{}但使用 fragment$fragment时跳过清洗因为 fragment 场景需要保留__typename。此外订阅结果通过mapSubscriptionPayload复用同一套extractPayload对每个推送事件逐条解包Client.ts因此上述四个快照同样适用于订阅场景。七、这些快照对开发者的实战价值7.1 调试真实查询Client构造函数支持debug选项开启后会在执行前把打印后的查询文档与变量输出到控制台Client.ts。当你怀疑 Prisma Client 生成了意外形状的查询时可以直接开启它再对照本文的快照样本判断行为是否符合预期。7.2 可复现的测试方法论Client.test.ts展示了一种高度可复现的测试模式用内存typeDefs构造Client链式调用触发指令收集再用getDocumentForInstructions提取 AST 并与快照比对。如果你要为自己的客户端封装做类似测试可以完全照搬这一套流程——无需真实 GraphQL 服务endpoint 仅为占位测试就能锁定查询生成逻辑的行为。7.3 与生成器的配合本包的公开入口 index.ts 还导出了JavascriptGenerator、TypescriptGenerator、FlowGenerator、GoGenerator等代码生成器以及makePrismaClientClassmakePrismaClientClass.ts用于把typeDefs/endpoint/models预绑定成一个可直接实例化的客户端类。运行时行为与生成代码的行为共享同一套Client核心因此本文剖析的快照逻辑对使用任何语言生成器的 Prisma Client 都成立。八、总结Client.test.js.md这份 AVA 快照报告虽然是一份自动生成的副产物却以 16 组精确到字符的 GraphQL 文档与 JSON 输出完整锁定了prisma-client-lib运行时两大核心行为查询文档生成链式指令被编译为合法 GraphQL 文档——标量/枚举字段自动展开、非标量字段以__typename兜底、Relay Connection 按pageInfo/edges/node/cursor结构展开、嵌入式类型递归整体展开、参数统一变量化响应解包按指令链下钻剥壳并对__typename占位对象做清洗保证最终结果形状与调用链语义一致。配合 Client.test.ts 与 Client.ts 阅读你可以把这套快照从一堆输出还原为一套可推导、可验证的编译器规则并在自己的项目中用同样的方法测试与调试客户端查询。【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址: https://gitcode.com/gh_mirrors/pr/prisma1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考