Prisma 归一化数据格式（NDF）完全指南：服务间数据导入导出的中间 JSON 格式

后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载本篇技术指南围绕 Prisma 服务中数据导入导出的核心中间格式——归一化数据格式Normalized Data FormatNDF展开系统讲解其 JSON 结构、三种 value typenodes/lists/relations的字段约定与完整示例并结合当前仓库中prisma import/prisma export命令的源码实现深入剖析 NDF 在导入校验、导出分页与压缩打包等环节中的实际运作方式。读完本文你将能够手写合法的 NDF 数据文件理解 Prisma CLI 导入导出的底层调用链并能够依据校验规则定位并修复数据格式错误。NDF 是什么导入导出之间的中间格式The Normalized Data Format (NDF) is used as anintermediatedata format for import and export in Prisma services. NDF 为 JSON 定义了一种特定的结构规范它既不直接对应数据库的行也不直接对应 GraphQL 查询结果而是把服务中的数据拆解为三类互补的值类型value type从而让数据可以在不同 Prisma 服务、不同环境本地 / 云端 / 自建集群之间无损迁移。在 Prisma 的数据迁移实践中prisma export产出的.zip内部正是 NDF 文件按nodes/、lists/、relations/三个目录组织而prisma import消费的也正是这种格式。相关的完整命令参考见 01-Data-Import.md 与 02-Data-Export.md。NDF 的三种值类型当使用 NDF 时数据被拆分到三种不同的值类型中Nodes节点包含节点的标量字段scalar fields数据Lists列表包含节点的列表字段list fields数据Relations关系包含通过关系字段relation fields连接两个节点的数据。这种拆分是 NDF 的核心设计把一个对象拆成它的标量部分 它的列表部分 它与其他对象的关系三者分别独立成文档最终由id字段与_typeName字段互相锚定、重新组装。顶层结构valueType valuesNDF 文档是一个 JSON 对象只包含两个顶层键valueType表示文档中数据的值类型取值只能是nodes、lists或relationsvalues实际数据是一个数组其元素结构必须符合对应的值类型约定。该结构在仓库源码中有精确的类型定义types.tsexport type ValueType nodes | relations | lists export type ScalarType number | string | boolean | null export interface Node { _typeName: string id: string [fieldName: string]: ScalarType | ScalarType[] } export interface RelationNode { _typeName: string id: string fieldName: string } export type RelationTuple [RelationNode, RelationNode] export interface ImportData { valueType: ValueType values: Node[] | RelationTuple[] }下面所有示例均基于如下数据模型与 Normalized-Data-Format.md 中的示例一致type User { id: String! unique firstName: String! lastName: String! hobbies: [String!]! partner: User }valueType 为 nodes 时的结构当valueType为nodes时values数组内每个对象的结构如下{ valueType: nodes, values: [ { _typeName: STRING, id: STRING, scalarField1: ANY, scalarField2: ANY, ..., scalarFieldN: ANY }, ... ] }其中_typeName与id均为字符串_typeName指数据模型中 SDL 类型的名称scalarFieldX占位符是该 SDL 类型上各标量字段的名称。例如下面的 JSON 文档可用于导入两个User节点的标量值{ valueType: nodes, values: [ {_typeName: User, id: johndoe, firstName: John, lastName: Doe}, {_typeName: User, id: sarahdoe, firstName: Sarah, lastName: Doe} ] }从源码校验逻辑Validator.ts可以进一步确认nodes的约束_typeName必须存在且必须是数据模型由 SDL 解析出的类型集合中真实存在的类型id必须存在且为字符串数据模型中标为必填NonNull的标量字段必须全部出现在对象中否则抛出 lacks the following properties 错误出现数据模型中不存在的字段会被判为未知字段而报错createdAt、updatedAt、id除外字段值必须匹配其声明的标量类型见下文类型校验器小节。valueType 为 lists 时的结构当valueType为lists时values数组内每个对象的结构如下{ valueType: lists, values: [ { _typeName: STRING, id: STRING, scalarListField: [ANY] }, ... ] }_typeName与id同样为字符串scalarListField占位符是该 SDL 类型上列表字段的名称。需要注意与标量字段不同每个对象只能为一个列表字段提供值——即一个lists文档中的对象只能携带一个列表键。例如下面的 JSON 文档可用于导入两个User节点的hobbies列表字段值{ valueType: lists, values: [ {_typeName: User, id: johndoe, hobbies: [Fishing, Cooking]}, {_typeName: User, id: sarahdoe, hobbies: [Biking, Coding]} ] }源码中对应的校验Validator.ts 与 Validator.ts保证了这种单向约定在nodes文档中提供列表值会报错List value ... mustnt be provided in a nodes definition在lists文档中提供标量值也会报错lists文档中的值必须是数组数组内每个元素再按元素标量类型逐一校验。valueType 为 relations 时的结构当valueType为relations时values数组内每个元素的结构如下{ valueType: relations, values: [ [ { _typeName: STRING, id: STRING, fieldName: STRING }, { _typeName: STRING, id: STRING, fieldName: STRING } ], ... ] }_typeName、id、fieldName均为字符串。_typeName指向数据模型中的一个 SDL 类型fieldName是该类型上的关系字段名。由于关系数据的目的是通过一条关系连接两个节点values中每个元素本身是一对pair——写作一个恰好包含两个元素的数组这与nodes、lists中单个对象的形式不同。例如下面的 JSON 文档通过partner关系字段在两个User节点之间建立一条关系{ valueType: relations, values: [ [ { _typeName: User, id: johndoe, fieldName: partner }, { _typeName: User, id: sarahdoe, fieldName: partner } ] ] }源码中的关系元组校验Validator.ts非常严格每个 tuple 必须是数组且长度必须恰好为 2Relation tuple must have 2 nodestuple 内两个节点都必须满足_typeNameid约束至少其中一个节点必须带fieldName且该fieldName必须真实存在于对应类型的字段定义中否则报 points to a non-existing fieldName 错误。导入导出流程中的 NDF源码视角NDF 不只是规范文档它贯穿了 Prisma CLI 导入导出的完整执行链路。本仓库中相关实现位于 cli/packages/prisma-cli-core/src/commands/import 与 cli/packages/prisma-cli-core/src/commands/export 目录下。导出分页拉取并按 valueType 落盘prisma export的核心是 Exporter.ts。其关键流程download 方法为在工作目录下创建.export/临时目录并预建nodes/、lists/、relations/三个子目录makeDirs依次以nodes→lists→relations的顺序调用导出服务接口每次请求携带{ fileType, cursor }其中cursor是{ table, row, field, array }四元组用于分页游标ExportCursor每次返回的数据被包装成标准 NDF 文档写入编号文件JSON.stringify({ valueType: fileType, values: data.out.jsonElements })文件名按六位前导零编号000001.json、000002.json……写入对应类型目录downloadFiles当游标之和小于 0 时停止拉取随后将.export/目录压缩为最终交付的.zip文件zipIt并清理临时目录。因此一份prisma export产物的内部结构天然就是 NDF 的组织形态export.zip ├── nodes/000001.json # valueType: nodes ├── lists/000001.json # valueType: lists └── relations/000001.json # valueType: relations导入解压、逐类型校验与按序上传prisma import的核心是 Importer.ts。其执行流程upload 方法为若传入的是.zip路径则先解压到.import/目录unzip若传入的是目录则直接使用用 glob 收集nodes/、lists/、relations/三个目录下的全部.json文件getFiles本地校验对每个文件逐一JSON.parse后交给Validator校验validateFiles。如果三个目录一个文件都没有直接报错提示目录结构不合法错误信息中同样指向 NDF 文档按序上传严格按nodes→lists→relations的顺序逐文件上传到服务端。这个顺序是硬性要求——必须先有节点数据才能挂接列表字段与关系断点续传上传进度通过state.json记录{ nodes, lists, relations }三个数字文件名中的数字编号如000001.json→ 1用于比对已导入过的文件会跳过Skipping file ... (already imported)从而支持中断后继续导入saveState / getState / getNumber。导入前的 NDF 校验器Validator.ts 是 NDF 数据质量的守门员。它以数据模型的 SDL 字符串为输入用 GraphQL 解析器将其转为 AST再据此构建每个类型的字段映射、必填字段清单、枚举取值表astToTypes / astToEnums随后对三种 value type 分别执行校验。其中内置的标量类型校验器validators值得注意SDL 类型校验规则源码实现ID/String必须是字符串isStringInt可解析为数字且(x | 0) x即为整数Float必须是数字isNumberDateTime必须是字符串且匹配 ISO-8601 风格正则\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d\.\d([-][0-2]\d:[0-5]\d\|Z)Boolean必须是布尔值isBooleanJson必须是对象typeof value object自定义枚举值必须包含在 SDL 枚举定义中makeEnumValidators这些规则在测试中有充分的覆盖例如 Validator.test.ts 验证了缺失_typeName、未知_typeName都会抛错Validator.test.ts 验证了id为数字 25 时抛错、为字符串25时通过。仓库内置的真实 NDF 示例仓库的导入测试 fixturecli/packages/prisma-cli-core/src/commands/import/fixtures/basic提供了一套可直接对照学习的完整 NDF 数据数据模型 types.graphqlPost含title、description、tags: [String!]!、state: PostState!枚举、comments关系与Comment含text、post关系节点数据 nodes/000001.jsonvalueType: nodesPost携带标量字段与枚举字段stateComment只携带text列表数据 lists/000001.jsonvalueType: lists每个Post对象仅携带一个列表键tags关系数据 relations/000001.jsonvalueType: relations每个 tuple 由Post.comments与Comment.post这一对关系字段构成进度状态 state.json初始状态为三个计数器均为 0。生成该 fixture 的脚本见 makeData.ts其数据生成逻辑与 NDF 的标量 / 列表 / 关系三分离模型一一对应适合作为手写 NDF 数据的参考模板。手写 NDF 的实践要点综合规范文档与源码实现在手动构造 NDF 文件时应当遵循以下要点顶层结构固定每个 JSON 文件都必须且只能包含valueType与values两个键valueType只能取nodes、lists、relations三者之一三件套齐备一次完整的导入需要同时提供nodes/、lists/、relations/三个目录内容可以为空文件集但目录结构必须存在否则 CLI 会报目录结构错误id是锚点三种 value type 都通过_typeNameid定位到具体节点id必须为字符串且与数据库中该节点的唯一标识一致类型正确性标量字段值必须与 SDL 声明的类型匹配如DateTime需符合 ISO-8601 格式、枚举值必须合法否则会在本地校验阶段即被拦截列表与标量互斥列表字段只能出现在lists文档中且每个对象只放一个列表字段标量字段只能出现在nodes文档中关系成对出现relations的values中每个元素必须是恰好两个节点的数组两个节点分别从关系两端如Post.comments与Comment.post描述同一条关系上传顺序不可变即便自行编写导入脚本也应遵循服务端 nodes → lists → relations 的依赖顺序先有节点再挂列表和关系。小结归一化数据格式NDF是 Prisma 数据导入导出体系的基石它以nodes/lists/relations三种值类型把数据库内容正交切分用统一的_typeNameid作为跨文档的关联锚点配合 CLI 的本地校验、按序上传与断点续传机制实现了数据在不同 Prisma 服务之间的可靠迁移。无论是阅读prisma export产物、手工构造prisma import输入还是排查导入报错理解本文所讲的 NDF 结构、字段约束与校验规则都能直接派上用场。进一步的实践入口完整的导入导出命令用法见 01-Data-Import.md 与 02-Data-Export.mdCLI 命令参考见 prisma-import.md数据迁移的端到端工作流可参考 01-Data-Export--Import.md。赞分享后端数据库GraphQL【免费下载链接】prisma1 Database Tools incl. ORM, Migrations and Admin UI (Postgres, MySQL MongoDB) [deprecated]项目地址https://gitcode.com/gh_mirrors/pr/prisma1点击查看免费下载相关推荐Prisma Normalized Data Format (NDF) 完全指南结构化 JSON 实现数据导入导出的中间格式Prisma Normalized Data Format NDF 完全指南结构化 JSON 实现数据导入导出的中间格式 Normalized Data Fo后端数据库GraphQLPrisma 数据导入导出核心Normalized Data Format (NDF) 中间格式完全解析Prisma 数据导入导出核心Normalized Data Format NDF 中间格式完全解析 Normalized Data FormatNDF是后端数据库GraphQLPrisma 数据导出与导入实战使用 NDF 格式在服务与 stage 之间迁移数据Prisma 数据导出与导入实战使用 NDF 格式在服务与 stage 之间迁移数据 本教程基于 Prisma 开源仓库 prisma1 讲解数据导出与导后端数据库GraphQL上一篇Mac Mouse Fix终极指南3步将普通鼠标升级为macOS生产力神器下一篇Slang 编译目标Targets、能力Capabilities与配置文件Profiles完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考