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

Parameters 模板上下文

parameters: 支柱承载由 Release 填充、经契约校验的参数值。其可访问性由两种并行的心智模型决定:

  • 值模板表面(Aggregate 内 component / feature / sub-aggregate 的 values: 字符串,以及 Recipe 的 valuesMapping、FeatureRecipe 的 injectMapping 和 provides、Workload 主体)以已插值的字面量形式使用参数值。解析过程中的插值步骤将 Aggregate 的全部文本作为模板求值,并把每个 {{ .parameters.<slot> }} 引用替换为解析后的值;下游的值模板表面在其模板上下文中永远不会直接看到 .parameters。
  • 路径模板表面(Release 边界上由运维人员编写的 directory: 和 subDirectory: 模板)在渲染期间进行路径模板求值时直接读取 .parameters.<slot>。合并后的参数映射在渲染结束前始终可读,以便路径模板能够依据封闭的允许列表读取 .parameters。

这种不对称的授权——路径模板直接读取 .parameters,值模板则不能——让每一层各自掌握所需的内容:开发者侧的 values: 将已解析的环境特定数据传递给值模板;运维侧的路径模板引用区域 / 环境 / 账户 ID 参数,而无需绕经 Aggregate 的 values schema。

本页说明插值步骤、各槽位的值结构、Aggregate YAML 字符串中的访问模式、路径模板的例外,以及合并映射保持可读的时长。关于更宽泛的 Recipe / FeatureRecipe 模板上下文结构(.values、.infra、.uses 等),参见 template-context-contract.md。关于编译流水线中各模板位置的可用性,参见 expansion-matrix.md。关于 Aggregate 上类型化参数契约的声明结构,参见 entities/aggregate.md §“Typed parameter contracts”。关于在边界 directory: / subDirectory: 求值时包含 .parameters.<slot> 的路径模板变量允许列表,参见 path-template-variables.md。

参数生命周期

