extends 与 implements
通过 extends 继承
目录实体(Component、Feature)通过 extends 关键字支持单继承,使平台架构师能够在共享的基础实体之上构建特化实体。YAML 信封深度合并对这两种类型是相同的:扩展实体上的元数据、标签和声明式结构表会覆盖基础实体中的同名键,嵌套映射则递归合并。两种类型的分歧在于数据支柱。
本页介绍目录类型,但声明 extends 的不只有这些类型。 Release 和 Manifest 也会声明它,二者都是彼此并列编写的部署侧文档,而不是由目录索引的实体——因此它们的引用指向文件而非目录实体,折叠的是编写层面而非 schema。相关内容请参阅 entities/release.md 和 entities/manifest.md。
Component 的 extends 组合结构,并整体继承支柱
对于 Component,extends 组合 metadata.labels、metadata.annotations、spec.featuresSchema(挂接槽位)、spec.usesSchema(拓扑插座)和 spec.inject(自注入允许列表,其条目按基础优先的顺序拼接且不重复)。三个数据支柱——values、infra、provides——不参与组合。扩展的 Component 不编写任何支柱内容:它写下字面标记 schema: inherited,并完全按照基础实体编写的样子接收其 schema: 块,在继承链的任何深度均如此。
已发布的 Component schema 规定该标记既是必需的也是排他的,并在文档加载时拒绝每一种偏离情况,且各有其专门的诊断:在声明了 extends: 的 Component 上于 schema: 下编写支柱内容;在此类 Component 上完全省略 schema:;以及在未声明 extends: 的 Component 上使用 schema: inherited。
由此产生两个后果,且二者方向相反:
- 键集合由基础实体决定。 扩展的 Component 不声明任何支柱键,因此它无法隐藏、删除或更改基础实体所声明键的类型,也不会添加自己的键。基础实体的实例与任何扩展它的实体的实例,都依据同一份支柱契约进行校验。
- 收紧约束移至
assertions:。 若特化实体需要接受的值少于继承的支柱所接受的值,应以作用于自身的谓词来表达,而不是收窄 schema 叶节点。如果基础实体core/base-server声明了tls_enabled: { type: boolean, default: true },那么无条件要求 TLS 的特化实体应写为:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/tls-only-server version: 1.0.0 labels: component.aggrega.ai/type: "server"spec: extends: core/base-server schema: inherited # values, infra and provides are the base's, verbatim assertions: tls-is-mandatory: | {{- if not .values.tls_enabled -}} {{- fail "this component requires tls_enabled: true" -}} {{- end -}}该规则会拒绝继承的支柱块所接受的某个值,这正是此处“收紧”的含义。反方向则完全无法表达:特化实体无法放宽继承的约束,因为它无法重新声明承载该约束的叶节点。完整的组合表以及基础实体与扩展实体的示例对,请参阅 entities/component.md 中的“Catalog Authoring: Extending Base Components”。
Feature 的 extends 组合其支柱
对于 Feature,子实体的 schema: 按照 JSON Schema 2020-12 的组合语义与基础实体的 schema 组合,生成一份合并后的 schema,供编写的实例据以校验。凭据 Features——即带有 feature.aggrega.ai/kind: secret 标签的 Features——借此在共享基础之上构建:子凭据 Feature 扩展父 Feature,以继承其保管库查询 schema,同时收窄约束。
编译器对这种变化的方向不持立场。组合是结构性的,因此放宽基础约束的子约束在组合时不会中止构建,而是以建议性提示呈现。没有任何机制会拒绝它:Feature 基础实体的约束是目录作者通过评审维护的共同预期,而不是由平台强制执行的契约。
通过 implements 进行接口绑定
Recipes 和 FeatureRecipes 通过其 spec 顶部的 implements: 关键字绑定到 Component 或 Feature 接口。该绑定声明此 Recipe / FeatureRecipe 是哪个目录接口的具体实现,并支持三种版本匹配形式:
- 精确 —
implements: core/api-server:1.0.0— 匹配该 Component 类型的某一个特定版本。 - 主版本兼容范围 —
implements: core/api-server:^1.0.0— 匹配满足>=1.0.0, <2.0.0的任意版本(SemVer 主版本兼容)。用于 Recipe 支持一个兼容范围而非单个固定版本的情况。 - 无版本 —
implements: core/api-server— 匹配该 Component 类型的任意版本。用于一个 Recipe 服务该类型所有版本的情况。
implements: 从不选择 Recipe:选择由 Manifest 的映射完成。该声明驱动的是对每个映射条目的一致性检查——被映射类型的版本必须以三种形式之一满足被映射 Recipe 的 implements:,或者该 Recipe 必须实现该类型所扩展的某个基类型——以及无映射诊断和编辑器补全所提供的候选列表。如果某个映射条目的 Recipe 的 implements: 既不匹配被映射类型,也不匹配其任何基类型,构建就会中止,并指明该映射、该 Recipe 及其 implements: 值。当某个 components.type 键作用于版本并非该键所指明版本的组件实例时——对于不带版本编写的键,即每个实例——会以该实例自身的类型、按构建编译它时所用的版本再次进行检查,不满足的 Recipe 同样会使构建中止,并指明该实例。
implements: 绑定正是让“同一 Component 类型,不同 provider 使用不同 Recipes”得以成立的机制:一个 core/postgres Component 可以有一个为 helm provider 实现它的 Recipe,以及另一个为 compose provider 实现它的 Recipe。每个 Recipe 声明相同的 implements: 值,而 Release 构建所用的 Manifest 会把该类型映射到它想要的那一个。
针对基础编写的 Recipe 服务于所有扩展它的实体
implements: 指定一个基础,指定该基础的 Recipe 即是扩展该基础的每个 Component 的具体实现,无论处于链的哪一层深度。因此,使用 extends 构建的特化无需自己的 Recipe——这也使得已发布的包装器易于使用:发布它的团队编写一个 Component,部署它的团队在每个目标上复用基础的 Recipes。
这里有两个事实同时成立,且相互独立。把它们混为“特化什么都不需要”的读者会写出一个失败的 Manifest,而且会到错误的文件中寻找原因:
- Recipe 能够匹配。 Manifest 映射的类型键与被映射 Recipe 的
implements:之间的一致性检查,在该 Recipe 实现被映射类型本身或该类型所扩展的任一基础时接受该映射。上述三种版本形式对基础的适用方式与对类型本身完全相同:声明implements: core/base-server:^1.0.0的 Recipe 满足基础版本为1.4.0的特化,而不满足基础版本为2.0.0的特化。 - Manifest 仍需映射特化自身的类型。 Recipe 的选择依据精确的映射键。
enterprise/labelled-server的实例需要自己的mappings.components.type条目;它不会继承为core/base-server编写的条目。没有自身条目的特化即使其基础已映射,也会以未映射实例诊断中止。
因此,一个特化的编写成本是一行 Manifest,而无需新的 Recipe:
# The wrapper extends core/base-server and authors no pillars.# core/helm/base-server declares: implements: core/base-serverspec: mappings: components: type: enterprise/labelled-server:1.0.0: core/helm/base-server:1.0.0当被映射类型的 extends 链无法遍历——形成循环,或其指定的某个基础不在目录中——构建会因该链故障而中止,而不是因映射而中止,因为在映射所依赖的链解析完成之前无法判定该映射。该检查仅通过本机已有的 Components 遍历链——即目录中的那些,以及本地制品缓存依据 lockfile 固定版本所保存的那些——从不查询 registry,因此仅由 registry 持有的基础在此视为不存在。获取这样的基础正是 aggrega pull 的作用:基础是所有扩展它的实体的依赖项,因此 pull 会沿着 Release 所涉及的每条 extends: 链,获取任何目录中都没有的每个基础,并在 lockfile 中固定它,随后的构建便会在那里找到它。除非某个 Aggregate 也声明了该基础的实例,否则 Manifest 无需为基础本身编写任何行。
Recipe 建议比此匹配规则更窄。无映射诊断打印的候选列表,以及编辑器补全对映射值应用的排序,列出的是实现所请求类型本身的 recipe;它们不会扩展到实现其某个基础的 recipe。
如需可运行的端到端演练——目录中的已发布包装器、使用它的那一行 Manifest、塑造其渲染输出的基础 Recipe,以及没有自身映射的包装器实例所产生的中止——请参阅示例 examples/extends-wrapper/。
跨实体的版本使用
每种 Aggrega 实体类型——Component、Feature、Aggregate、Recipe、FeatureRecipe、Manifest、Release、Plugin、SchemaLibrary、MappingLibrary、WorkloadLibrary、ArtifactLibrary——都带有一个必需的 metadata.version 字段,并按同一个 SemVer 正则表达式进行校验(MAJOR.MINOR.PATCH,见 architecture/02-ecosystem-philosophy.md)。版本的形式是统一的;版本的使用方式则因实体类型而异。有些版本主动参与解析;另一些则是编译器不据以匹配的描述性来源信息。下表涵盖非库类型,说明编译器如何处理每种实体的版本字段,并使用 10-status.md 中的四标签状态分类法对每种使用机制进行归类。四种库类型不在表中,因为它们的机制统一且不同:使用方按裸名称引用库,可以声明一个可选的 :<version> 最低版本下限,而每个 Release 的 lockfile 负责记录解析出的版本及其内容摘要。
| 实体 | 使用机制 | 状态 |
|---|---|---|
| Component | 类型引用解析;Recipe implements: 匹配 | available——两者均支持精确、caret 范围(^MAJOR.MINOR.PATCH)和无版本形式(参见版本解析和状态 → 版本匹配) |
| Feature | 附加引用解析;FeatureRecipe implements: 匹配 | 同 Component |
| Recipe | Manifest 映射层级解析 | available — 映射值中的精确、caret 范围和无版本形式,每种都选择满足条件的最高版本 |
| FeatureRecipe | Manifest 映射层级解析 | 同 Recipe |
| Aggregate | 父级 aggregates[].type 引用解析 | available——精确、caret 范围和无版本形式,均选择满足条件的最高版本(参见版本解析) |
| Plugin | 通过 recipe.spec.capability → spec.provider.capabilities 进行 Provider 分派 | available — 裸 capability 选择 provider,而其上的版本固定(helm:<version>、helm:^<version>)选择由该插件的哪个版本进行渲染;插件的标识是不含摘要的 oci://<repository> 引用加上 metadata.version,内容摘要记录在 release lockfile 中,构建时据此校验获取到的字节 |
| Manifest | IR 图来源信息(manifest_version) | available(仅为来源信息读取;不参与解析分派) |
| Release | IR 图来源信息(release_version)+ 模板元数据(.metadata.release_version) | 同 Manifest |
目录解析机制(Component、Feature、Aggregate、Plugin)。 对这些类型之一的引用——组件的 type、feature 附加的 type、子 aggregate 导入的 aggregates[].type、流水线步骤的 plugin——按照版本解析所讲的规则进行解析:精确、caret 范围或无版本引用会在目录所持有的版本中选择满足条件的最高版本,而拉取、构建、validate、编辑器以及面向助手的工具都同样应用这一条规则。对于 Component 或 Feature,implements: 匹配从另一个方向读取同样的三种形式——将具体的类型版本与 Recipe 或 FeatureRecipe 声明的形式进行比对——作为下文所述的一致性检查,而非一种选择。Provider 渲染插件的分派采用更简单的形式:按名称在 provider 渲染插件的 spec.provider.capabilities 中查找裸 recipe.spec.capability,而写在 capability 上的版本固定会选择由该插件的哪个版本进行渲染,没有任何版本满足时则中止。
Manifest 映射层级解析。 Manifest 扁平的 mappings.{components,features} 解析机制(包含 name 和 type 两个层级、name 优先于 type、带版本的 type 优先于无版本的 type)记录在 entities/manifest.md 中。解析器使用这些映射:Recipe 和 FeatureRecipe 的选择是将映射值直接在 lockfile 和目录中查找,而类型没有映射的组件或附加会使构建中止。spec.implements 不选择 Recipe——它是对作者已写好的映射在加载时进行的一致性检查,也是无映射诊断和编辑器补全所提供候选列表的来源。随后,能力分派来自已解析 Recipe 的 spec.capability 字段,而非 Manifest 的结构形式。
描述性来源机制(Manifest、Release)。 Manifest 的 metadata.version 和 Release 的 metadata.version 在编译器填充来源信息时被读取,并以 manifest_version 和 release_version 出现在 IR 图的来源信息块中;渲染输出上没有任何标签携带它们。模板还能以 .metadata.release_version 访问 Release 版本。这两个版本都不会为了解析分派而与任何其他实体的版本进行匹配;它们纯粹是来源信息。
阅读此表。 四标签分类区分了“版本字段被 schema 接受并存在于实体上”(始终成立——统一的 SemVer 正则)与“编译器在解析过程中根据此版本进行匹配”(因实体而异)。
Schema 桥接跨支柱传递:将意图桥接到基础设施
Aggrega 在领域 1 与领域 4 之间实行严格的关注点分离:开发者在 values 块中编写认知逻辑,运维者在 infra 块中规定物理规格。Aggregate.yaml schema 强制执行一个具体推论:infra 关键字不出现在 Aggregate 的组件实例及其 features 挂载中,并且结合 additionalProperties: false,会被 schema 校验拒绝。开发者不应在开发者意图中规定物理规格;当某个具体值适合应用场景(例如硬编码的端口或特定的 CPU 数量)时,架构师可以在 Component 的 schema: 声明中显式暴露它,该值通过 values 传递。
当某个具体的基础设施约束是组件契约的内在组成部分时——例如必须拥有 10,000 预置 IOPS 的高吞吐交易数据库,或必须恰好运行在 4 块 GPU 上的 ML 工作负载——平台架构师使用 schema 桥接跨支柱传递模式,通过专门构建的 Component 暴露该约束。
面向基础设施感知组件的 schema 桥接模式。
Component 通过其 schema: 声明,在开发者的 values 块中暴露特定的基础设施调节项,绑定的 Recipe 的 valuesMapping: 模板将该值传入渲染出的 infra: 形态输出。其结果是认知意图与物理规格之间的类型化桥梁:开发者通过经过校验的字段规定硬件约束,约束流向运维,双方都无需编写原始基础设施代码。该调节项是一个支柱键,因此声明在拥有该契约的 Component 上——extends: 某个基础的 Component 不声明支柱键,因而无法引入调节项。
# Domain 2: The Platform Catalog (the schema-bridge Component)apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/high-perf-postgres version: 1.0.0 labels: component.aggrega.ai/type: "stateful-server"spec: schema: values: # Expose the dial safely to the Developer with a typed contract. required_iops: { type: integer, min: 1000, max: 100000, required: true } infra: # Operator-owned sizing the Recipe below reads alongside the dial. storage: { size: { type: string, default: 100Gi } } compute: { instance_class: { type: string, default: db.m5.large } }# Domain 2: The Platform Catalog (the Recipe pipes the dial into provider infra)apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: aws-rds-high-perf-postgres version: 1.0.0spec: implements: core/high-perf-postgres:^1.0.0 capability: terraform source: ./modules/rds valuesMapping: | # The Recipe pipes the developer's values.required_iops into the provider's infra-side knob. iops: {{ .values.required_iops }} allocated_storage: "{{ .infra.storage.size }}" instance_class: "{{ .infra.compute.instance_class }}"# Domain 1: The Developer Intent (remains capability-agnostic)components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: 10000 # Developer dictates the hardware constraint safely多环境扩展(参数提升要求)。
为了在 GitOps 环境(Dev 与 Prod)之间扩展这一硬件约束而不修改开发者的 Aggregate.yaml,开发者将该值提升到类型化的 parameters 契约中。运维通过特定于环境的 Release 文件满足具体的 IOPS 要求。编译器的执行顺序保护了这一流程:参数契约校验在解析时运行;插值将参数解析进所在的 values: 字符串;Recipe 的 valuesMapping: 模板将解析后的值传入渲染输出。
1. 开发者意图(抽象调节项)。
开发者知道需要控制 IOPS,但通过类型化的 parameters 契约将具体数值抽象到环境层面。
spec: parameters: env_iops: type: integer min: 1000 max: 100000 description: Provisioned IOPS for the trading-db instance components: trading-db: type: core/high-perf-postgres:1.0.0 values: required_iops: {{ .parameters.env_iops }} # Hoisted to the environment2. GitOps Releases(运维履约)。
运维在特定于环境的 Release 文件中满足 parameters 契约。类型化契约在插值运行之前校验每个由 Release 提供的值。
- Dev 环境(
release-dev.yaml):env_iops: 1000 - Prod 环境(
release-prod.yaml):env_iops: 25000
编译顺序。 该机制由编译器在解析时的严格执行顺序保护:
- 参数契约校验。 每个由 Release 提供的参数值都会依据 Aggregate 的类型化
parameters:声明进行校验。Prod 值25000通过校验(在min: 1000, max: 100000范围内);值500则会以明确的错误终止。 - 插值。 编译器读取 Prod
Release的参数值,并将25000插值到AggregateYAML 字符串的values.required_iops处。合并后的参数映射在整个渲染过程中保持有效,因此路径模板界面可以直接读取.parameters.<slot>;值模板界面使用已写入 Aggregate 的values:块中的插值后字面量。该映射在所有渲染阶段完成之前保持可读,且只能从为其解析的那次编译中访问。 - Schema 校验。 Component 的
schema:声明校验生成的values:字典;values.required_iops: 25000满足 schema 的min: 1000, max: 100000。 - Recipe valuesMapping 渲染。 绑定的 Recipe 的
valuesMapping:模板将values.required_iops传入 provider 的infra形态输出(iops: 25000)。Wasm provider 插件生成正确的物理数据库配置。开发者获得显式的硬件控制,运维获得特定于环境的扩展,而Aggregate保持与能力无关。