URI 语法与格式字符串清单
Aggrega 实体通过出现在多个不同编写位置的 URI 字符串相互引用。同一种 URI 形式(core/postgres:1.0.0)出现在五种以上的实体种类上下文中,编译器根据 schema 位置而非符号或前缀来推断实体种类。阅读或维护 YAML 文件的作者必须牢记这些基于位置的解释规则,才能知道 core/postgres:1.0.0 指的是 Component 类型、Aggregate 模块、Recipe、FeatureRecipe 还是 Wasm 插件。
本页汇总了所有位置上的 URI 语法、Manifest 映射层级中带版本与不带版本的 type: 键的优先级规则、OCI URI 简写推断规则,以及整个文档语料中更广泛的格式字符串清单(Go 模板语法、Sprig 函数、JSON Schema 2020-12 声明、JSONPath、glob 模式、SemVer 正则表达式)。需要了解“Aggrega 会如何处理这个字符串?”的作者应能在此找到答案。
基于位置的实体种类推断
同一个 URI 字符串根据其在 schema 中出现的位置而具有不同的实体种类含义。下表列出了 Aggrega 期望出现实体引用 URI 的每个位置,以及推断出的实体种类:
| Position | 推断的实体种类 | OCI 路径展开 |
|---|---|---|
Aggregate.spec.components.<id>.type | Component | /component/{publisher}/{category}/{name} |
Aggregate.spec.subsystems.<name>.components.<id>.type | Component(与 components 相同——子系统是组件分组) | /component/{publisher}/{category}/{name} |
Aggregate.spec.aggregates.<id>.type | Aggregate(子聚合模块) | /aggregate/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature | /feature/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature(凭据——标记为 feature.aggrega.ai/kind: secret) | /feature/{publisher}/{name} |
Manifest.spec.mappings.components.type.<key> | Component(用作查找键的 URI);值为 Recipe URI | 键:/component/;值:/recipe/{provider}/{name} |
Manifest.spec.mappings.components.name.<id> | Recipe(细粒度覆盖绑定) | /recipe/{provider}/{name} |
Manifest.spec.mappings.features.type.<key> | Feature(查找键);值为 FeatureRecipe URI | 键:/feature/;值:/featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.name.<id> | FeatureRecipe(细粒度覆盖绑定) | /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.annotations.<key>.feature | Feature(通过注解绑定) | /feature/{publisher}/{name} |
Recipe.spec.implements | Component(接口契约) | /component/{publisher}/{category}/{name} |
FeatureRecipe.spec.implements | Feature(接口契约) | /feature/{publisher}/{name} |
Component.spec.extends / Feature.spec.extends | Component / Feature(继承链中的父级) | /component/{publisher}/{category}/{name} 或 /feature/{publisher}/{name} |
Manifest.spec.extends | Manifest(映射继承链中的父级) | 不是 URI 位置——相对路径,或位于 Release 旁边的 Manifest 的裸 metadata.name |
Release.spec.extends | Release(继承链中的父级) | 不是 URI 位置——指向 Release 文件的相对路径,不接受其他形式 |
Release.spec.aggregate | Aggregate(该 Release 的部署目标) | /aggregate/{publisher}/{name} |
Release.spec.manifest | Manifest(该 Release 的映射锁文件) | 不是 URI 位置——相对路径,或位于 Release 旁边的 Manifest 的裸 metadata.name |
FeatureRecipe.spec.pipeline.<step>.plugin | Wasm 插件 | /plugin/{pluginType}/{name} |
之所以列出这三个位置,是因为作者会以为它们接受 URI,而实际上并非如此。 Manifest 和 Release 是彼此并列编写的部署侧文档,而不是由目录索引的实体,因此二者的 extends: 以及任何 Release 的 manifest: 都不会针对目录或注册表进行解析。Release 的 manifest: 指向一个文件,或位于 Release 旁边的 Manifest 的裸 metadata.name。在这两个 extends: 位置上,该值指向一个文件,在任一位置写入注册表坐标都会被拒绝,诊断信息中会给出可接受的形式。这两个 extends: 位置的写法也不相同——Manifest 还接受位于 Release 旁边的 Manifest 的裸 metadata.name,而 Release 只接受相对路径。Release 的形式参见 entities/release.md,各项拒绝的具体说明参见 errors/fatal-halts.md。
推断规则:YAML schema 位置决定实体种类。没有任何表层标记(符号、前缀、schema 级注解)告诉作者某个 type: 字段引用的是哪种实体。作者阅读 YAML 时需牢记这些基于位置的规则;工具(编辑器补全、aggrega inspect)也读取同样的规则,以提供特定于实体种类的建议。
两种 URI 形态——派生坐标的插件与在元数据中标明种类的目录实体
目录实体 URI 不带种类标记(见上一节)。Plugin URI 则是有意设计的对照:插件 URI 确实直接在路径中写出一个分类段——即其插槽类型。这两类引用有意采用不同的读法,知道某个 URI 属于哪一类,就知道该去哪里查找它的分类。
Plugin 坐标由插件的类型派生。 插件引用的形式为 oci://hub.aggrega.ai/plugin/<pluginType>/<name>。该坐标是派生的:<pluginType> 段和裸 <name> 来自插件的寻址块——metadata.pluginType 和 metadata.name——并组合成路径。插槽不会以路径形式编码进名称;metadata.name 是裸名称。派生坐标就是注册表(以及嵌入式插件集)的键,因此注册表按插槽组织插件。核心插件解析为 plugin/provider/helm、plugin/linter/publishing 和 plugin/parser/yaml 这样的坐标——每一个都是裸 metadata.name(helm、publishing、yaml)与其 metadata.pluginType(provider、linter、parser)的组合。<pluginType> 段恰好就是插件的插槽类型:同一个裸 <name> 在不同的 pluginType 下是不同的插件,因为派生坐标——进而身份——不同。关于 <pluginType> 段所依据的完整插槽分类,参见 entities/plugin.md。
目录实体在元数据中标明种类。 编写的引用形式为 <publisher>/<category>/<name>(例如 core/datastore/postgres)。实体的 kind: 写在文件中;URI 的实体种类由 schema 位置推断,见上文基于位置的实体种类推断。路径按类别组织,而非按种类:Component 带有类别段(core/datastore/postgres);Recipe 或 FeatureRecipe 以其渲染能力作为第一段(helm/postgres);其余种类为扁平的 <publisher>/<name>。路径中没有任何部分写出实体种类。
**两种形态为何不同。**Plugins 在注册表中按插槽组织,因此插槽段是天然的注册表键,并出现在每个插件 URI 中。目录实体在注册表中按类别组织,因此路径写出的是类别,而不是种类。所以,对于插件,仅凭路径即可从 URI 得知其插槽;而对于目录实体,只有在读取文件之后才能得知其种类(种类位于 metadata 中,在引用处则由位置提供)。这种不对称是有意为之:每一类的路径都反映该类在注册表中的组织方式,而不是在两者之上强加一套统一的语法。
URI 形态——有版本与无版本
上述每个 URI 位置都接受以下三种形式之一的引用——无版本,或在冒号后用精确版本或脱字符范围固定版本:
| 形式 | 示例 | 语义 |
|---|---|---|
| 无版本 | core/postgres | 根据该位置的解析语义,解析为“任意版本”或“最新注册版本” |
| 精确固定 | core/postgres:1.0.0 | 固定到一个特定版本。该版本为语义化版本,即每个实体的 metadata.version 所采用的形式 |
| 脱字符固定 | core/postgres:^1.0.0 | 选择与所指定版本兼容的最高版本——对于 ^1.0.0,即大于等于 1.0.0 且小于 2.0.0 |
固定版本是引用中最后一个冒号之后的文本,且仅当该文本不含 / 时才成立。因此,指向带端口的注册表主机的引用——localhost:5000/core/postgres——不带固定版本:端口冒号之后的文本是引用的延续。
不属于上述任何形式的固定版本——脱字符后的文本无法解读为版本范围(core/postgres:^garbage),或精确固定版本不是语义化版本(core/postgres:1.x、core/postgres:1.0、core/postgres:v1.0.0)——不指定任何版本。当某个命令解析此类引用且解析失败时,拒绝信息会指明该引用、该固定版本以及上述三种形式,而不是报告目录中不存在的实体或版本;该诊断见 errors/fatal-halts.md 中的“A version pin is none of the forms a pin takes(版本固定不属于固定版本可采用的任何形式)”。固定版本仅在该处判定,因此格式错误的固定版本永远不会改变哪些引用能够解析,而格式正确但没有可用版本满足的固定版本会如实报告。没有任何 schema 规定固定版本的语法,因此格式错误的固定版本会在某个操作解析该引用时——aggrega validate、aggrega pull、aggrega build——报告,而不是在文件加载时报告。
这些形式可在同一位置共存。作者根据需要版本固定还是版本灵活性进行选择。Manifest 的 mappings.{components,features}.type 层级支持将两种变体作为不同的字典键,并采用有版本优先于无版本的优先级——当两者匹配同一查找时,有版本的键(core/api-server:1.0.0)优先于无版本的键(core/api-server)。两种变体并不互斥;二者可以位于同一个 type: 映射中,由解析器选择最具体的一个。Provider 分派源自所解析 Recipe 的 spec.capability 字段,因此 Manifest 只是将类型映射到 Recipe,仅此而已。
关于各实体的版本使用机制(哪些实体的版本字段真正被解析分派使用,哪些仅作描述性来源信息),见 vocabulary/inheritance-and-interface.md 中的“跨实体版本使用”。
对 Component、Feature、Aggregate 或 Plugin 的引用也接受脱字符范围(core/postgres:^1.0.0),无论采用哪种形式,它都会按每个命令共同应用的同一条规则,在目录所含版本中选择满足条件的最高版本——见 version-resolution.md。关于三种形式的 implements: 匹配(它是对映射的一致性检查,而非选择),见 10-status.md 中的“版本匹配”。
是身份,而非位置
规范的实体引用(包括插件引用)是一个身份,而非位置:它指明实体是什么,从不指明它当前位于何处。
该身份是裸的且不含主机。它不携带注册表主机;主机是一个解析坐标,由配置通过 default_registry 提供,并在解析时绑定。迁移注册表,或在其他位置镜像同一实体,只是一次配置变更——指明该实体的引用保持不变。
该身份也不含版本。引用可以携带一个可选的版本固定(:<version> 或 :^<version>),用于约束哪些版本满足它;每个 Release 会在其锁文件中将解析得到的确切版本记录为固定版本。但版本是与身份一并提供的,而不是嵌入身份之中。
在解析时,编译器将裸身份与所配置的主机及固定版本结合,以获得具体的字节内容。由于两者是分别提供的,同一个引用可以针对不同的注册表或不同的固定版本进行解析,而无需修改指明它的源文件。
OCI URI 简写推断
作者不必把每个 URI 都写成完全限定的 OCI URI。编译器在解析时应用四条相互正交的推断规则,将简写的编写形式展开为规范的 OCI URI。规则如下:
规则 1 — 默认域名
任何缺少域名的 URI 都会加上 .aggrega-config.yaml 中配置的 default_registry 作为前缀(默认值:hub.aggrega.ai/)。
# Shorthandtype: core/postgres:1.0.0
# Equivalent canonical formtype: hub.aggrega.ai/component/core/postgres:1.0.0规则 2 — 上下文实体展开
编译器根据 schema 位置追加正确的实体类型段。该映射与上文的位置推断表相同(/component/、/aggregate/、/recipe/、/featurerecipe/、/feature/、/plugin/)。
# Same string, two positions, two expansionsAggregate.spec.components.foo.type: core/postgres:1.0.0# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0# Key: hub.aggrega.ai/component/core/postgres:1.0.0# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0规则 3 — 三层优先级
在应用 OCI 推断之前,编译器先通过 architecture/13-catalog-and-registry.md 中记载的三层实体解析模型来解析 URI:
- 本地路径——用于 Release 及其 Manifest 所指定的文档。 Release 的
aggregate、manifest或extends,或 Manifest 的extends,若以./或../前缀书写,则会作为相对于该 Release 自身目录的文件读取;不运行 OCI 推断。其他位置都不接受路径:写成./…的type、Manifest 映射键或值、implements或流水线plugin不指向任何实体,并会中止构建。本地编写的实体放在工作区根目录的catalog/下或workspace.catalog_dirs列出的目录中,并通过工作区与缓存层按名称解析。 - 工作区与缓存——工作区目录搜索栈,然后是缓存。 按书写顺序搜索
.aggrega-config.yaml工作区的catalog_dirs:目录(对于配置在workspace.releases下为其单独指定了目录的 Release,则搜索该 Release 的目录),工作区根目录的catalog/目录最后搜索:在所有列出的条目之后,且仅当该目录存在时。在栈中任意位置匹配都会跳过 OCI 推断。未命中时再查询artifact_cache_dir,其中保存了先前从注册表拉取的内容。 - 注册表。 当工作区与缓存层未命中时,将应用 OCI 推断规则,并由
aggrega pull,或由使用--auto-pull或工作区auto_pull设置运行的构建,从远程注册表获取该引用;两者皆无的构建只读取其锁文件所固定的内容。
这种级联让项目可以将 Release 按路径指定的文档(本地路径层)与 vendored 的及工作区本地的目录内容(工作区与缓存层)以及从远程获取的注册表内容(注册表层)混合使用,并且无论实体位于后两层中的哪一层,实体引用的写法都相同。
当 catalog_dirs: 列出多个目录时,该列表是一个有序的先到先得优先级栈:出现在多个所列目录中的实体标识解析到最先列出的目录,后出现的会被遮蔽(属于覆盖,而非错误)。因此,项目可以把自己的目录层叠在共享目录之前,按标识覆盖实体,其余实体则继续落到后面的目录。覆盖情况会在解析详情中报告。同一个目录中有两个文件声明相同标识,仍属于编写错误,会中止加载。
工作区根目录的 catalog/ 目录位于该栈的末尾而非开头,因此发生冲突时,项目列出的任何内容都优先于它;列出一个无关的目录也不会使它停止被读取。当某个列出的条目已经覆盖到它时,会跳过它:对所列目录的遍历是递归的,因此列出工作区根目录的栈已经读取过它。省略 catalog_dirs: 与将其写为空列表是不同的声明:省略时,工作区仍会读取 catalog/;写为 [] 时,则完全不读取本地目录,工作区以此表明自己没有本地目录。
规则 4 — 版本处理
URI 可以包含或省略版本段。版本的处理方式取决于解析位置(Manifest 层级解析、implements: 匹配、子 aggregate 导入),遵循该位置自身的版本使用规则。各实体的版本语义参见 inheritance-and-interface.md 中的“跨实体版本使用”。
格式字符串清单
除 URI 字符串外,Aggrega 的编写界面还包含几种不同的格式字符串约定。编写或阅读 YAML 文件的作者会在不同位置遇到以下格式:
| 格式 | 编写位置 | 校验方 |
|---|---|---|
Go 模板({{ .field }}) | Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:;FeatureRecipe injectMapping: / pipeline with:;Aggregate parameters: 插值;Release directory: / subDirectory: | 求值时的 Go 模板解析器;各位置的可用性规则见 templates/expansion-matrix.md |
Sprig 函数引用({{ default 1 .v }} 等) | 与 Go 模板相同的位置 | 模板引擎初始化时注册的 Sprig v3 FuncMap;完整辅助函数列表见 templates/sprig-functions.md |
| JSON Schema 2020-12(紧凑形式或完整形式) | Component / Feature 的 schema: 内容(或指向 SchemaLibrary 条目的 $ref:) | 解析期间加载实体时的 JSON Schema 校验器 |
| JSON Pointer(RFC 6901) | Recipe locals.<*_path>: 键(volumes_path、containers_path 等);FeatureRecipe pipeline: 步骤输出引用;Wasm 插件 JSONPatch 载荷 | 依据 Wasm 插件契约的 RFC 6901 基线;在 plugins/plugin-contract.md 中声明 |
| SemVer 正则表达式 | 每个实体上的 metadata.version 字段 | 各实体 schema 中的 JSON Schema 正则表达式 ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ |
版本锁定(:<version>、:^<version>) | 实体引用的版本段,适用于上述所有 URI 位置 | 编译器在解析引用时校验:精确锁定须为语义化版本,脱字符锁定的范围须可解析,格式错误的锁定按其自身的条件被拒绝——参见上文 URI 形式 |
| 文件系统路径 | 相对于目录的路径(例如 .aggrega-config.yaml 的 catalog_dirs: 条目);Recipe 在 workload: / artifacts: / valuesMapping: 中的 $import: 文件路径 | 在解析时按书写内容读取——catalog_dirs: 条目相对于声明它的配置文件,$import: 路径相对于实体自身的目录;不展开任何 glob,因此 * 表示以此为名的文件或目录 |
| 标签选择器表达式 | Component.spec.usesSchema.<socket>.selector;Feature appliesTo: / appliesToAnyOf: | 在对选择器求值之处由 Aggrega 选择器解析器处理;选择器语法见 vocabulary/modifier-system.md |
注解键形式(<namespace>/<name>) | metadata.annotations 键;Manifest features.annotations 键;边界注解级联 | 各实体的 JSON Schema 正则表达式;保留前缀规范见 vocabulary/labels-and-annotations.md |
Provider 名称,可选择固定版本(helm、helm:^1.0.0) | Recipe.spec.capability; FeatureRecipe.spec.capability | Provider 分派查找;若没有任何插件版本满足固定版本,构建将中止 |
注入投递键(env.<KEY>、file.<path>、arg.<flag>) | Aggregate inject: 块;FeatureRecipe injectMapping: 输出 | 注入 schema 见 vocabulary/topology-triad.md |
每种格式都有各自的语法、校验器和错误报告形式。遇到格式字符串解析错误的作者可查阅对应格式的参考文档了解语法规则。
编辑器会在你编写时报告这些错误:aggrega serve 会根据所属种类的 schema 验证发送给它的每个文档,并返回与构建相同的结论(参见 cli/aggrega-serve.md 的“实时验证”),而 aggrega scaffold 可以起草任意种类的起始文档。
交叉引用
entities/manifest.md— Manifest 映射层级解析 + 上下文感知简写 URI 一节。entities/plugin.md— Plugin 插槽分类 +plugin/<socket>/<name>插槽编码 URI 形态。architecture/13-catalog-and-registry.md— 三层实体解析模型 + 用于目录分发的规范 OCI 分类。vocabulary/inheritance-and-interface.md—implements:接口绑定 + 跨实体版本使用。templates/expansion-matrix.md— Go 模板格式字符串在各模板位置的可用性规则。templates/sprig-functions.md— 接入模板引擎的 Sprig v3 辅助函数清单。vocabulary/topology-triad.md— 注入交付键约定;选择器表达式语法见vocabulary/modifier-system.md。vocabulary/labels-and-annotations.md— 注解键形态与保留前缀规范。10-status.md—implements:三种形式匹配以及解析引用的 CLI 命令的就绪状态。