跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

验证范围

Aggrega 在四个不同的 schema 层上验证编写的内容。每一层覆盖不同的范围,在编译流水线的不同阶段运行,产生的错误形态也各不相同。遇到验证错误时,了解是哪一层拒绝了输入会很有帮助:同一个字段可能受多个层约束,而触发错误的层决定了要修复什么、在哪里修复。

本页介绍这四个层、它们在流水线中的位置、每层遵循的错误形态约定,以及当多个层作用于同一字段时各层如何相互作用。

四个层

第 1 层 — JSON Schema 信封

范围。 每个目录 YAML 的结构形态:apiVersion、kind、metadata.{name, version, description, maintainers, license, ...}、顶层 spec: 块,以及 schema 声明的各实体必填字段。每种实体类型(Aggregate、Component、Feature、Recipe、FeatureRecipe、Manifest、Plugin、Release、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary)都有自己的 JSON Schema,记录在 schema 参考中。Workload 在那里也有一个,它是该集合中唯一一种由作者写在另一个实体内部的类型——写在 Recipe 或 FeatureRecipe 的 workload: 块中,或写在 WorkloadLibrary 条目中——而不是作为独立的目录文件;无论写在哪里,都由同一信封检查约束,并且 aggrega validate 可直接接受 Workload 文件作为单实体目标。

验证时机。 在解析阶段(resolver / load),按文件进行。每个文档在加载时都会根据其种类的 JSON Schema 进行检查;schema 声明字段之外的键会在此处被拒绝,早于任何后续验证。

错误形态。 schema 不匹配会作为文档信封失败报告。其头部带有出错文档的类别——目录实体为 [CATALOG_ERROR E0215],Aggregate 为 [DEVELOPER_ERROR E0215],Release 为 [OPS_ERROR E0215]——消息会指出种类、文件、行和列、字段路径以及所违反的约束:

[CATALOG_ERROR E0215] <path>
document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schema

必填字段缺失和类型不匹配也以同样的形态呈现——spec.capability: missing required property: capability、metadata.version: type: 1 has type "integer", want "string"。

第 2 层 — 支柱 schema(schema: / featuresSchema / usesSchema)

范围。 实体携带的数据支柱——values、infra、parameters,以及由 featuresSchema 声明其槽位的 features: 挂载块和由 usesSchema 约束的 uses: 块。领域 2 实体(Component、Feature)在其 YAML 信封中嵌入 JSON Schema 2020-12 声明(内联的 spec.schema——紧凑形式或完整形式——或指向共享 SchemaLibrary 条目的 $ref:);领域 3 实体(Recipe、FeatureRecipe)在其自身的验证过程中使用已解析的 schema。

验证时机。 在解析阶段,JSON Schema 信封检查通过之后。编译器将实体编写的 schema: 与从 usesSchema 和 featuresSchema 声明自动生成的基础 schema 组合;组合后的 schema 对 Aggregate 中每个组件实例上由开发者提供的 values: / infra: / features: / uses: 块进行验证。

错误形态。 约束违规以消息形式报出,消息指明实体、支柱内的路径以及拒绝该值的规则——例如开发者将端口设置为 80,而 schema 规则要求 >=1024。

重新声明的 usesSchema 或 featuresSchema 条目不会产生组合失败。这两个范围按名称覆盖:子条目会整体替换基础条目,schema 和选择器一并替换,因此基础条目与子条目之间不存在需要报告的冲突。

第 3 层 — Provider 合成模式能力

范围。 由所绑定 provider 的合成模式能力门控约束:

  • 合成模式(workload:)的支持取决于所绑定 provider 的能力,而非是否存在 workloadSchema:绑定到无法合成的 provider 的 workload: Recipe 会在此处被拒绝。按照约定,标准库目录在具备合成能力的 provider 上声明 workloadSchema——位于 provider 渲染 Plugin 的 spec.provider.workloadSchema 上——作为文档化的转换契约。该 workloadSchema 主体本身会在 Plugin 加载时编译为 JSON Schema 2020-12,这是一道结构性准入门控,会在加载时而非渲染时拒绝格式错误的 schema。

验证时机。 在基础渲染阶段,Recipe 自身的 valuesMapping 解析完成之后。第 3 层根据 provider 能力对合成模式分派进行门控。

错误形态。 能力拒绝归属于目录编写领域,因此其报告以方括号标头开始,标头包含该类别和出错的实例。消息以陈述该条件的固定句子开头,随后指明节点、provider 以及该 provider 支持的类型:

