标签与注解
Aggrega 实体带有两种结构相似的元数据机制——metadata.labels 和 metadata.annotations——此外还有分散在边界级联界面和 feature 挂载界面上的带注解字段。共有六个不同的界面编写或承载注解/标签内容,每个界面的级联规则、使用方和前缀约定各不相同。本页集中记录这些界面,定义运行时模板上下文公开的三个语义分桶,说明作者应遵循的前缀规范,并将五个 Feature 挂载界面并列记录,使其与更广泛的标签/注解词汇一同呈现。
六个承载注解和标签的界面
作者会在六个不同的界面上遇到标签和注解。每个界面具有不同的范围、不同的级联规则和不同的使用方。
| # | 界面 | 范围 | 级联规则 | 主要使用方 |
|---|---|---|---|---|
| 1 | 目录实体 metadata.labels | 每个实体的标识(Component、Feature、Aggregate) | 不级联到实例;承载在目录实体本身上 | 对 Components 和 Features 使用 aggrega search -l;Aggregate 的标签随其文档携带,没有任何命令读取它们 |
| 2 | Component metadata.labels(固有) | 每个 Component 实例的属性(component.aggrega.ai/type 等) | 经 label-transform 变更后级联到 IR 每个节点的 .context.labels | 选择器匹配(usesSchema 的 selector: 声明,在合成的 JSON Schema 中以 x-aggrega-selector: 承载)、Recipe 模板逻辑 |
| 3 | Component metadata.annotations | 由架构师编写的每个 Component 实例的特征 | 级联到 IR 每个节点的 .context.annotations.catalog 桶 | 治理裁决角色(固有特征策略)、Recipe 模板逻辑 |
| 4 | Aggregate / 子系统 annotations: | Aggregate 侧的认知元数据 | 级联到 IR 每个节点的 .context.annotations.aggregate 桶 | 用于认知路由的 Recipe valuesMapping: |
| 5 | Release 边界 annotations: | 运维侧的物理元数据,包括 aggrega.ai/* 知名注解 | 级联到 IR 每个节点的 .context.annotations.release 桶 | Providers(helm 读取 aggrega.ai/namespace;compose 从同一键派生网络名称);用于跨边界路由的 FeatureRecipe injectMapping: |
| 6 | Manifest features.annotations 绑定 | 注解键 → Feature 类型的绑定,带按支柱分组的子键路由(maps.infra / maps.values),用于注解驱动的 Feature 附加 | 解析过程中的注解展开子阶段遍历 Release 边界(由外到内)和 Aggregate 子系统(由外到内);适用按 component 覆盖以及整值 / 按子键的 null 退出;侧与支柱的强制检查决定每个编写侧触发哪个支柱 | 注解驱动的 Feature 展开(合成的 Feature 附加,在 IR 图中以 origin: annotation 记录) |
界面 4 和 5 具有相同的 YAML 结构(级联边界上的 annotations: 映射),但级联到不同的 IR 桶——桶的区分是运行时公开的关键规则。界面 6 在结构上是独立的:它位于 Manifest 实体上,而不是 Aggregate / Release 内容上,其使用受注解驱动的展开过程控制。
.context.annotations.* 的三桶语义
渲染器求值 Recipe 模板时,每个节点的 .context.annotations 字段包含三个具名桶。每个桶都是以注解名为键的扁平 string → string 映射;桶决定了注解由谁编写以及其意图是什么。
.context.annotations.release— Release 边界注解(界面 5)。用于管理物理现实;渲染器在适当时将其路由到infra:字段。aggrega.ai/*知名注解位于此桶中。.context.annotations.catalog— Component 元数据注解(界面 3)。由架构师编写的不可变内在特征;主要由 Wasm 策略插件使用。.context.annotations.aggregate— Aggregate 子系统注解(界面 4)。认知元数据;渲染器在适当时将其路由到values:负载中。
三桶分离是一种社会契约
编译器不强制执行桶的边界。三个桶共享扁平的 string → string 形状;Recipe 的模板可以读取全部三个桶,没有任何机制阻止 Release 边界注解被解释为认知元数据字段,也不阻止目录注解被路由到 infra:。这种分离是编写纪律,而非编译器保证。
纪律目标——各个桶意图表达的内容:
- release = “该组件在何处运行,由运维管理”
- catalog = “该组件是什么,由架构师编写”
- aggregate = “该组件做什么,由开发者编写”
当作者遵守这种分离时,下游工具可以针对正确的关注点读取正确的桶。当作者违反它时(例如,因为 Release 文件方便而将认知元数据放入 release 注解),运行时仍然可以工作,但桶的意图会变得混乱。
Linter 插槽——标记跨桶读取
linter 插件(带外建议性;放置标准参见 plugins/plugin-contract.md)可以标记跨桶读取,即 Recipe 的模板从意图与所路由字段不匹配的桶中取值。标准如下:
- 读取
.context.annotations.release来填充values:字段——标记(认知元数据应来自aggregate桶)。 - 读取
.context.annotations.aggregate来填充infra:字段——标记(物理元数据应来自release桶)。 - 读取
.context.annotations.catalog来填充values:或infra:——通常仅作建议(目录注解是内在特征;将其路由到支柱中并不常见,但并不总是错误的)。
发布 linter 没有针对此标准的规则,构建也不检查它;你自己的 linter 插件可以做到,借助 aggrega lint 运行的 linter 插槽。这一纪律由遵循桶意图约定的审阅者和作者来维护。
前缀规范
注解和标签的键遵循统一的 <namespace>/<name> 形式。下面的前缀族说明了每个前缀下的键由谁编写,以及各自如何维持——**一个前缀是保留的,当 Manifest 绑定或 Recipe 输出标签在其中声明新键时,构建会中止;其余前缀属于目录约定,没有任何机制会拒绝某个键。**两者的区别在于构建是否中止,因此请先阅读中间一列。
| 前缀 | 由谁在此编写键 | 如何维持 | 用途 | 示例 |
|---|---|---|---|---|
aggrega.ai/ | 仅限 Aggrega 平台 | 保留且强制执行。 此处的键由平台定义,你可以编写平台定义的键,例如 Release 边界上的 aggrega.ai/namespace。在该前缀下声明新键会导致构建中止:无论是直接位于该前缀下的 Manifest features.annotations 绑定,还是位于该前缀下、出现在 outputLabels: 或 outputComponentLabels: 中的 Recipe 输出标签键,均是如此。在该前缀下编写但平台未定义的注解不会被拒绝:构建会携带它,而当它位于 Release 上时,不处理它的目标会以警告说明这一点。参见 errors/fatal-halts.md 中的“A Manifest annotation binding claims the reserved aggrega.ai/ prefix(Manifest 注解绑定占用了保留前缀)”和“An output-label key uses a reserved namespace(输出标签键使用了保留命名空间)”。 | 由 provider 直接使用的平台原生注解 | aggrega.ai/namespace, aggrega.ai/region, aggrega.ai/environment |
feature.aggrega.ai/ | 官方标准库 | **约定。**此处没有任何机制拒绝键;该词汇表归标准库所有,依据的是共识而非检查。 | 在 Manifest features.annotations 中绑定的 Feature 注解快捷方式 | feature.aggrega.ai/prometheus-exporter, feature.aggrega.ai/data-masking |
component.aggrega.ai/ | 官方标准库 | **约定。**此处没有任何机制拒绝键。 | Component 固有特征标签(component.aggrega.ai/type 选择器键位于此处) | component.aggrega.ai/type |
aggregate.aggrega.ai/ | 官方标准库 | **约定。**此处没有任何机制拒绝键。 | Aggregate 模块级身份标签 | aggregate.aggrega.ai/tier, aggregate.aggrega.ai/compliance |
<role>.aggrega.ai/ | 官方标准库,以及在自有目录中的企业 | **约定。**此处没有任何机制拒绝键。 | 能力标签——usesSchema 选择器或 Feature 的 appliesTo 据以区分的行为维度。<role> 指明该维度所属的关注点:可以是某个组件角色,也可以是多个角色共有的横切关注点。 | model.aggrega.ai/capability, datastore.aggrega.ai/engine, gateway.aggrega.ai/intelligence, dataplane.aggrega.ai/request-mirroring |
<any-other-domain>/ | 企业 / 社区 | **开放。**在你控制的域名下编写。 | 自定义注解和标签 | acme.com/billing-tier, corp/cost-center |
编写自定义注解时,请使用你控制的域名(通常采用反向 DNS 风格)。直接在 aggrega.ai/ 下(不带子前缀)编写是平台保留的;Manifest 的 features.annotations 绑定也不能绑定直接位于 aggrega.ai/ 下的键——参见 entities/manifest.md 中的 “aggrega.ai/ 前缀保留”。
为能力前缀命名
能力键的形式为 <role>.aggrega.ai/<dimension>,其中 <role> 是需要斟酌的部分。
有三条规则约束它,第一条最常被
弄反。
- 命名关注点,而不是碰巧最先具备它的组件种类。
当某个维度描述的是多个组件种类共有的东西时,前缀
应命名这一共同关注点,这样下一个具备它的种类可以复用该词汇表,
而不必另起一套平行的词汇。
component.aggrega.ai/hosting是一个关注点—— 由谁运维底层资源——它用相同的措辞描述数据库和模型 API;dataplane.aggrega.ai/*命名的是流量路径上的一个位置,因此 代理、入口网关和服务网格都以同样方式描述自己。确实只属于某一角色的维度 则采用该角色的名称,如model.aggrega.ai/capability那样。 - **前缀中只用一个小写单词,不带连字符。**连字符属于
<dimension>部分,在那里复合词读起来很自然(request-mirroring、data-class、upstream-licensing)。 - **维度在选择器需要时才添加,且它声明的每个值都有携带该值的组件。**这里的每个词都是目录作者必须学习、Feature 作者可能遇到的,因此一个维度要凭借区分
usesSchema或appliesTo实际询问的内容来赢得一席之地。没有组件携带的值比缺失的值更糟:命名它的选择器能够解析,却什么都匹配不到,也什么都不报告——因此目录无法展示的值在有组件携带它之前不会进入词汇表。如果某个键的值是一个部署环境对其如何使用自身组件的陈述,而不是产品的属性,那就是例外,compliance.aggrega.ai/data-class正是这种情况:一个组件的数据属于哪个类别取决于部署环境如何使用该组件,因此没有标准库 Component 携带它的任何值,也没有标准库插槽或 Feature 依据这些值进行选择。声明该键及其值,是为了让部署环境自己的 Components 和它附加的策略共用同一种拼写;命名某个值的选择器或策略只会在其 Components 携带该值的目录中匹配。policy-data-class-route 展示了这样一个 Component 以及读取它的策略。
保留与平台定义的键不是一回事
保留针对的是裸的 aggrega.ai/ 根。其下的每个 <scope>.aggrega.ai/ 命名空间都是独立的键空间,不归平台所有,这正是目录词汇表保持可扩展的原因:企业目录可以编写 acme.aggrega.ai/team,而不会与构建写入的任何内容冲突。
不过,这些开放命名空间中有少数键是由平台定义并由构建读取的,但这并不会使其命名空间成为保留命名空间:
component.aggrega.ai/type在每个 Component 的metadata.labels上都是必需的,并取一组固定值中的一个。选择器依据它进行匹配;编译器不会根据它的取值进行分支。features.aggrega.ai/requiredType.<label>编写在 Component 的metadata.annotations上,声明必须附加指定类型的 Feature。构建会根据每个节点最终的附加集合检查这一要求,并在没有任何附加满足它时中止——参见errors/fatal-halts.md中的 “Required feature not attached(未附加必需的 feature)”。注意复数形式:features.aggrega.ai/是一个独立的命名空间,不同于上表中单数形式的feature.aggrega.ai/,后者承载 Manifest 绑定快捷方式。
可以这样理解两者的区别:保留前缀会拒绝你试图在其中定义的键,而平台定义的键是构建所知的某一个具名键,位于一个你在其他方面可以自由编写的命名空间中。component.aggrega.ai/、features.aggrega.ai/ 等命名空间下的其他所有键,都是构建携带但不解释的元数据。
Component 的 metadata.annotations 上有一个这样的键由标准发布 linter 而非构建读取:observability.aggrega.ai/metrics-credential 说明产品的指标如何进行认证——none,指标不需要凭据即可提供;target-key,指标使用 Component 要求每个调用方提供的密钥;separate-token,指标使用自己的令牌。构建像对待其他注解一样携带它。linter 读取它来决定是否将抓取连接的凭据与目标的调用方密钥进行比较,并要求它与 Component 声明的 metrics_credential_required provides 键保持一致——参见 cli/aggrega-lint.md 中的 “The discipline rules”。
在渲染输出上发出的溯源标签
除了 provider 所消费的入站注解之外,Aggrega 还会向 helm provider 渲染的每个 Kubernetes manifest 和每个发出的 compose 服务发出溯源标签,而 helm-chart provider 会以与 helm provider 相同的方式,把同一组标签写到它用 $import: 加载的每个制品上。借助这组标签,下游工具(成本看板、可观测性栈、GitOps 控制器)可以将运行时资源追溯到生成它们的目录内容。helm-chart 子 chart 自身的模板按其作者编写的原样复制,因此它们携带的是该作者所写的标签。
helm 和 compose provider 发出的标签集——在 helm 上,其中三个键以注解而非标签的形式写入,如表所示:
| 标签 | 来源 | 是否总是发出? |
|---|---|---|
app.kubernetes.io/name | Component 标识——你所写的名称;对于导入的 Aggregate 贡献的组件,是其限定名称,模块分隔符以转写形式写出(见下文);对于 FeatureRecipe 发出的资源,则是为该附加派生的标识符 | 在 Kubernetes manifest 上是;在 compose 服务上不发出(该标准标签专用于 K8s) |
aggrega.ai/component-id | Component 标识——你所写的名称;对于导入的 Aggregate 贡献的组件,是其限定名称,模块分隔符以转写形式写出(见下文);对于 FeatureRecipe 发出的资源,则是为该附加派生的标识符 | 是 |
aggrega.ai/recipe-uri | 生成方 Recipe 的 <recipe-name>:<recipe-version>(对于 FR 发出的资源,则为生成方 FeatureRecipe 的) | 当生成方实体同时设置了名称和版本时;在 helm 上为注解 |
aggrega.ai/boundary-path | 该组件被路由到的边界路径 | 当边界路径非空时;在 helm 上为注解 |
aggrega.ai/aggregate-name | Aggregate metadata.name | 设置时 |
aggrega.ai/compiler-version | 构建时写入的编译器版本 | 设置时 |
aggrega.ai/provider | 渲染该资源的 provider(helm、helm-chart、compose) | 是 |
aggrega.ai/provider-version | 该 provider 的版本 | 是 |
aggrega.ai/environment | Release metadata.environment | 是——每个 Release 都会声明它 |
aggrega.ai/sync-wave | 按边界设置的 syncWave 整数,即 GitOps 工具应用资源的顺序 | 非零时;在 helm 上为注解,与 argocd.argoproj.io/sync-wave 并列 |
聚合名称、环境、编译器版本以及提供程序的名称和版本,都是由你或构建选定的字符串,在写入之处都不受 Kubernetes 标签值规则的约束。在 helm 上,当值已经是有效的标签值时——字母、数字、-、_ 和 .,两端为字母或数字,最多 63 个字符——这些标签各自按原样携带该值;否则携带改写为有效标签值后的值,并在同一个键下以注解形式添加原样的值:名为 imported/flow 的 Aggregate 会获得标签 aggrega.ai/aggregate-name: imported-flow 和注解 aggrega.ai/aggregate-name: imported/flow。已经符合规则的值不会添加注解。Compose 将原样的值作为标签携带。改写规则见 providers/well-known-annotations.md 中的“由提供程序发出的来源标签”。
对于 FeatureRecipe 发出的资源,aggrega.ai/component-id 的值根据挂载而非宿主组件的名称构建——无论 FeatureRecipe 以何种方式交付这些资源:合成一个工作负载、发出一组独立的制品,还是渲染其作者提供的 chart 或片段。因此,按标识选择某个挂载资源的查询会返回其全部资源,且其中没有任何一个与宿主组件自身发出的资源无法区分。值的构建方式取决于 Feature 挂载在何处;无论哪种方式,结果都是合法的 Kubernetes 标签字符串。
对于由导入的 Aggregate 提供的组件,标识是该组件的限定名称,其中连接模块与组件的分隔符被转写——data-layer.main-db 会被写为 data-layer-zdmain-db——因为点号不是资源名称或集群地址能够安全承载的字符。你所写的不含分隔符的名称会按字节原样写入。
标识说明的是资源属于什么。这与资源叫什么是不同的问题,而对于其中一种交付方式,两者的答案不同:
- 当 FeatureRecipe 合成工作负载时,这些资源由 Aggrega 自行构建,因此也按标识为其命名:标识不仅进入其标签,还进入其
metadata.name、选择器标签和发出的文件名。它是集群内的名称,而不仅是一个标签。 - 当 FeatureRecipe 交付的是其作者编写的 chart 或片段时,名称归编写者所有。这些模板渲染所依据的 Helm release 名称——以及渲染所发出文件的前缀——仍保持为宿主组件的。chart 通常按 release 名称为其资源命名,因此改动它会重命名 chart 自身声明的资源,而这些资源已部署在集群中,且原因与 chart 毫无关系。标签仍携带该挂载自身的标识,正是这一点使挂载的资源可被找到。
- 当 Feature 挂载到边界时,不存在可以代用其名称的宿主组件,因此组合出的标识在那里既是标签,也是命名依据。
无论哪种方式,值都由你所写的各部分组合而成,以 -- 连接,并以一个固定的开头标明属于两种情况中的哪一种。共使用两种开头,而你所写的组件标识不能以其中任何一种开头——正是这一点保证你所写的名称与 Aggrega 组合出的名称永远不会被相互混淆。
当 Feature 挂载到组件时,各部分依次为固定的 cfr 开头、Feature 所挂载组件的标识,以及挂载所用的键。挂载到组件 api、键为 mon 的 Feature 得到 cfr--api--mon。宿主组件之所以属于该值,是因为同一个 Feature 名称挂载到多个组件时,会在每个组件上发出一组独立的资源,而每组都需要自己的标识:将 mon 同时挂载到 api 和 worker 会得到 cfr--api--mon 和 cfr--worker--mon,而不是两者共用一个值。出于同样的原因,与宿主组件同名的挂载会得到与该组件自身不同的值——挂载到 mon 上的 mon 得到 cfr--mon--mon。
当 Feature 挂载到边界时——compose-bridge 网关服务是典型示例——各部分依次为固定的 bfr 开头、边界路径从最外层开始的每一段,以及 Feature 挂载所用的名称。位于 bridge 边界上、名为 gateway 的 Feature 得到 bfr--bridge--gateway;同一 Feature 位于 prod/eu 边界上时得到 bfr--prod--eu--gateway。
值无法携带的字符会被转写而不是替换;并且由于该值既是集群内的名称又是标签,它被限制在每种 Kubernetes 资源名称都接受的字符内:小写字母、数字和连字符。因此你写的连字符仍是连字符,小写字母或数字保持原样,而其他任何字符——包括大写字母,标签值接受它而资源名称拒绝它——都会变成一个简短的转义:名为 my_zone 的挂载贡献 my-zuzone,而带有挂载 worker 的组件 myApi 得到 cfr--my-zx000041pi--worker。这个转义后的值,就是该挂载的资源在每个目标上被打标签和被选择所依据的值,是该挂载合成的工作负载据以命名和存档的值,也是边界挂载的 release 名称据以派生的值。大写字母是资源名称规则在仅标签本会转写的字符之外唯一新增的字符,因此各部分都不含大写字母的组合值——cfr--api--mon、bfr--prod--eu--gateway——就是仅作为标签时会携带的值。因此,你能区分的两个挂载必定得到两个不同的值——无论你如何命名它们、边界嵌套多深——因为 -- 是任何书写部分都不可能包含的序列,所以移动各部分之间的分界会改变值,而不会与之冲突。
组合值可以有多长,由目标决定,而不是 Aggrega 持有的某个数字:系统会询问资源所渲染的目标,并缩短值直到该目标接受。Kubernetes 标签值最多 63 个字符,而由同一标识派生的 Helm release 名称限制更严,因此同一挂载在一个目标下可能比在另一个目标下更短。能放下的值按组合结果原样发出,这是通常情况,也是标准库目录中每个挂载的情况。放不下的值会被缩短:每个部分保留其开头,并在一个你所能写出的任何名称都不会产生的标记之后追加整个标识的 10 个字符摘要——因此缩短后的值可被识别出来,永远不会被误读为未经缩短的值。因此,深度嵌套的 gateway 挂载可能渲染为 bfr--region-region-region-region-r--gateway-gate---ze24e3a2ba5e。两个缩短后的值极不可能相同;若真相同,构建会中止,而不会让二者共用一个名称。
关于哪些成对情况会中止以及如何区分它们,请参阅 errors/fatal-halts.md 中的 “The same name is derived more than once inside the output(同一名称在输出中被派生了不止一次)”。
对于 FR 发出的资源,aggrega.ai/recipe-uri 解析为该 FeatureRecipe 自身的 name:version,而非使用它的 Recipe 的标识——因此读取 recipe-uri 来识别生成方实体的下游工具,无论对组件发出的输出还是 FR 发出的输出,都能获得正确的溯源。
关于各 provider 的发出细节(标签落在渲染输出的何处,以及每个 provider 如何序列化它们),请参阅 providers/well-known-annotations.md 中的“Provenance labels emitted by providers”。
Recipe 声明的输出标签
除编译器拥有的来源标签集之外,Recipe 作者还可以通过 Recipe.spec.outputLabels: 声明自己的标签,写入该 Recipe 的渲染输出。这些标签与来源标签走同一条发出通道——它们被合并到同一个标签集中,并落在来源标签所在的每个位置——但它们归作者所有,而非归编译器所有。其预期用途是表达一种实现特征:即某个特定 Recipe 如何实现一个组件的属性(例如,对于同一组件类型,托管服务 Recipe 与自托管 chart Recipe 分别为 hosting: managed 与 hosting: self-hosted),将其呈现在输出上,以便成本、策略和资产清单工具可以查询它。
aggrega.ai/ 和 app.kubernetes.io/ 命名空间保留给来源标签集;任一前缀下的键都会在加载时被拒绝——无论是在 outputLabels: 中,还是在 outputComponentLabels: 中(后者是配套的块,用于指定一个组件标签键,并写入组件自身声明的值)。因此,经过校验的输出标签集始终与来源键不相交,二者在合并后的输出上永远不会冲突。判断依据是裸根:诸如 component.aggrega.ai/hosting 这样带作用域的键属于其自身的命名空间,可以按字面写出或进行提升。各 provider 的呈现方式(合成时为 helm 对象和 pod 模板;源渲染和制品时为对象;compose 服务标签;.tf.json 制品主体上的 terraform 逐资源 tags)与来源标签的放置位置一致,完整说明见 Recipe 实体页面 中的 “The outputLabels: field” 和 “The outputComponentLabels: field” 两节。
Feature 挂载——五个界面
Features 通过五个不同的编写界面挂载到 Components 上,每个界面的范围、目标用户以及在五层洋葱模型中的排序优先级各不相同。完整的挂载顺序和洋葱模型本身记录在 architecture/10-compilation-pipeline.md 中;下表并列列出这五个界面。
| 层级 | 界面 | 编写者 | 范围 | 级联规则 |
|---|---|---|---|---|
| 1 | Aggregate 组件 features: 块 | 开发者 | 按组件实例(细粒度) | 无——由编写者直接指定 |
| 2 | Aggregate 子系统 features: 块 | 开发者 | 子系统范围(在 Aggregate 内横切) | 级联到子系统中的每个组件 |
| 3 | Release 边界 components.<id>.features | 运维 | 按组件实例(细粒度,运维侧) | 无——由编写者直接指定 |
| 4 | Release 边界 features: 块 | 运维 | 边界范围(在边界内横切) | 级联到边界中的每个组件 |
| 5 | Manifest features.annotations 展开 | 平台运维者 | 由注解驱动(合成挂载) | 沿边界树(Release 侧)或子系统树(Aggregate 侧)级联;适用按组件覆盖和按子键 null 退出 |
五个界面是累加的;出现在任一界面上的挂载都会计入该 Component 解析后的 feature 集合。当同一个 Feature 实例名出现在多个界面上时,这些贡献会合并为一个挂载,而不是相互替换;若它们之间类型不匹配,构建会以 feature-merge-conflict 错误中止。
这五个界面是依据架构的关注点分离而有意设计的——开发者(第 1-2 层)、运维(第 3-4 层)、平台运维者(第 5 层)——而非冗余。编写者根据挂载归谁所有以及作用于什么范围来选择界面。
哪些标签决定 Feature 是否适用
Feature 通过 spec.appliesTo 和 spec.appliesToAnyOf 声明自己可以挂载到哪里,构建会依据挂载所落节点的最终标签来判定该声明。将 Feature 挂载到标签不满足条件的节点上会中止构建;两者都未声明的 Feature 不提出任何要求,可以在任何位置适用。
最终标签集分两步组装,而这两步都不是编写者最常设想的那样。
- 节点的标签取自其
type:所指定的 Component 目录实体。 标签是组件类型的属性,而不是实例的属性:Aggregate 无法为组件实例打标签,Release 也不能。Aggregate 自身的metadata.labels描述的是作为可复用模块的 Aggregate,不会级联到其中的组件。因此同一类型的两个实例携带相同的标签;要改变节点的标签,就要改变它指向的类型——或者改变该类型的实体。 - 随后,
label-transform挂载可能会改写这些标签。 当工作区配置以label-transform角色挂载治理插件时,它在拓扑构建阶段运行,可以在任何判定之前添加、修改或删除节点标签。它不能触及其他任何内容,因此标签是它唯一能改变的节点部分——而这恰恰是适用性所依赖的部分。
因此,基于单个文档声明的标签提出的建议只是近似,而不是预测。 读取 Component 实体的 metadata.labels 能告诉你该类型的节点初始拥有哪些标签,这一答案在很多情况下足够有用,但会在两个具体方面出错:仅与节点同名的文档是另一个对象,标签也不同;而 label-transform 挂载可以让标签集脱离任何文档而变化。仅凭源码提供挂载建议的工具依据的正是这种近似;构建所做的判定基于最终标签集。
挂载优先级
当两个贡献提供同一挂载的同一字段时,由四条规则决定渲染输出采用哪一个。它们按以下顺序应用,正是这一顺序让结果可预测:
- 来源。 显式编写的贡献优先于由注解驱动的贡献,无论两者分别在哪个范围声明。在
features:块中写下字段,就是编写者覆盖注解原本会贡献内容的方式,注解永远不会悄无声息地取代手写的内容。编译器会将被压制的注解与胜出的值一并记录,并作为提示报告,使覆盖清晰可见而不令人费解。 - 支柱归属。 每个领域填充自己的支柱:Aggregate 界面贡献
values,Release 界面贡献infra。由于双方从不写入同一支柱,开发者的贡献与运维者的贡献不会争夺同一字段——不存在开发者与运维者之间的优先级问题。 - 组合权威。 你正在部署的 Aggregate 中的声明优先于它所组合的 Aggregate 内部的声明,即使被组合的 Aggregate 是在更窄的范围声明的。组合始终具有权威:模块不能仅凭选择更窄的范围就压过使用它的 Aggregate。
- 具体性。 在同一编写层级和同一支柱内,较窄的范围逐字段细化较宽的范围。组件范围的挂载会覆盖同一实例名的子系统级或边界级挂载——但仅限于它实际提及的字段。较窄范围未涉及的字段保留较宽范围的值,因此共享挂载可以提供通用配置,而单个组件只调整其中一个字段。同一范围的两个贡献按编写顺序解决,后者胜出,这使得内层子系统可以细化外层子系统,较深的边界可以细化较浅的边界。
优先级决定字段值,但不会重排求值:编译器折叠各界面、以及执行各挂载的预渲染 injectMapping 的顺序,是 architecture/10-compilation-pipeline.md 中记录的固定五层顺序。挂载中编写的 inject 块遵循该求值顺序,而不是上述范围排序,因此一个挂载永远不会同时带有两种相互冲突的顺序。
哪些类型带有 metadata.labels 和 metadata.annotations
metadata.labels 位于 Component、Feature、Aggregate 以及四种库类型上;metadata.annotations 位于除 Aggregate 之外的相同类型上。Manifest、Release、Recipe、FeatureRecipe 和 Plugin 两者都不带有。
级联汇总
编译器在六个表面上评估的级联规则:
- **目录实体标签(表面 1)**保留在目录实体上。它们不会流向实例;使用方通过直接检查目录内容来读取它们。
- **Component
metadata.labels(表面 2)**在拓扑构建阶段经过可选的label-transform处理后,流入每个节点的.context.labels。 - **Component
metadata.annotations(表面 3)**流入每个节点的.context.annotations.catalog桶。 - **Aggregate / Subsystem
annotations:(表面 4)**沿子系统层级级联,从外层子系统向内累积,流入每个节点的.context.annotations.aggregate桶。 - **Release 边界
annotations:(表面 5)**沿边界层级从外层边界向内级联,流入每个节点的.context.annotations.release桶。 - **Manifest
features.annotations(表面 6)**不会直接级联到每个节点的 IR 数据;解析阶段中由注解驱动的展开子阶段会使用这些绑定,合成每节点的 Feature 挂接,IR 图(--ir-graph)以origin: annotation记录这些挂接。在解析之后的下游环节中,除通过该来源信息外,这些合成挂接在结构上与显式挂接无法区分——完整的展开说明参见providers/well-known-annotations.md,目录加载与检查时的机制参见architecture/13-catalog-and-registry.md§“Annotation-driven Feature expansion”。
规范的级联注解设计参见 architecture/06-data-taxonomy-and-composition.md §2(Flow 5)。
交叉引用
templates/template-context-contract.md—.context.labels以及三个.context.annotations.*桶的运行时视图。providers/well-known-annotations.md— 各 provider 的边界注解矩阵,以及溯源标签输出的不对称性。entities/manifest.md— Manifest 的features.annotations绑定界面(界面 6)。vocabulary/publishing-surface.md— 在发布端补充标签/注解的统一元数据词汇。plugins/plugin-contract.md— 针对跨桶读取的建议性检查在 linter 插槽中的放置准则。architecture/06-data-taxonomy-and-composition.md— 规范的级联注解设计。architecture/10-compilation-pipeline.md— 决定 Feature 挂载顺序的五层洋葱模型。