本页面由机器翻译。阅读英文原文。
Aggrega Catalog(Component)schema
自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。
Schema id:https://aggrega.ai/schemas/component-v1beta1.schema.json
原子构建块的抽象定义。
有关编写 Component 实体的文字指导,请参阅 Component 编写参考;本页记录该参考所描述的结构化 schema。
顶层类型: object
属性
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | 是 | 常量:"aggrega.ai/v1beta1" |
kind | const “Component” | 是 | 常量:"Component" |
metadata | object | 是 | |
spec | object | 是 | 用于约束开发者不透明 values 载荷的校验与 schema 定义。 |
不允许其他属性。
component.metadata
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | 长度至少为 1 个字符。 |
version | string | 是 | 接口的严格语义化版本(例如 1.0.0)。模式:^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$。 |
description | string | 否 | 说明该实体是什么、用于什么,面向正在决定是否使用它的人。先用一句话点明它是什么,再补充读者为正确选择和使用它所需了解的内容——它对部署它的 Release 有什么期望,以及它的行为中任何出人意料之处。通常写一个简短的段落即可。 |
maintainers | object[] | 否 | 拥有此实体的维护者列表。 |
license | string | 否 | 此实体所描述软件的许可证 SPDX 标识符,例如 MIT 或 AGPL-3.0。它记录的是该软件的条款,而不是此文件的条款。 |
repository | string | 否 | 源文件所在 Git 仓库的 URL。 |
home | string | 否 | 此实体的主页、wiki 或文档的 URL。 |
keywords | string[] | 否 | 用于提升 UI 可发现性的描述性关键字列表。 |
labels | object | 是 | 用于声明特征的鸭子类型标签。必须包含保留键 ‘component.aggrega.ai/type’。 |
annotations | map of string | 否 | 由 Platform Architect 在 Domain 2 中编写的、不可变的组件固有特征。向下级联到 .context.annotations.catalog 存储桶。 |
不允许其他属性。
component.metadata.maintainers[]
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
name | string | 是 | |
email | string | 否 | |
url | string | 否 |
不允许其他属性。
component.metadata.labels
用于声明特征的鸭子类型标签。必须包含保留键 ‘component.aggrega.ai/type’。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
component.aggrega.ai/type | string(枚举) | 是 | 保留的分类轴,指明该组件属于哪一类事物。Aggrega 定义了此键及其可接受的值,因此该集合是封闭的;若要按你自己的轴对组件分类,请在此键旁添加你自己的标签键。允许的值:"server"、"worker"、"task"、"function"、"stateful-server"、"resource" |
component.spec
用于约束开发者不透明 values 载荷的校验与 schema 定义。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
extends | string | 否 | 该 Component 所扩展的基础 Component 的 URI。扩展组合的是结构:基础的 metadata 标签与注解、其挂载槽(featuresSchema)、其自注入允许列表(inject)以及其拓扑插槽(usesSchema)均被继承,该 Component 可以在其上添加,或逐键替换继承的条目。基础的数据支柱不会被组合——基础的 schema 块按基础编写的原样继承,因此扩展的 Component 写作 schema: inherited,且不编写任何自己的支柱内容。 |
featuresSchema | map of object | 否 | 声明式挂载槽定义:该实体期望挂载 Feature 的具名绑定点。槽约束哪些填充可以绑定它(selector)以及填充的材料如何交付(inject);填充自身的 Feature 拥有其 values 和 infra 契约。声明槽从不会封闭挂载块——作者可以用任何槽都未声明的名称挂载 Feature,因此同一个实体既可服务于槽填充的挂载,也可服务于在更大范围共享的凭据。槽是绑定点,而不是依赖插槽:usesSchema 声明的是独立的拓扑面。 |
inject | string[] | 否 | 允许列表中的自注入交付机制(例如 [‘env’, ‘file’, ‘arg’])。存在时,开发者可在 Aggregate 中组件级别使用 inject: 块,将自己的 values 或 provides 键直接注入交付管道。若省略,则禁止组件级自注入(黑盒模式——由 Recipe 处理所有内部连线)。语义与 usesSchema[].inject 相同,但约束的是组件自身的 values,而非跨组件拓扑。可以列出除 all 以外的任何机制名称;任何 inject 块都不能使用 all 这个名称。 |
usesSchema | map of object | 否 | 该实体声明的依赖插座,以插座名称为键;通过某个插座建立的每个连接都会对照该插座的声明进行检查——其选择器、它允许的 inject 机制以及其逐连接契约。键:一个或多个字母、数字、下划线或连字符。不允许使用点号。模式:^[a-zA-Z0-9_-]+$。 |
schema | any | 否 | 涵盖自由形态支柱的 JSON Schema 2020-12 内容:values(Developer 的领域——Developer 在 Aggregate 中为每个 Component 实例配置的应用形态参数);infra(Operator 的领域——由 Release 提供的物理规格调节项);以及 provides(该 Component 通过拓扑管道向消费者公开的下游上下文键)。通过内容形态分派接受四种编写模式:(1) 内联内容(承载紧凑形式、JSON Schema YAML 或混合形式的 YAML map);(2) 通过 {$import: |
assertions | map of string | 否 | 构建时的跨字段校验。每个条目都是一个命名断言:键是一个稳定的规则标识符,会在错误消息中显示;值是一个 Go 模板字符串,具有 {{ fail "message" }} 的中止语义。每个实体的多个命名断言按作者声明的顺序逐实例求值;第一个失败的断言会中止构建。Component 断言在解析和静态分析之后、渲染之前求值,表达的是契约的架构不变量,无论绑定的是哪个 Recipe 都成立。模板上下文:.values / .infra / .uses / .features / .metadata。求值器使用 missingkey=error:引用未定义的键会以 no-such-key 诊断中止。由于裸引用在任何回退执行之前就会中止,在此处普通的 default 无法为可选字段提供回退——请用 hasKey 保护该引用,或使用 optional 辅助函数,它会直接执行存在性检查。通过 index 读取该键同样无法提供回退:index 在映射中不存在该键时会中止,并给出该键的名称。继承是累加的:声明了 extends 的 Component 会同时按其继承的断言和自身的断言求值,继承的规则在前;任意深度的继承链从链根向下累积——因此当不止一条规则会失败时,报告的是在链中声明位置最靠上的那条。复用继承来的名称来声明不同的规则,会在针对目录解析 extends 链时被拒绝,并给出两个 Components 的名称以及共用的名称——因此该错误在基础 Component 存在时才会出现,而不会仅凭扩展文档本身出现;扩展的 Component 只能添加规则,绝不能替换规则。在同一名称下逐字节重述继承的规则是允许的,它本身就是一个空操作。不会检查两条规则能否同时成立:互相无法同时满足的一对规则属于编写错误,它会在某个实例触发先生效的那条时表现为普通的断言失败,而绝不会预先给出警告。 |
不允许其他属性。
定义
extending-component-must-declare-schema-inherited
在存在 spec.extends 时适用。扩展型 Component 会原样获得其基础 Component 所编写的 values / infra / provides,因此它声明 spec.schema: inherited,且不编写任何支柱内容。另外两种情况都是错误,而且是不同的错误:完全省略 spec.schema,这会让读者无法区分继承而来的支柱块与被遗忘的支柱块;以及在 spec.schema 下编写支柱内容,这相当于在一个契约本就来自其基础的 Component 上要求第二份、相互分歧的契约。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
schema | const “inherited” | 是 | 继承标记,也是声明了 extends 的 Component 上 spec.schema 唯一可取的值。它指明支柱的来源;支柱内容本身属于基础 Component。常量:"inherited" |
non-extending-component-authors-its-own-schema
在不存在 spec.extends 时适用。不扩展任何基础的 Component 在 spec.schema 下编写自己的 values / infra / provides 内容,因此该字段承载的是编写的内容,而非继承标记:该标记表示支柱来自某个基础,而此 Component 没有基础。
| 属性 | 类型 | 必需 | 描述 |
|---|---|---|---|
schema | object | 否 | 编写的支柱内容——一个映射,采用 spec.schema 所记述的三种内容编写模式中的任意一种。 |