E2 · 出版卷 24

数据契约与互操作性

模式版本、兼容性、验证与导出

学习目标

  • 解释为什么模式版本、兼容性、验证与导出需要显式语义建模。
  • 设计在交换过程中保留“数据契约与互操作性”含义的身份、关系与约束。
  • 区分硬性发布质量门、诊断指标与解释选择。
  • 使用合成证据产出一个版本化契约、兼容矩阵与可独立核验的符合性报告。

只有当学习者能够为模型和发布决定同时辩护时，本章才算完成。没有证据、测试或声明限制的整洁模式仍是未经验证的设计。考核成果必须让假设可见，并区分来源主张与派生结论。

决定情境

契约应定义必需字段、语义标识符、类型、单位、值状态、关系、约束、错误行为、版本政策与服务预期。变更按使用者影响分类。兼容性具有方向：新生产者配旧使用者，与旧生产者配新使用者可能表现不同。

从决定记录开始：写明预期用途、所需证据、错误后果、可接受不确定性以及有权接受残余风险的角色。随后检查拟议模型能否在不依赖文件名惯例、行顺序、无文档默认值或个人记忆的情况下回答决定问题。这样可避免技术选择掩盖缺失的语义要求。

同一记录可能适合一种用途而不适合另一种用途。快速探索视图可以容忍正式交换发布不能接受的条件。因此，适用性应针对用途、契约版本与质量门声明，而不能永久贴在数据上。

核心概念

数据契约是生产者与使用者之间关于含义、结构、质量和运行行为的版本化约定。当独立实现能够交换符合约定的数据并保留预期含义时，才算证明互操作；两个系统都能打开同一文件并不足够。

本章工作范围是模式版本、兼容性、验证与导出。对范围内每个项目，都要区分对象本身、来源使用的标签、关于它的主张以及承载主张的记录。身份不等于显示名称，数值不等于单位，观测不等于模型，“当前”也不等于“有效”。这些区分为更正、不确定性与竞争解释提供明确位置。

良好的语义设计应先能用句子解释，再进行编码。每个句子都识别主语、属性或关系、宾语或结果，以及主张成立的上下文。物理表和文件是这些句子的投影，而不是含义来源。

语义模型

契约应具有标识符和不可变版本。每个版本包含逻辑模式、词汇依赖、验证规则、示例、变更日志与兼容性声明。符合性报告应标识契约版本、验证器版本、测试用例、失败项和被评估工件指纹。

用七个问题检验每种拟议记录：什么具有身份？它是什么类型？主张了哪个属性或关系？适用哪些时空上下文？哪个状态或限定符修饰主张？哪些证据支持它？哪个版本和活动产生了当前存储表示？缺失答案都应成为显式契约缺口。

规范化用于分离独立事实，而不是追求最多表数。只要身份、约束与来源保持显式，紧凑嵌套对象也可以语义健全；相反，如果关系和单位只存在于文档或应用代码中，即使高度规范化的数据库仍可能含糊。

约束与不变量

| 不变量 | 可执行或审查测试 | | --- | --- | | 版本必须显式 | 每个载荷或分发都标识其契约版本。 | | 按方向测试兼容性 | 测试受支持的生产者—使用者版本组合。 | | 语义变化必须分类 | 熟悉的字段名不能掩盖含义或单位变化。 | | 验证失败可采取行动 | 报告路径、规则、观测值与预期条件。 |

不变量是在存储、导出、更正与再处理过程中必须始终成立的条件。应尽可能在权威边界实施，并在交换边界重复检查。记录规则标识符、版本、严重级别、评价范围、观测值与结果，使失败可复现。

硬性质量门保护身份、语义有效性、必需来源与授权使用；诊断检查揭示异常值或模式，但需要解释。没有经审查规则和保留的源证据，不得把诊断阈值直接转化为删除或更正。

定量推理

可用兼容矩阵 K_{ij} 表示生产者版本 i 与使用者版本 j 的组合，状态可为支持、存在声明损失的支持和不支持。符合率 C = n_p / n_t 可汇总通过测试数，但必须保留硬性失败和测试覆盖信息。

每个比率都应声明分子、分母、排除项与评价时间。当汇总可能隐藏局部失败时，按来源、实体类型、契约版本或处理运行分层报告。百分比应同时附计数，避免很小分母造成的表面巨大变化被忽略。

精度属于含义的一部分。不能只因存储类型允许就增加小数位，也不能在没有声明容差和测试时舍入身份、区间或坐标字段。定量摘要支持发布决定，但不能替代语义审查。

证据与不确定性

互操作证据包括共享夹具、边界情况、无效情况、往返测试与独立使用者结果。示例载荷是可执行测试，而不是装饰性文档。解析后仍应测试语义不变量，因为单纯模式有效可能仍接受错误单位或关系。