编译器按四个有序阶段解析参数:

  1. 读取契约——在查看任何 Release 值之前,先单独检查 Aggregate 的 spec.parameters: 块,因此即使没有 Release 提供某个槽位,一个无法约束任何内容的槽位也会中止构建。参数自身声明上为负数的 minLength 或 maxLength 会在 Aggregate 加载时被拒绝,并指出参数名和键名。每个 pattern(无论位于槽位本身,还是位于 items、properties 或 valuesType 下的任何嵌套契约中)都会被编译为正则表达式,无法编译的 pattern 会被拒绝,并指出参数、pattern 及原因。嵌套契约中的长度界限不受该下限约束;参见 entities/aggregate.md。
  2. 默认值填充——定义了 default: 且没有 Release 提供值的槽位会获得其默认值。此时 .parameters 映射处于作用域内。
  3. 参数契约校验——合并映射中的每个值,无论由 Release 提供还是由 default: 填充,都会按照 Aggregate 的 spec.parameters.<slot> 所声明的 type / enum / min / max / pattern / 嵌套结构约束进行校验;pattern 会与读取契约时编译好的表达式进行匹配。.parameters 映射作为被检查的结构化载荷,存在于校验器的内存上下文中。
  4. 插值——编译器在将 Aggregate 的整个文本作为 YAML 读取之前,先将其作为模板求值,并用解析后的值替换每个 {{ .parameters.<slot> }} 引用;文本中的其他任何 {{ 也会被当作模板语法读取,因此自带双花括号的值要将每个 {{ 写成 {{"{{"}}(参见自带双花括号的文本)。插值是值模板表面的替换路径——经过这一步后,值模板的上下文不再携带 .parameters;它们使用已写入所在 values: 字符串中的解析值。合并映射在插值之后仍然可读,贯穿整个渲染过程,专门用于支持路径模板求值。其可读生命周期以构建为界:编译器将解析后的视图交给使用它的编译过程,而不是返回给调用方,因此该构建之外的任何内容都无法访问该映射。路径模板表面(Release 的 directory: / subDirectory:)在渲染期间按照 path-template-variables.md 中记录的封闭允许列表读取 .parameters.<slot>。

Aggregate YAML 字符串中的模板(component 的 values:、feature 的 values:、sub-aggregate 的 parameters: 透传表达式)在插值阶段通过标准 Go 模板语法读取 .parameters 映射。Recipe 和 FeatureRecipe 文件中的模板在其模板上下文中不会获得 .parameters(各表面的契约参见下文“与下游模板上下文的边界”)。

自带双花括号的文本

由于整个文本都是模板,属于值而非模板的双花括号也会被读作模板动作。常见情况是在某个 component 的 values: 中携带流程平台的定义:n8n 会把节点参数中的每个表达式包在双花括号中,例如 ={{ $json.body.message }};Flowise 的提示词以 {{question}} 的形式命名变量,Flowise 的 chatflow 为两个节点之间的每条连接写入 {{chatOpenAI_0.data.instance}};Langflow 的导出文件则携带其组件的源代码,其中同样可能出现这种花括号。若原样写入 Aggregate,它们会使构建在该 Aggregate 处以 E0158 停止,该错误在 Fatal halts 中的“A {{ .parameters.* }} reference cannot be interpolated(该参数引用无法插值)”下说明;其原因会指出行号以及模板引擎无法读取的第一个记号——对于 n8n 表达式是 undefined variable "$json"。YAML 注释同样是模板文本,因此写在注释中的 {{ 也会以同样方式停止构建。

将此类值中的每个 {{ 写成 {{"{{"}}。这是一个结果为字符串 {{ 的模板动作,因此插值会把两个花括号还原。闭合的 }} 无需处理,因为在动作之外它是普通文本。插值只在 Aggregate 的文本上运行一次,而 Recipe 模板会将其从 .values 读取的内容作为数据原样写出,因此还原后的花括号会按导出时的样子到达渲染输出。

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

平台接收到的是 "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}"。

如上所示,将此类定义放在块标量(|)中,其中转义的引号只是普通字符。Aggregate 的文本在插值之前也会被读作 YAML,而在双引号 YAML 字符串中,转义里的 " 会闭合该字符串,导致文件无法解析,构建以 YAML 错误中止。

.parameters.<slot> 访问模式

每个已声明的参数槽都可以作为 .parameters 映射上的字段访问。类型正确的访问与声明的 type 一致:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

插值阶段针对 .parameters 映射执行 Go 模板求值;结果在文档中原地替换模板表达式。随后,在解析的插值后 schema 校验阶段,由 Component / Feature 的 values: schema 校验所得的值。

引号决定提升后的类型

指向字符串叶子的引用要加引号;对于其他所有声明类型则不加引号。 这条规则是 YAML 本身的规则,而非 Aggrega 额外添加的:插值只是将已填充的值代入文档的字节,不做其他任何事,因此随后的解析读取结果的方式与读取任何其他标量完全相同。不加引号的 {{ .parameters.cache_ttl_seconds }} 携带已填充值自身的类型,正因如此,整数参数才能到达整数叶子,布尔参数才能到达布尔叶子。加引号的 "{{ .parameters.cache_ttl_seconds }}" 携带的是字符串,声明为 integer 或 boolean 的叶子会拒绝它:编写的值在类型上无法通过其 Component 或 Feature 的 values: schema,诊断信息指出的是类型不匹配,而不是该字符串同样未能满足的任何值空间约束。

与其他文本共享同一标量的引用,无论怎样书写都是字符串,因为代入后的文档只有一个标量可读——image: app:{{ .parameters.tag }} 得到 app:1.4.0。当非字符串参数需要落入字符串叶子时,应使用这种形式。

对象类型与数组类型的槽位访问

对象类型的参数槽位将其声明的属性作为 .parameters.<slot> 映射上的嵌套字段公开。数组类型的槽位提供 Go 模板的切片语义(range、index、len)。

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

数组类型的参数槽位支持通过 range 进行迭代:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Release 提供的每个元素都会在插值之前按照 items 契约进行检查,因此一个不是主机名的值(例如 *)会中止构建,并指出该参数、该元素和该格式。format 接受的名称及其各自检查的内容列于 vocabulary/compact-form-authoring.md。

插值期间可以使用 Sprig 模板库,它提供了诸如 join 之类的辅助函数,用于简洁地将数组转换为字符串:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

默认值填充语义

声明了 default: 的参数槽位,在 Release 省略该槽位时接收其默认值。默认值在契约校验阶段运行之前应用,因此校验看到的是解析后的值(由 Release 提供的值或默认值):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

标记为 required: true 且没有 default: 的槽位,在 Release 省略它时会触发构建时错误(E0165)。该错误会指出槽位及其在契约中的位置,供作者修复。既没有 required: true 也没有 default: 的槽位是可选的:省略时,对它的每个引用都插值为空,随后由 Component 的 values: schema 评判结果。

嵌套对象参数

当参数声明 type: object,且其 properties: 的子项本身带有 default: 值时,三种编写情形会产生不同的结果。当参数声明是一个结构化对象(数据库配置、功能开关集合、超时与重试策略),而不是单个标量时,理解这种区别很重要。

情形 1——Release 省略父槽位。 契约中子项的默认值会被填充。声明嵌套默认值的 Aggregate 作者得到其预期的行为:当运维未提供该槽位时,配置使用文档中说明的默认值。

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

情形 2——Release 将父项编写为显式的空映射。 显式的空值被视为有意的选择退出而予以遵从。子项的默认值不会被填充;槽位保持为空。当运维希望抑制契约的嵌套默认值、又不提供覆盖值时,使用这种形式——例如,下游使用方期望该槽位存在但为空时。

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

与情形 1 的区别是有意为之:运维既可以表达“使用默认值”(省略槽位),也可以表达“抑制默认值”(将槽位编写为 {})。这与 Aggrega 对注解中显式 null 的处理方式一致——编写为 aggrega.ai/<key>: null 的注解是一种有意的选择退出,不同于完全省略该注解。

情形 3——Release 部分编写父项。 Release 提供的子项采用其编写的值;Release 未提供的子项由默认值填充。

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

对于希望覆盖部分字段、其余字段保留契约默认值的 Release 作者,这是常见情形。

何时使用各种形式

  • 省略槽位:当你希望应用契约的默认值时。
  • 编写 {}:当你有意希望槽位存在但为空时——即契约的默认值不适合你的环境,而你又没有覆盖值时。
  • 部分编写:当你希望覆盖部分值,其余部分使用契约的默认值时。

Release 作者如果写下 database: {} 并期望“给我默认值”,结果会出乎意料——解析后的值为空,而不是填充后的默认值。要获得默认值,请完全省略该槽位。

这种三情形分派在每个嵌套深度上按同级项逐一进行。编写为 { connection: {}, other_field: "x" } 的父项会产生这样一棵解析树:connection 为空(深度 1 处的情形 2),other_field 为 Release 提供的值(深度 0 处的情形 3)——各情形针对每个同级项独立分派,而不是对整个子树做出单一决定。

与下游模板上下文的边界

这种不对称的授权——路径模板直接读取 .parameters,值模板则不能——是这一边界上起关键作用的区别。各个表面上的边界语义如下:

  • 写有 {{ .parameters.X }} 的 Aggregate component-values: 模板会在插值时正确解析。解析得到的字面值会就地写入 YAML 字符串。
  • 写有 {{ .parameters.X }} 的 Recipe valuesMapping: 模板是值模板表面;其模板上下文不包含 .parameters。需要在 valuesMapping: 中按环境变化的作者,应通过已解析的 .values.<key> 消费路径来表达:Aggregate 暴露一个参数,在某个 Component 的 values: 中引用它,由 Release 提供该参数,插值后的值再传递到 Recipe。
  • FeatureRecipe injectMapping:、provides: 或 pipeline.with: 模板是值模板表面,与 Recipe valuesMapping: 相同。.parameters 不在其模板上下文中。
  • Workload 主体模板(Recipe 中的 workload: 内容)是值模板表面,同上。
  • 路径模板(Release 边界的 directory: / subDirectory:)是例外。路径模板的上下文依据封闭的允许列表包含 .parameters.<slot>;引用在渲染放置每个边界的输出时解析。完整的路径模板变量矩阵参见 path-template-variables.md。

四域所有权边界是通过哪个表面接收参数来维护的,而不是通过参数映射在某个流水线阶段是否存在于内存中。路径模板由运维人员编写并归运维人员所有;授予它们直接访问参数的权限,可将运维关注点(按环境的制品布局)保留在运维表面之内。值模板由目录编写;拒绝它们直接访问参数,可使目录侧的编写与“Aggregate 作为唯一事实来源”契约保持松耦合。

合并后的参数映射在所有渲染阶段完成之前一直可读,此后不再可读:它只能从为其解析的那次编译中访问,因此其生命周期受构建的生命周期限制。

跨支柱桥接

参数在解析期间插值到其所在的 values 字符串中。插值后的值可以落入 Aggregate 在其作用域内编写的任何支柱:component values: 字符串、feature values: 字符串、sub-aggregate parameters: 透传声明(父 Aggregate 的参数值先被解析,再传播到子 Aggregate 的参数槽中),以及 metadata name: / labels: 字符串。

这种桥接是单向的:参数值从 Release 提供(或取默认值)的 .parameters.<slot> 流入引用处的 YAML 字符串。参数不会反向流动——参数无法读取 values: 字段、provides: 字段或任何其他支柱的内容。这种方向性是参数契约“仅在编译时”保证的一部分。

交叉引用

  • 关于 Aggregate 上类型化参数契约的声明形式:entities/aggregate.md §“Typed parameter contracts”。
  • 关于 Recipes 在基础渲染时使用的更广泛的模板上下文(.values、.infra、.uses、.context.* 等):template-context-contract.md。
  • 关于编译流水线中各模板位置的可用性(哪些字段在哪个求值位置可用):expansion-matrix.md。
  • 关于参数提升检查清单(四个依次进行的编写环节——Aggregate 声明、values 引用、Release 提供值、Recipe 使用):vocabulary/data-pillars.md §“The parameter-hoisting checklist”。
  • 关于更广泛的数据支柱集合(values:、infra:、provides:、uses:、features:、locals:、parameters:):vocabulary/data-pillars.md。