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。
参数生命周期
编译器按四个有序阶段解析参数:
- 读取契约——在查看任何 Release 值之前,先单独检查 Aggregate 的
spec.parameters:块,因此即使没有 Release 提供某个槽位,一个无法约束任何内容的槽位也会中止构建。参数自身声明上为负数的minLength或maxLength会在 Aggregate 加载时被拒绝,并指出参数名和键名。每个pattern(无论位于槽位本身,还是位于items、properties或valuesType下的任何嵌套契约中)都会被编译为正则表达式,无法编译的 pattern 会被拒绝,并指出参数、pattern 及原因。嵌套契约中的长度界限不受该下限约束;参见entities/aggregate.md。 - 默认值填充——定义了
default:且没有 Release 提供值的槽位会获得其默认值。此时.parameters映射处于作用域内。 - 参数契约校验——合并映射中的每个值,无论由 Release 提供还是由
default:填充,都会按照 Aggregate 的spec.parameters.<slot>所声明的type/enum/min/max/pattern/ 嵌套结构约束进行校验;pattern会与读取契约时编译好的表达式进行匹配。.parameters映射作为被检查的结构化载荷,存在于校验器的内存上下文中。 - 插值——编译器在将 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 exportedspec: 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 declarationsspec: 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 parameterspec: 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 parameterspec: 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 提供的值或默认值):
# Aggregatespec: 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 作者得到其预期的行为:当运维未提供该槽位时,配置使用文档中说明的默认值。
# Aggregatespec: parameters: database: type: object properties: host: { type: string, default: "localhost" } port: { type: integer, default: 5432 }
# Release (parent omitted)spec: parameters: {}
# Resolved at template-interpolation timeparameters: database: host: "localhost" port: 5432情形 2——Release 将父项编写为显式的空映射。 显式的空值被视为有意的选择退出而予以遵从。子项的默认值不会被填充;槽位保持为空。当运维希望抑制契约的嵌套默认值、又不提供覆盖值时,使用这种形式——例如,下游使用方期望该槽位存在但为空时。
# Release (parent explicit empty)spec: parameters: database: {}
# Resolved at template-interpolation timeparameters: 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 timeparameters: 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 }}的 RecipevaluesMapping:模板是值模板表面;其模板上下文不包含.parameters。需要在valuesMapping:中按环境变化的作者,应通过已解析的.values.<key>消费路径来表达:Aggregate 暴露一个参数,在某个 Component 的values:中引用它,由 Release 提供该参数,插值后的值再传递到 Recipe。 - FeatureRecipe
injectMapping:、provides:或pipeline.with:模板是值模板表面,与 RecipevaluesMapping:相同。.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。