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

appliesTo 与选择器

修饰符系统决定一个 Feature 附加到哪些节点。Feature 声明标签选择器;编译器原生的标签匹配引擎在静态分析阶段 针对每个目标 Component 的 metadata.labels 对其求值。同一个引擎(以及同一套选择器 语法)也对 usesSchema socket 选择器求值,以实现跨节点 类型安全,因此一套词汇适用于语言中的所有选择器场景。

两种封装

一个 Feature spec 最多带有两个选择器字段:

  • appliesTo:AND 组合接口。单个 Kubernetes 风格的标签选择器字符串;每个以逗号分隔的 要求都必须成立,附加才有效。
  • appliesToAnyOf:OR 组合接口。一个选择器 条目列表;任意一个条目匹配即满足附加。每个条目 要么是字符串形式的选择器(语法与 appliesTo 相同, 字符串内的要求以 AND 组合),要么是仅按相等匹配的扁平键值映射。

当一个 Feature 同时声明两者时,两种封装的结果以 AND 组合: appliesTo 字符串必须成立,且至少一个 appliesToAnyOf 条目必须 匹配。省略或为空的选择器不声明任何约束,匹配 所有标签集;两个字段都没有的 Feature 可附加到 开发者放置它的任何位置。

spec:
appliesTo: "compliance.aggrega.ai/scope in (pci), tier notin (dev, staging)"
appliesToAnyOf:
- { component.aggrega.ai/type: stateful-server }
- "datastore.aggrega.ai/engine in (relational, document, vector)"

字符串语法

选择器字符串遵循 kubectl get -l 接受的标签选择器语法:以逗号分隔、以 AND 组合的要求,每个要求采用以下六种 形式之一:

形式含义
key=value该标签存在且值恰好为此值
key!=value该标签不存在,或存在但值不同
key in (v1, v2)该标签的值属于该集合
key notin (v1, v2)该标签不存在,或其值不在该集合中
key该标签存在(任意值)
!key该标签不存在

键可以带有 DNS 风格的前缀(team.aggrega.ai/owner)。 运算符词汇是一个由六种形式构成的封闭集合;引擎不支持 正则表达式、子串或数值比较。

appliesTo: "component.aggrega.ai/type in (server, worker), !legacy.aggrega.ai/exempt"

六种形式之外的要求会被拒绝,绝不会被猜测:

  • 空要求:开头、结尾或重复的逗号,或 仅由分隔符组成的字符串。"tier=frontend," 和 " , , " 会被 拒绝,而不会被解读为更少的要求或没有要求。
  • 包含空白或语法自身字符之一的键: =、!、(、) 和逗号,这些字符用于区分不同形式。! 只用于指明标签键,因此 !tier=frontend 会被 拒绝:它本意是排除 frontend,否则会被解读为“名为 tier=frontend 的 标签不存在”,而每个 component 都 满足这一点。排除某个值的写法是 tier!=frontend。同样, tier in frontend 会被拒绝(集合应写作 tier in (frontend)), tier: frontend 也是如此。
  • 未闭合的集合:in ( 或 notin ( 缺少 )。

值不受任何字符集限制:它是运算符之后的文本, 去除首尾空白后,与标签的原样值进行比较。因此 tier==frontend 要求标签的值为 =frontend;== 并不是相等的另一种写法。除上述键 规则外,键和值都不会被评判:标签是引擎进行比较的不透明 字符串。

校验在哪里进行

选择器由两层检查,其严格程度有意不同:

  • JSON Schema 的 pattern 是一道宽松的外层关卡。 Feature schema 将 appliesTo(以及字符串形式的 appliesToAnyOf 条目) 声明为带有边界 pattern 的字符串,该 pattern 只拒绝 明显格式错误的形态。它有意保持宽松:schema 绝不会拒绝引擎能够求值的选择器。
  • 解析器即校验器。 编译器的选择器解析器掌管语法:它拒绝的选择器(上述任一形态)会使构建中止,并给出诊断,指明该选择器、声明它的 Feature、socket 或 slot,以及它无法解读的要求。解析失败会明确而具体地报告,绝不会被静默跳过。在构建中,解析器在选择器被求值的地方运行:Feature 的每次附加、经由 socket 连接的每条边、slot 的每次填充。aggrega validate 无论针对整个目录,还是针对单个 Component 或 Feature,也会读取该实体文档声明的每个 socket 和 slot 选择器,因此位于没有任何东西使用的 socket 或 slot 上的格式错误选择器会在那里被拒绝,所用的代码和措辞与构建相同。位于没有任何东西附加的 Feature 上的格式错误的 appliesTo,直到有东西附加它时才会被报告。

能够解析但不匹配的选择器本身并不是错误, 而是一个未满足的约束。在静态分析阶段,每个目标标签不满足该 Feature 选择器的 Feature 附加都会产生一个违规诊断,指明 feature 实例、目标节点、其 标签以及该约束;分析器会在中止前收集所有违规, 因此一次编译即可呈现全部违规。

编译器不做什么

编译器与标签语义无关。它对找到的任何标签字符串求值:它不会将 component.aggrega.ai/type 视为特殊标签,不会校验某个类别值是否属于标准目录的封闭集合,也不会从键名推断含义。标签词汇本身(运维类型契约、认知类别轴、按角色划分的能力标签)是一项由目录作者和发布 linter 维护的标准库约定,而非由编译器维护。编写自己目录的企业可以自由定义自己的标签词汇;选择器引擎会以完全相同的方式对其求值。关于标准目录使用的三轴标签方案,参见 architecture/13-catalog-and-registry.md;关于逐个标签的讲解,参见 architecture/09-ai-features.md §1.2。

整个语言中选择器的同源关系

usesSchema socket 选择器(selector: "component.aggrega.ai/type=stateful-server") 以及由其合成的 x-aggrega-selector: 注解,与 Feature appliesTo 使用 相同的语法和相同的引擎。编写 知识可以一一对应地迁移:可用作 socket 选择器的字符串也可用作附加选择器。关于 socket 侧的讲解, 参见 topology-triad.md 和 entities/component.md。

关于 Feature 侧的编写接口(spec 字段、完整的 附加示例,以及与 extends 继承的相互作用),参见 entities/feature.md §Label-Based Attachment。