E6 · 出版卷 28

API 与数据合同设计

资源、查询、分页、空间子集与版本

*资源、查询、分页、空间子集与版本*

API 边界上的资源、查询、分页、空间子集与错误合同
API 边界上的资源、查询、分页、空间子集与错误合同

学习目标

本课是通用、机构中立内容，不使用任何真实公司、个人、矿权、项目或可识别地点。通用角色只描述职责，SYN-ARCH 标识符明确表示合成教学证据。

  • 界定由“资源、查询、分页、空间子集与版本”治理的决定。
  • 在选择实现前建立相关边界、状态与合同模型。
  • 定义可测不变量、故障证据与安全发布后果。
  • 基于合成证据产出一份带可执行样例的版本化 API 与数据合同规范并为其权衡辩护。

决策边界

API 应围绕决定与稳定领域资源设计，而不是围绕界面或数据库表设计。对每个使用动作，定义资源身份、允许的查询、时空子集、返回表示、一致性预期、版本语境与失败含义。地图视口、审查队列与可复现分析即使引用相同观测，也可能需要不同表示。改变状态的命令应与检索证据的查询分开。边界必须说明响应何时完整、部分、过期、脱敏、近似或已被取代，避免把便利响应误当成权威证据。

核心概念

合同同时包含语法、语义与运行行为。语法描述字段和类型；语义定义身份、单位、坐标参考、空值、顺序与有效期；运行行为定义认证、限制、缓存、重试与错误。资源标识在不同表示之间保持稳定。集合端点公开有界过滤与确定性排序。分页属于一致性问题：变化数据上的偏移分页可能重复或遗漏记录，而绑定快照的游标可保留声明视图。空间子集参数必须说明坐标参考、轴顺序、边界包含规则、精度，以及几何是被裁剪、简化还是仅被选择。

系统模型与合同

把边界建模为资源模式、查询语法、响应封套与问题模式。资源携带稳定身份、表示版本、数据版本、有效期、来源链接与领域字段。集合响应携带快照身份、确定性顺序、分页链接或游标、返回数量与已知截断。空间请求包含显式参考与有界范围。问题响应使用稳定机器代码，并给出人类可读细节、受影响字段、可否重试、关联身份，以及在允许披露时指向被拒证据的链接。合同样例覆盖正常、空、部分、脱敏、过期、畸形、不支持版本与超限情况。

不变量与验收标准

| 不变量 | 测试证据 | 发布后果 | |---|---|---| | 每个响应都声明解释所需的数据版本与合同版本。 | 合同测试与反例记录 | 阻止发布 | | 集合分页在声明快照内具有确定性。 | 回放比较与摘要检查 | 隔离制品 | | 空间子集声明参考、轴顺序与边界语义。 | 基于角色的验收追踪 | 把决定返回为未解决 | | 问题响应携带稳定代码且不泄露受保护证据。 | 故障注入与恢复记录 | 保留上一已验证版本 | | 合同样例通过模式验证，并由生产端与消费端测试回放。 | 依据声明证据的领域审查 | 记录明确评审发现 |

量化工程

对声明的使用决定，把载荷效率量化为 P_e=B_{needed}/B_{transferred}，把过滤选择率量化为 S_f=n_{returned}/n_{eligible}，并连同序列化、压缩、缓存状态与几何复杂度报告。分页测试把全部页面的并集与声明快照比较，检查重复、遗漏与顺序。延迟预算按操作和响应类别使用百分位，而不是单一均值。限制应约束范围、要素数、顶点数、请求字段、页大小与计算代价。若更小响应删除了解释所需的来源、单位或不确定性，它并不更好。

数据质量、证据与不确定性

从代表性决定追踪与字段级证据词典推导合同。对每个字段记录定义、来源、单位、参考、允许状态、精度、来源链、敏感级别与变更政策。样例是可执行夹具，不是装饰片段：既要按模式验证，也要在生产端与消费端测试中回放。维护歧义标识、混合参考、缺失单位、分页边界重复、无效几何与翻页期间记录变化等反例。合同不能证明领域适用性；它只能保留并暴露该审查需要的证据。

互操作性与版本

把机器可读模式、端点语义、版本政策与规范样例作为一个经过评审的数据包发布。必填字段不能悄然变为可选；单位、参考语义或枚举含义不能在同一合同身份下改变。只有当消费端必须忽略未知可选成员且往返行为已明确时，新增字段才安全。弃用声明替代项、兼容区间与移除条件。摘要标识一次发布使用的确切合同包。数据版本与合同版本字段保持分离，因为新数据集快照不一定改变接口。

安全与专业责任

依据所请求版本与空间范围，对每项资源、字段与动作授权。即使记录被隐藏，集合数量、范围、错误与时序也可能泄露受保护信息，因此披露政策同时覆盖元数据和值。无限过滤、过度复杂几何、递归展开与昂贵排序组合应在执行前被拒绝。游标令牌应不透明、受完整性保护、有范围且会过期；不得嵌入凭证或暴露内部存储键。错误细节应支持纠正，同时不泄露秘密、查询结构或不可访问资源是否存在。

运行流程与可观测性

对每个受支持版本持续运行生产端与消费端合同测试。在不记录敏感载荷的前提下，观察请求类别、版本、结果类别、响应大小、百分位延迟、缓存结果、拒绝代码与重试行为。兼容性监测识别未知字段、不受支持版本与继续使用弃用途径的消费端。速率控制依据代价与后果，而不只依据请求数。发现合同缺陷时，应签发修正版，保留受影响证据窗口并通知依赖作业；不得在静默修改的模式下重新解释历史响应。

集成检查点

把“API 与数据合同设计”制品连接到本卷前面的架构。追踪一个合成对象从来源身份穿过新边界到达已审查输出，再把一个拒绝或故障追溯到最早被违反的不变量。更新架构决定记录，写明所选方案、备选方案、假设、证据、后果、责任角色、评审状态与重新考虑触发条件。只有另一位审查者无需口头说明即可重建成功路径与阻断路径，检查点才通过。

合成案例

SYN-ARCH-05 最初公开一个表形端点，使用偏移分页，并接受未说明坐标参考的可选边界框。审查中，一条插入记录推移后续页面，消费端漏掉一个区间。修订合同采用稳定资源身份、绑定快照的游标、显式参考与轴顺序、确定性排序、字段定义，以及对不支持版本的结构化拒绝。可执行夹具包含空子集与落在边界上的几何。回放证明每个合格身份恰好出现一次，脱敏测试则证明不可访问范围不会泄露。

练习与考核

  1. 哪项决定与证据证明每种资源和查询合理？
  2. 消费端如何知道一页是否完整且可重复？
  3. 哪些空间语义必须在每种表示中保留？
  4. 何种变化需要新合同版本而不只是新数据版本？

考核制品：一份带可执行样例的版本化 API 与数据合同规范。提交时附来源清单、验收证据、未解决风险，并简要说明为何没有选择一个合理备选方案。

常见失败模式

  • 照搬数据库表却不定义领域资源语义。
  • 在变化数据上使用没有快照合同的偏移分页。
  • 接受没有参考或轴顺序规则的空间范围。
  • 对畸形、禁止与不可用状态返回同一种笼统错误。
  • 改变字段含义却保留相同合同身份。

来源与延伸阅读