命名约定
本章介绍适用于所编写的 Aggrega 内容的命名和大小写规则:用户编写的实例名称所遵循的模式、DSL 中字段名称的大小写规范、平台(而非你)为其定义的标识符所使用的大小写,以及 YAML 编写层面所使用的注释语法。
实例名称
用户编写的实例名称——开发者为 component、feature、aggregate、子系统、边界以及 uses 插槽和别名编写的键——都匹配同一个模式:^[a-zA-Z0-9_-]+$。kebab-case(pii-filter、my-agent)和 snake_case(openai_key、db_credentials)均有效;团队可以采用自己偏好的任一约定。
**允许的字符:**字母数字(a-z、A-Z、0-9)、连字符(-)和下划线(_)。不允许使用其他字符。
示例:
components: web-server: # kebab-case finance_worker: # snake_case
features: pii-filter: # kebab-case audit_logger: # snake_case openai_key: # snake_case — natural for a credential attachment db-password: # kebab-case — also valid| 模式 | 范围 | 示例 |
|---|---|---|
^[a-zA-Z0-9_-]+$ | 所有用户编写的实例名称 | web-server, openai_key, pii-filter |
该模式在解析阶段通过 JSON Schema patternProperties 强制执行。
component 名称的代价,以及为什么大写字母在某些目标下代价更高
上述模式说明的是你可以写什么。一个名称的代价是另一个问题,它因 component 部署到的目标而异——因此值得在选定名称之前了解,而不是等到构建拒绝某个名称时才知道。
component 的名称会成为它所生成的每个资源上标记的标识,而每个目标都会从该标识派生自己的名称:chart 安装器派生出 release 名称,容器编排器派生出服务名称。字母表比该模式更窄的目标无法承载它不接受的字符,而 Aggrega 不会悄悄把这样的字符折叠为某个相似字符——作者能够区分的两个名称,不能在集群中变成同一个名称。因此,目标不接受的字符会被改写为转义序列,而转义序列比它替换的字符更长。
实际结果:大写字母在某些目标下没有代价,在另一些目标下代价高昂。
- 在名称允许大写的目标下——例如容器编排的 compose 文件——
PaymentsAPI会完全按你编写的样子保留,占用 11 个字符。 - 在名称只允许小写的目标下——例如 chart 安装器的 release 名称——每个大写字母都会被转义,仅由 6 个大写字母组成的名称就已经超出该目标接受的长度。
还有第二个影响,而且更为严重:转义序列以连字符开头。因此,要求名称以小写字母或数字开头的目标,会拒绝首个字符为其不接受字符的名称,无论其余部分多短——任何缩短都无法解决这一点。
**指导建议源自这两个影响。**优先使用小写字母和数字,单词之间用连字符分隔,并以小写字母开头。对于 Aggrega 提供了 provider 的每个目标,payments-api 都会原样保留。payments_api 在 compose 文件中会原样保留,但在 helm 目标中不会,因为后者的资源名称不允许下划线:它以该 component 命名的 Service、workload 和 release 会写作 payments-zuapi。PaymentsAPI 在那里的代价还要更高。发布此类资源地址的 Recipe 会读取目标自身的拼写,而不是去预测它——参见 templates/rendered-resource-names.md。
以数字开头在书写上是合法的,在 compose 文件下也没有代价,但 helm 目标会拒绝它。Kubernetes Service 名称必须以字母开头,而 chart 或合成的 workload 所生成的 Service 以 component 命名,因此名为 1cache 的 component 会使 helm 构建停止——拒绝信息会指出该 component,并说明 Service 名称必须以字母开头——而不是渲染出集群会拒绝的 Service。
这些都不是编译器自行施加的规则——它不持有任何目标的命名规则,也不自创任何限制。每个目标的 provider 自行负责其名称,因此只有当 component 实际部署到的目标表示无法使用某个名称时,该名称才会被拒绝,并且拒绝信息会带有该目标自身的原因,并指向你编写的 spec.components 键。一个名称在某个目标下没问题、在另一个目标下被拒绝,这是预期行为,而不是不一致。
Aggrega 自己组合的名称——例如附加在边界上的 feature 的标识——则以相反的方式处理:它们会被缩短以适应目标,而不是被拒绝,因为它们由在多处编写的部分拼装而成,没有任何单个作者能看到其最终长度。只有你编写的名称才会被拒绝。
点号作为保留的路径分隔符
句点字符(.)在所有用户编写的实例名称中均为保留字符。点号承担结构性用途:作为编译器生成的路径分隔符,用于跨 aggregate 的 component 引用。
当根 Aggregate 导入一个名为 data-layer 的子 aggregate,且其中包含名为 main-db 的 component 时,编译器会用点号连接 aggregate 实例名称和 component 实例名称,构造出扁平化的绝对 ID data-layer.main-db。这种带点路径出现在:
- 开发者的
uses目标:target: data-layer.public_db——引用嵌套 aggregate 中导出的 component。 - **构建自身的诊断信息:**关于该 component 的中止或警告会以其带点路径来指称它,因此你读到的名称就是可以在文档中搜索的名称。
分隔符不会进入名称
带点路径是文档内部的地址,它不是部署目标会接受的名称。Kubernetes Service 名称完全不允许点号;更糟的是,集群地址中的点号用于分隔服务与其所在的命名空间,因此把带点名称作为主机交给使用方时,它会解析到另一个服务,而不是直接失败。
因此,构建从 component 标识派生出的每个名称和标签中,分隔符都会被转写掉,而且是转写而非替换:data-layer.main-db 会变成 data-layer-zdmain-db。若用目标接受的某个字符替换它,两个不同的 component 就可能得到同一个名称——data-layer.main-db 和某人写作 data-layer-main-db 的 component——而两个 component 共用的名称无法标识其中任何一个。
它影响哪些内容,不影响哪些内容:
- 它影响从标识派生出的名称和标签——Aggrega 合成的资源上的
metadata.name、aggrega.ai/component-id和app.kubernetes.io/name标签、匹配这些标签的选择器、输出的文件名、{{ .context.instance_id }},以及 provider 为自身派生的名称,例如 helm release 名称。它们会一同变化,因此 Recipe 根据命名资源的键组合出的地址——目标以标识命名资源时为.context.instance_id,目标报告自有名称时为.context.rendered_name——仍然指向构建输出的资源。 - **它不影响你编写的名称。**不含分隔符的 component 名称会逐字节原样返回,因此只有导入的 Aggregate 所提供的 component 在输出中的拼写才会与文档中不同。
- **它不影响作者提供的 chart 或片段内部的名称。**这些名称属于其编写者,从第三方 chart 中带出的名称——例如形如
<plural>.<group>的自定义资源名称,其中点号是合法的——会完全按照该 chart 的写法输出。
🔴 **最后这一点会影响 Recipe 应当发布的内容,也是本页最容易出错的地方。**所提供 chart 自身的模板会以平台交给它们的标识来命名资源——即 release 名称,按该平台自己的字母表书写,而不是按上文的字母表——而 helm 目标也会以同一个 release 名称来命名它合成的工作负载。因此,对于从你提供的源渲染出的输出,以及在此类目标下合成的工作负载,{{ .context.instance_id }} 并不是这些资源所带的名称,只要两种字母表不同,据此发布的地址就不指向任何资源。承载平台名称的键以及哪些 provider 会报告该名称,参见 templates/rendered-resource-names.md。
转写分隔符会占用字符,有长度上限的名称可能因此不够用。分隔符被替换为一个简短的转义序列而非单个字符,因此限定标识转写后会比在文档中读到的略长。这只在其最终名称有长度上限时才有影响:渲染 component 的目标会说明它接受的标签值长度,若转写后的标识超出该长度,构建会中止,而不是输出目标会拒绝的值。中止信息会说明标识本身必须满足的长度——即转写之前的长度,因此在此长度内选定的名称一次就能通过——修复方法是缩短作者编写的部分:导入文档为子 aggregate 指定的名称,或其中 component 自身的名称。
分隔符是名称转写后变长的常见原因,但不是唯一原因。作者编写的名称可以合法采用的两种形式也无法按原样保留,因为保留它们会让转义产生歧义:以连字符结尾的名称,以及连字符后紧跟 z 的名称。二者都以同样的方式转写,代价相同。其他所有作者编写的名称都会逐字节原样返回,因此由字母、数字、下划线以及词间连字符组成的名称完全不受这些影响。
组件自身 uses 块中的插槽名称,要么匹配目录实体 usesSchema 中的某个键(即已声明的插槽),要么命名开发者自己的临时插槽;后者即使在完全未声明 usesSchema 的实体上也能构建。与某个已声明插槽仅差一处编辑的名称会引发一条同时列出两种拼写的警告。Release 的逐边 uses 以及 Feature 附件中的同类设置只能命名实体所声明的插槽,任何其他名称都会以 unknown-uses-socket 校验错误失败。
字段大小写
DSL 将面向开发者的 YAML(由人编写)与编译器内部契约(由模板和工具使用)区分开来:
- 面向开发者的 YAML(camelCase): Aggregate、Release、Component、Feature、Recipe、FeatureRecipe、Manifest 和 Plugin schema 中的多词字段名使用 camelCase。示例:
exportedComponents、syncWave、subDirectory、featuresSchema、usesSchema、valuesMapping、injectMapping、executionScope、appliesTo、appliesToAnyOf、conflictsWith。遵循 Kubernetes API 约定。 - 内部契约(snake_case): IR Graph schema 和 Template Context schema 中的多词字段名使用 snake_case。Recipe 作者会遇到的面向用户的示例:
instance_id(位于.context.instance_id中,即该 Recipe 的标识)、inject_raw(位于.inject_raw中,它是与.inject并列的顶层支柱,而不是.context下的键,即未经修改的注入契约)、attachment_name(位于附加型 FeatureRecipe 的上下文中,标识该附加所填充的槽位,或其附加时使用的名称)。遵循 JSON API 约定,并与 Go 的 JSON struct tag 生成保持一致。 - 单词字段: 无论上下文如何均为小写。示例:
values、infra、inject、provides、locals、features、labels、annotations、boundaries、components、subsystems、pipeline、source。
开发者在自己编写的 YAML 中不会遇到 snake_case,模板作者在 Go 模板中也不会遇到 camelCase。schema 的新增内容遵循这些约定。
一条语句中交汇的三种大小写
编写 Recipe 时,经常会在一条语句中同时跨越全部三种大小写约定:schema 定义的 DSL 字段使用 camelCase,用户编写的实例名使用 kebab-case 或 snake_case,模板上下文引用使用 snake_case。把这些交汇视为各自独立的约定的作者,能顺畅地读懂由此得到的 YAML;试图把这些大小写归结为一种约定的作者,则会在边界处感到困惑。
典型的示例:一个 Recipe 的 valuesMapping: 模板通过模板上下文引用被渲染的 Component 实例。
# Recipe authored against a Component the developer instantiated as "web-server"# (kebab-case instance name) in their Aggregate.spec: valuesMapping: | # camelCase — schema-defined DSL field name: "{{ .context.instance_id }}" # snake_case — template context # internal contract image: "{{ .values.image }}" # snake_case — template context # internal contract三种大小写,一条语句:
valuesMapping—— camelCase。schema 为 Recipe 的映射模板定义的 DSL 字段名。使用驼峰式,是因为该语言面向开发者的 YAML 遵循 Kubernetes API 约定。web-server(通过被渲染的 component 间接引用)—— kebab-case。Aggregate 中由用户编写的实例名;开发者选择了连字符形式。同样也可以是web_server(snake_case);按照实例名模式,两者均有效。instance_id、image—— snake_case。模板上下文中的字段名(.context.instance_id、.values.image)。使用蛇形式,是因为 IR Graph 和模板上下文遵循 JSON-API 约定,并与 Go 的 JSON struct tag 生成保持一致。
这三种大小写不可互换。Recipe 作者如果写成 {{ .context.instanceId }}(camelCase),构建会中止:.context 声明了自己的键,而 instanceId 不在其中,因此该引用在任何渲染之前就会被拒绝,诊断信息会列出 .context 确实定义的键 —— 参见 errors/fatal-halts.md 中的“Template references a root the render context does not define(模板引用了渲染上下文未定义的根)”。开发者如果写成 web.server(带点),会被实例名模式拒绝,因为点被保留为路径分隔符。要达成的规范目标:在阅读或编写时记住这三种约定;依靠边界(你位于 YAML 中还是模板中)来判断适用哪种大小写。
平台定义的标识符
以上内容约束的都是编写层面的名称:你选择的实例名、语言定义供你填写的 schema 字段、你读取的模板上下文键。另有两套命名体系约束平台自身定义、你只需读取或输入的标识符。它们之所以分开,是因为承担的职责不同,而职责决定了形式。
描述型体系:统一使用 kebab-case。 这类标识符用文字说明它所指代的对象,因此你无需查阅任何资料即可读懂并据此操作。CLI flag、发布 lint 规则 id、诊断类别代码,以及登记中止条件所用的代码,都属于这一体系。
--no-unsupported-field-warnings # a CLI flag you typecategory-matches-directory # a lint rule id, printed in `aggrega lint` outputunsupported-field # a diagnostic class codeartifact-provenance-skipped # anotherparameter-contract-violation # the code a halting condition is registered under当某个诊断类别有对应的抑制 flag 时,代码与 flag 由相同的单词按相同顺序组成——unsupported-field 由 --no-unsupported-field-warnings 静默——因此你匹配到的类别直接告诉你该用哪个 flag,无需任何转换。类别代码是工具用来识别某项检查结果的稳定名称,无需解析其消息文本;消息措辞可能改进,代码则保持不变。
短代码体系:字母 E 加四位数字。 中止条件还带有一个短代码——E0007——它是唯一不采用 kebab-case 的平台定义标识符。原因在于位置:它位于每条中止诊断的开头,紧挨类别,排在你接下来要读的文件和行号之前。
[DEVELOPER_ERROR E0007] aggregate.yaml at .spec.components.edge描述型代码无法放在这里。其中最长的一个单独就能占满一个窄终端,而后面还有告诉你去哪里查看的位置信息。因此开头采用按宽度选择的标识符,这一取舍是有意为之:四位数字并不说明任何条件,所以每个短代码都与它所指代的条件以及该条件渲染出的文本一同发布在错误哨兵参考中。在报告中引用短代码,在搜索中输入它,然后到那里查明其含义。
两套体系从两个方向指代相同的条件,彼此不可替代。编写以条件为键的工具时,匹配描述型代码;与人沟通某个条件时,引用短代码。
kebab-case 同时出现在这里和实例名中并不构成冲突。 实例名模式关注的是你可以写什么——kebab-case 和 snake_case 在那里都有效,由团队选择其一。这一体系关注的是平台实际写什么,其中没有选择余地:你从不决定 lint 规则 id 的拼写,平台也从不决定你的组件名的拼写。
它不改变字段的大小写形式。 编写的 schema 字段仍为 camelCase,模板上下文键仍为 snake_case。这一体系中的标识符都不是这两个层面上的字段——它们是 flag、规则或检查结果类别的简短、稳定的名称——因此诊断代码采用 kebab-case 并不说明 schema 字段如何拼写。
文档路径命名后缀规则
语言中有一部分字段携带文档路径值——即指向另一文档内某个位置的字符串(已渲染 Workload 的 volumes 部分、Component 的 featuresSchema 条目、Manifest 的 mappings 层)。这些值遵循 RFC 6901 JSON Pointer 语法——以斜杠分隔的标记,标识穿过目标文档的路径。
RFC 6901 是 Aggrega 中每个文档路径接口的路径语法基准。 Wasm 插件契约使用路径为 RFC 6901 指针的 RFC 6902 JSON Patch 文档(参见 plugins/plugin-contract.md 中 label-transform 角色的 JSONPatch 输出);URI 语法的格式字符串清单将 RFC 6901 与 Go 模板语法和 Sprig 辅助函数并列(参见 vocabulary/uri-grammar.md “Format-string inventory”);每个 Recipe 的 .locals 导出使用 RFC 6901 指向合成 Workload 中的位置,Wasm Injector 插件在插件流水线中通过其步骤的 with 载荷接收这些位置。一种语法,多个使用接口。
命名后缀规则通过一种有意设计的后缀划分来区分这些路径值的两个编写侧,与上文更宽泛的字段大小写一节保持一致:
- 携带 RFC 6901 JSON Pointer 的模式字段使用 camelCase
*Path后缀。这些字段属于面向开发者的 YAML 模式,因此遵循 camelCase 约定。没有任何实体模式声明这样的字段;作者编写的文档路径是下文的.locals导出键。 - 携带 RFC 6901 JSON Pointer 的
.locals导出键使用 snake_case*_path后缀。这些键属于 Recipe 的内部导出接口——由该 Recipe 自身的后续模板读取,也由 Wasm 插件流水线通过引用.locals的pipeline[].with载荷读取——因此遵循 snake_case 约定。示例:volumes_path——.locals.volumes_path: "/spec/template/spec/volumes",暴露合成 Workload 的 volumes 数组位置。containers_path——.locals.containers_path: "/spec/template/spec/containers",暴露 containers 数组位置。resource_path——.locals.resource_path: "/resource/aws_s3_bucket/main",暴露 Terraform 原生资源路径。root_path——.locals.root_path: "/data",暴露渲染器管道所使用的根路径。
这两种后缀约定反映了字段大小写一节的两层约定:由模式定义的字段使用 camelCase;用户编写的或 Recipe 私有的标识符使用 snake_case(或 kebab-case)。*Path / *_path 后缀规则使值的路径语法性质在标识符层面即可见——读者看到任一后缀,就知道该值遵循 RFC 6901 语法,无需检查值本身。
完整示例:Wasm Injector 使用 Recipe 的 *_path 导出。
# Recipe (Domain 3) — declares .locals exports the Wasm Injector consumesspec: locals: primary_compute: "worker-container" containers_path: "/spec/template/spec/containers" volumes_path: "/spec/template/spec/volumes"# Credential FeatureRecipe (Domain 3) — attached to the component the Recipe# above realizes. Its templates read `.locals`: an attachment sees the host# Recipe's resolved locals merged with the attachment's own block.spec: pipeline: - id: workload_injector plugin: pipeline-step/k8s-workload-injector:2.0.0 function: inject_secret with: | target_container: "{{ .locals.primary_compute }}" containers_path: "{{ .locals.containers_path }}" volumes_path: "{{ .locals.volumes_path }}"*_path 键是 Recipe 私有的导出;containers_path / volumes_path 的值是 RFC 6901 JSON Pointer 字符串。Injector 插件使用这些字符串,将其 JSONPatch 输出定位到已渲染 Workload 的 AST 上。附加项通过其自身的 .locals 支柱访问它们——不存在 .context.uses[].locals 字段,因此使用方无法跨 uses 边读取其目标的 locals;跨边传递的是目标的 provides。
更完整的格式字符串清单(Go 模板语法、Sprig 函数、JSON Pointer,以及 SemVer 正则表达式和标签选择器语法),参见 vocabulary/uri-grammar.md “Format-string inventory”。使用以 RFC 6901 指针寻址的 RFC 6902 补丁的 Wasm 插件契约接口,参见 plugins/plugin-contract.md。
注释语法
注释字符取决于所处的语言:
- YAML 上下文(每个 Aggrega 实体的默认编写界面):使用
# - Go 模板上下文(位于 Recipe 的
valuesMapping:块标量、FeatureRecipe 的injectMapping:块标量、MappingLibrary 的映射条目、断言块的assertions:主体之内):模板注释使用{{/* ... */}},模板引擎会识别它并在渲染时将其去除;模板主体之外的 YAML 级注释则使用#。
schema:、usesSchema:、featuresSchema: 和 parameters: 下的紧凑形式 schema 全部是 YAML;逐字段的 description: 注解是有文档说明的内联字段文档界面(port: { type: integer, description: "TCP listen port" })。