[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesized

[CATALOG_ERROR] 标头表示出错的是目录实体,而不是开发者的 Aggregate。在终端上,标头还包含该条件的短代码——此处为 E0265,可通过所有条件的表格查得——且消息移到单独的缩进行;上面的单行形式是写入日志的形式。开头的句子对每个条件都是固定的,因此在基于文本处理时应匹配这一部分;其后的内容随出错节点而变化。

一项相关的防护措施保护 provider 分派本身:当多个 provider 渲染 Plugin 服务于同一目标时,工作区通过 .aggrega-config.yaml 中的 provider 绑定消除歧义,该绑定在 aggrega pull 时选定并记录在锁文件中。没有绑定且恰有一个候选 Plugin 时,使用该候选;没有绑定且有多个候选时,构建会显式中止,并列出候选插件。歧义在使用处按工作区消除,而不是通过目录范围的唯一性规则。

按 provider 的 Workload 内容验证。 渲染 provider 的 Plugin 的 spec.provider.workloadSchema 记录该 provider 如何转换 Workload,并将该 provider 标记为能够合成 Workload;它不验证任何内容。无论使用哪个 provider,每个 Workload 主体都会根据平台的 Workload schema 进行验证。

第 4 层 — 注解绑定值验证

范围。 在 Release 边界 / 边界组件或 Aggregate 子系统 / 组件实例上编写的注解值,前提是 mappings.features.annotations.<key> 下的 Manifest 绑定声明了通过 maps.infra 和/或 maps.values 点分路径列表进行路由。每条声明的路径沿目标 Feature 的 spec.schema.<pillar> 导航到一个叶属性;注解值在该叶上的贡献依据 Feature schema 声明的类型进行验证。验证通过 Feature 自身的 JSON Schema 2020-12 声明进行——绑定只声明路由,不声明验证片段。

验证时机。 在解析阶段的注解展开子阶段,位于 Manifest 绑定目标验证(确认每条声明路径都存在于所引用 Feature schema 中的目录加载检查)之后,并与针对显式挂载的第 2 层 schema 验证并行。对每个生效的按组件注解:将值解析为标量、结构化映射或显式的 null;按子键通过绑定中按支柱分组的 maps 声明进行路由,并执行侧与支柱的对应约束(Aggregate 侧触发 maps.values;Release 侧触发 maps.infra);依据 Feature schema 在所路由支柱上声明的类型验证每个叶的运行时值。多个子键错误会全部收集并输出,然后才中止。

错误形态。 该层的 schema 验证错误遵循第 2 层的形态——实体、路径(注解键加子键路由)、约束详情。侧与支柱的划分违规以及路由歧义失败归属于编写该注解值的文档,因此由 Aggregate 携带的错误以 [DEVELOPER_ERROR] 标头开始,由 Release 携带的错误以 [OPS_ERROR] 标头开始,两者都会指明注解键、所路由的支柱、编写侧以及源位置。

跨层统一的错误格式约定

四个层共享一项可观察的约定:每个可归因于 Aggrega 的验证失败都带有“路径加理由”的形式,指明出错的字段以及拒绝它的约束。

  • 第 1 层(信封)和第 2 层(支柱 schema)的错误以相同的方括号头部开头——即出错文档的类别和该条件的短代码,例如目录实体中信封不匹配时为 [CATALOG_ERROR E0215],支柱 schema 拒绝的 Aggregate 值为 [DEVELOPER_ERROR E0168]——其后是字段路径和所违反的 schema 规则。
  • Layer 3(Provider 来源 / Workload)的错误按定义可归因于目录实体——是 Recipe + Provider 这一组合编写了拒绝开发者输入的 schema。这些错误归属于目录编写领域,归属信息通过诊断信息中带方括号的开头传达给你,而不是作为写入消息中的一个词:一条终止报告以 [CATALOG_ERROR E0nnn] 开头,其中类别指明领域,短代码指明具体条件。请匹配短代码,它一经发布便固定不变。
  • Layer 4(注解绑定值验证)的错误遵循 Layer 2 的形式——执行验证的 Feature schema 位于所引用 Feature 的 spec.schema 中,运行时值经由 Manifest 绑定的 maps 路由流入该 schema,进行逐叶子节点的类型检查。

带 Aggrega 前缀的哨兵错误及产生它们的界面的完整清单,请参见 errors/error-translation.md。逐个错误的目录([CATALOG_ERROR] Recipe 形式规则,按条件逐一列出),请参见 errors/fatal-halts.md。

字段重叠时各层的交互

同一个编写的字段可能受多个层约束。Workload 的 containers.<name>.ports.<port> 由第 1 层作为 Workload schema 结构形态的一部分进行检查;第 2 层触及不到它,因为 Workload 内容是 Recipe 内部的结构,而不是 Component 的支柱;而 provider 的 workloadSchema 什么也不检查——因此诸如拒绝低于 1024 的端口这类约束应放在 Component 的 schema 或断言中,由触发的那一层指出它。

流水线位置汇总

层范围运行阶段错误前缀
1 — JSON Schema 外壳结构形态(apiVersion、kind、metadata、顶层 spec)解析(加载)文档的类别加上 E0215——目录实体为 [CATALOG_ERROR E0215]
2 — 支柱 schema(schema: / featuresSchema / usesSchema)按支柱的数据校验(values、infra、secrets、uses)解析(外壳之后)编写文档的类别加上该条件的短代码——Aggregate 值为 [DEVELOPER_ERROR E0168]
3 — Provider 能力门控合成模式支持(provider 能力)基础渲染[CATALOG_ERROR]
4 — 注解绑定值校验通过 Manifest 绑定的 maps 路径路由到目标 Feature 的 spec.schema 中的注解值贡献解析中的注解展开子阶段,与第 2 层并行schema 校验错误;side 与支柱冲突 / 路由歧义的错误以编写文档自身的领域开头——来自 Aggregate 的为 [DEVELOPER_ERROR],来自 Release 的为 [OPS_ERROR]

交叉引用