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。