一个已发布的包装器,由其基础组件的 Recipe 提供服务
本示例只讲一件事:一个 extends 另一个组件的 Component 会继承该基础组件的完整数据契约,因此为基础组件编写的每个 Recipe 都已经实现了这个扩展的 Component。所以,发布标准库组件的一个特化变体只需要一个目录实体和一行 Manifest——不需要自己的 Recipe,也无需修改基础组件。
这里的包装器是 example/gateway/nginx-reviewed。它与其所扩展的组件 core/gateway/nginx 一起随目录发布。
包装器添加了什么,继承了什么
包装器编写的全部内容就是元数据加一个插槽:
metadata: name: example/gateway/nginx-reviewed labels: component.aggrega.ai/type: server component.aggrega.ai/category: gateway gateway.example.com/audit-tier: reviewed # added gateway.example.com/data-zone: eu-west # added annotations: governance.example.com/review-board: platform-architecture # added governance.example.com/contact: platform-architecture@example.comspec: extends: core/gateway/nginx:1.0.0 schema: inherited usesSchema: reviewed_upstream: # added selector: "gateway.example.com/audit-tier=reviewed" inject: [env]schema: inherited 是扩展的 Component 用来代替 schema: 块的字面标记。它表明三个数据支柱——values、infra 和 provides——属于基础组件,与基础组件编写的完全一致。包装器不声明自己的任何支柱键,也不能声明:在继承链的任何深度,契约都属于基础组件。
包装器未提及的一切,都由它继承。aggrega inspect example/gateway/nginx-reviewed --resolved 会显示合并后的实体,其中有两点值得仔细阅读:
- 三个
uses插槽,而不是一个:upstream和guard(基础组件的,其中upstream选择component.aggrega.ai/type=server)以及reviewed_upstream(包装器的)。扩展会添加插槽,而不会替换整个集合。 - 基础组件的三个支柱,原样保留——
values.upstream_path、infra.port/engine_version/compute/overrides,以及provides.host/port/protocol,每项都带有基础组件自己的描述。
使用方 Aggregate 编写的内容
aggregate-reviewed.yaml 将两个网关层声明为该包装器,位于一个数据库控制台之前:
components: edge: type: example/gateway/nginx-reviewed values: upstream_path: /api/ # declared by the base; the wrapper never mentions it uses: reviewed_upstream: # the socket the wrapper ADDS internal: { target: internal, inject: { env: [ ... ] } } internal: type: example/gateway/nginx-reviewed values: upstream_path: / uses: upstream: # the socket the wrapper INHERITS console: { target: console, inject: { env: [ ... ] } } console: type: core/devtool/adminer需要注意的是 upstream_path 这个键。它声明在 core/gateway/nginx 的
values 支柱中,在包装器的文件里没有出现,但作者在包装器实例上编写它,它会进入渲染出的网关配置。这就是完整继承支柱在实践中的含义。
Manifest 是另一半,每个类型一行:
mappings: components: type: example/gateway/nginx-reviewed:1.0.0: compose/nginx:1.0.0 core/gateway/nginx:1.0.0: compose/nginx:1.0.0 core/devtool/adminer:1.0.0: compose/adminer:1.0.0两行网关都指向同一个 Recipe。compose/nginx 声明了
implements: core/gateway/nginx:1.0.0,而指向某个基础组件的 Recipe 就是所有扩展该基础组件的 Component 的实现——因此包装器无需改动即可由它提供服务。这里同时成立两个事实,且它们彼此独立:
- Recipe 匹配。 不存在实现包装器自身类型的 Recipe, 也不需要。
- 映射仍然是必需的。 Recipe 按精确的映射键选择,因此
包装器需要自己的
type条目;它不继承基础组件的条目。没有自己条目的包装器实例即使其基础组件已映射,也会以未映射实例诊断而中止。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example extends-wrapper然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd extends-wrapper构建
aggrega build --release release-reviewed.yaml --auto-pull渲染输出和 lockfile 是生成的,不随示例提供:本示例只提交输入,其余一切都重新生成。--auto-pull 在构建期间解析 lockfile;预先运行一次 aggrega pull --release release-reviewed.yaml 效果相同,之后的构建可以不带任何标志运行。
包装器及其扩展的基础组件都位于共享目录中,该目录从 .aggrega-config.yaml 声明的默认注册表 hub.aggrega.ai 解析。构建命令不需要 --catalog 标志,在此目录中运行的 aggrega inspect 也不需要。
pull 操作会获取 core/gateway/nginx,因为包装器扩展了它:基础组件是所有扩展它的内容的依赖,因此无论 Manifest 是否指定它,pull 操作都会沿着包装器的 extends: 在锁文件中固定该基础组件。此处 Manifest 映射该基础组件另有原因——下文的对照发布声明了基础组件本身的一个实例。
渲染出的 dist/compose/docker-compose.yaml 提供了证据:
edge: image: nginx:1.27.5-alpine entrypoint: - /bin/sh - -c - echo 'server { listen 8080; location /api/ { proxy_pass http://internal:8081; } }' > /etc/nginx/conf.d/default.conf && exec nginx -g 'daemon off;' [… omitted: the published port] labels: [… omitted: the other provenance labels every rendered document carries] aggrega.ai/recipe-uri: nginx:1.0.0 [… omitted: the service's network, its depends_on naming internal, and its healthcheck]三处读数,按其所证明的内容排列:
aggrega.ai/recipe-uri: nginx:1.0.0——该服务由基础组件的 Recipe 生成。 包装器实例上的来源标签指向基础组件的 Recipe,因为渲染它的正是该 Recipe。location /api/——values.upstream_path这个只有基础组件声明的键, 在包装器实例上编写并被渲染。proxy_pass http://internal:8081——reviewed_upstream边已解析。 目标的provides.host和provides.port以基础组件的 Recipe 读取的交付键到达注入上下文,因此包装器添加的插槽会流经一个从未知道它存在的 Recipe。
构建解析出的 lockfile 从解析器的角度记录了同一事实:
一个位于同一摘要的 compose/nginx:1.0.0 条目,被两个映射键引用——基础组件的类型和包装器的类型。
包装器的标签和注解随已解析的边一起传递:使用方节点的渲染上下文携带每个目标的 provides、labels 和注解,因此 edge 的上下文知道其上游是 audit-tier=reviewed 以及由谁审核。这些内容是否出现在渲染产物中由 Recipe 决定——这些标签和注解是供选择器和策略读取的组件身份,而不是编译器写入的输出。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `extends-wrapper` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `extends-wrapper`,且不设置 `dir`:它会把示例写入新的 `extends-wrapper` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `extends-wrapper`,`release` 设为 `release-reviewed.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我这次构建写入了哪些文件;它们位于 `extends-wrapper/dist/` 下。对照:添加的标签有何用途
aggregate-unreviewed.yaml 是对 aggregate-reviewed.yaml 做了一处修改的版本——内部层被声明为裸的 core/gateway/nginx 基础组件而非包装器——它预期会失败:
aggrega build --release release-negative-unreviewed.yaml --auto-pull# [DEVELOPER_ERROR E0007] aggregate-unreviewed.yaml at .spec.components.edge.uses.reviewed_upstream.internal# selector violation ("gateway.example.com/audit-tier=reviewed", declared on socket "reviewed_upstream", not satisfied by the labels of "internal"). Add the labels the selector requires to the target's component type, or wire the socket to a component that already carries them.这次中止正是要点所在。基础组件满足它自己的 upstream 插槽——它是
component.aggrega.ai/type=server,内部层也以完全相同的方式通过该插槽连接——但它不带 audit-tier 标签,因此包装器更严格的插槽拒绝了它。包装器添加的标签使其实例可被选中,而这一点体现在选择器上。
还有两种中止值得了解,两者都是 schema 在履行职责:
- 声明了
extends又在schema:下编写支柱内容的 Component 会在文档加载时被拒绝,并指出所违反的约束。完全省略schema:的也会被拒绝。schema: inherited是唯一被接受的形式,它需要显式写出而非隐含,这样读者永远不会把继承的支柱块与遗忘的支柱块混淆。 - 基础组件未声明的
values键在包装器实例上会被拒绝, 错误定位在编写的路径上,因为强制执行的契约属于基础组件。
为什么这很有用
一个组织为某个标准库组件确定了经审核的形态后,需要有地方保存它。如果只用文字描述,标签、注解和插槽就要在每个需要它们的 Aggregate 中重复书写,并因此逐渐走样。如果作为扩展基础组件的 Component 发布,这一形态就成为一个有名称、有版本、可审核的目录实体:使用它的团队只需编写
type: example/gateway/nginx-reviewed 和一行 Manifest,就能继承基础组件的完整契约以及所有已针对它编写的 Recipe,覆盖基础组件支持的所有目标。
包装器的代价正是这一切得以成立的原因:它只添加结构和元数据,别无其他。由于它不声明支柱,包装器的实例和基础组件的实例针对同一个契约进行校验,为基础组件编写的 Recipe 永远不会被它的特化所意外影响。