证据包应包含保留的来源引用、采集或主张上下文、适用方法、验证结果、审查决定及派生物链接。当分类会改变处理方式时，把不确定性区分为观测、语义、结构、参数或政策相关。“未知”在证据不足以支持更强主张时是有效状态。

矛盾证据应保持可用。模型可以选择一条当前主张，但要保留理由、竞争主张与生效时间。这样才能支持后续重解释，而不假装早期证据从未存在。

接口与存储

导出端点或作业接收所请求的契约与格式配置，随后返回符合要求的数据包或结构化拒绝，不得悄然降级。每个发布导出都应附处理清单、模式、词汇版本、验证报告与内容指纹。

接口设计应从逻辑契约向外展开。在选择序列化前，先指定标识符、类型、基数、单位、值状态、坐标与时间参考、版本协商、验证行为和结构化错误；物理表示随后声明它如何映射这些逻辑元素。

存储优化可以分区、压缩、索引或缓存数据，但不能改变身份或悄然移除上下文。派生表示应指向不可变输入与处理清单。缓存携带新鲜度和契约版本信息，绝不被当作唯一证据副本。

治理与访问

变更流程应识别受影响的生产者与使用者，分类兼容性，提供迁移并记录停用。破坏性版本可在过渡期共存，但每个版本都保持显式。契约维护分配给角色，不能依赖某个未指明个人的记忆。

治理通过角色名称、审查状态与版本化决定表达，而不依赖任何特定组织。应定义谁可以提议、验证、批准、替代和撤回每类受治理资源。审计记录保存角色和事件，同时避免不必要的个人数据。

对源证据与派生物应用最小必要访问。访问控制不能删除理解获授权发布所需的标识符、血缘或质量元数据。政策未解决时，应以明确理由和升级路径隔离输出。

集成检查点

契约版本连接经过测试的生产者与使用者
契约版本连接经过测试的生产者与使用者

图中概括本章控制流。应从源证据开始，经过语义结构与验证，读到可供决定使用的成果。每个箭头都应对应声明关系或转换，每个边界都应有契约，每个发布节点都应具有身份、版本与来源指针。

把一个版本化契约、兼容矩阵与可独立核验的符合性报告加入持续演进的合成数据包。验证早期成果仍可解析，并确认新模型没有覆盖前几章引入的观测、标识符、数值或版本。记录每项变化的假设。

合成算例

一个合成契约先增加可选置信字段，随后在另一个提案中改变浓度单位。学习者把前一变更判为对可忽略未知字段的使用者兼容，而把单位变化判为破坏性。测试夹具覆盖四种生产者—使用者版本组合，导出对不支持组合明确拒绝。

按四轮完成算例：

  1. 保留接收记录并写出预期决定，不先进行任何更正。
  2. 识别实体、主张、上下文、不确定性与政策约束，标记每个未解决项。
  3. 应用版本化规则，创建派生物，并记录准确转换与验证证据。
  4. 给出接受、拒绝或隔离决定，并说明独立审查者如何复现。

由于示例全部为合成内容，其数值只用于演示方法。重要结果是从接收证据到有依据决定的链条。若缺少必需事实，解答应记录缺口，而不是制造一个看似合理的值。

练习任务

编写两个版本的合成样品结果契约。建立有效、边界与无效夹具，分类每项变更，填写方向性兼容矩阵，执行验证与往返测试，再生成使用者可独立核验的符合性报告。

采用以下验收标准：

  • 所有必需标识符与引用都解析到声明类型。
  • 每次转换都保留接收证据并记录派生关系。
  • 无效、未知与不适用状态保持区分且可机器测试。
  • 输出标识所用契约、词汇与处理版本。
  • 第二位读者无需私下知识即可复现验证结果。

提交源快照、编写的契约或模型、验证输出、派生物、清单和简短决定记录。截图本身不足以证明准确输入、版本或规则执行。

常见失效模式

  • 载荷未携带契约版本。
  • 仅凭一个成功的顺向文件就声称兼容。
  • 单位变化却保持相同字段名与版本。
  • 导出器悄然删除不支持的属性。

这些失败具有共同模式：便利的表示被误认为已经验证的含义。诊断时应找到假设最早变为隐式的边界。修复时恢复源证据，把假设转为版本化字段或规则，重新运行依赖转换，并通过替代而非覆盖发布受影响成果。

不要用无文档默认值修复失败。带明确缺失依赖的阻止结果，比一个无法重建含义却看起来完整的结果更安全、更可复用。

复习问题

  1. 为什么兼容性具有方向？
  2. 哪些语义变化属于破坏性变更？
  3. 什么使示例载荷成为可执行规范？
  4. 不支持的导出请求应如何失败？

对每个答案，都要指出适用不变量、评价所需证据以及不变量失败时的发布行为。高质量答案会区分科学不确定性与语义缺失，也会区分可恢复警告与硬性契约违规。

来源与延伸阅读