Sprig 函数与辅助函数
Aggrega 模板引擎会把 Sprig v3 函数库以及 Aggrega 自有的辅助函数(optional 和 capitalizedWords)接入渲染器求值的每一个 Go 模板,并用一个在遇到映射中不存在的键时即中止的版本替换 Go 的 index。编写 Recipe valuesMapping:、FeatureRecipe injectMapping: 或渲染器求值的任何其他模板位置的作者,都可以使用完整的 Sprig 辅助函数集,以及 Go text/template 内置函数和 template-context-contract.md 中记录的运行时上下文字段。
🔴 请把“渲染器求值的”理解为它所表示的范围,因为有一个编写界面位于该范围之外。 结构化的 source: 坐标会被解析,以便固定它所指向的制品,而这种解析并不是一次渲染过程:它只注册 Aggrega 自身的辅助函数,不注册其他任何函数,因此在 source: 字段中,或在该字段读取的 locals: 条目中调用 Sprig 函数,会使拉取中止。没有任何 source: 字段读取的条目只由渲染求值,可使用完整的函数集。解析坐标确定的是要固定的内容,而不是生成制品,这正是其函数集被有意收窄的原因——关于该中止以及应改用的可移植写法,请参阅 errors/fatal-halts.md 中的“Resolving a source: coordinate registers a narrower function set(解析 source 坐标时注册的函数集更窄)”。
Sprig 函数集在参数插值时单独注册,在渲染器的值模板位置则与 Aggrega 自有的辅助函数一起注册。
已接入的内容
Sprig v3 公开完整的 Sprig 辅助函数集——按下列类别共约 200 个函数。本页概述各个类别及其中的常用辅助函数;逐个函数的权威参考是上游 Sprig 文档。
- 字符串 —
upper、lower、title、trim、trimAll、trimPrefix、trimSuffix、replace、contains、hasPrefix、hasSuffix、substr、quote、squote、cat、indent、nindent、repeat、大小写辅助函数(snakecase、camelcase、kebabcase)、缩写辅助函数(abbrev、abbrevboth、trunc)、校验和辅助函数(sha1sum、sha256sum、sha512sum、adler32sum)、toString。 - 列表 —
list、tuple、first、last、rest、initial、append/push、prepend、concat、reverse、uniq、without、has、slice、chunk、join、splitList、split、splitn、sortAlpha、compact。 - 字典 —
dict、get、set、unset、hasKey、keys、values、pick、omit、pluck、merge、mergeOverwrite、dig、deepCopy。 - 数学 —
add、sub、mul、div、mod、add1、min、max、ceil、floor、round,以及带f后缀的小数变体(addf、subf、mulf、divf、minf、maxf)。 - 转换 —
int、int64、float64、atoi、toString、toDecimal、seq、until、untilStep。 - 编码 —
b64enc、b64dec、b32enc、b32dec、toJson、toPrettyJson、toRawJson、fromJson,以及带must前缀的 JSON 变体,它们会报告解码错误,而不是静默地置为零值。 - 类型检查 —
typeOf、typeIs、typeIsLike、kindOf、kindIs、deepEqual、empty。 - 默认值与流程 —
default、coalesce、all、any、ternary、fail(以自定义消息引发模板错误——这是以守卫消息中止渲染的标准方式)。 - 正则表达式 —
regexMatch、regexFind、regexFindAll、regexReplaceAll、regexReplaceAllLiteral、regexSplit、regexQuoteMeta,以及带must前缀的严格变体。 - 路径 —
base、dir、clean、ext、isAbs(Unix 风格);osBase、osClean、osDir、osExt、osIsAbs(感知操作系统)。 - SemVer —
semver、semverCompare。 - URL —
urlParse、urlJoin。 - 日期 —
ago、date、dateInZone、dateModify、duration、durationRound、htmlDate、htmlDateInZone、now、toDate、unixEpoch。
确定性注意事项
Aggrega 保证相同字节的输入产生相同字节的输出。部分 Sprig 辅助函数会读取环境状态,在模板中调用时会破坏这一保证。作者应避免在参与生成渲染产物的模板位置使用以下辅助函数:
- 挂钟时间读取函数 —
now、date、dateInZone、dateModify、htmlDate、htmlDateInZone,以及在未提供固定参考时间时调用的ago。 - 随机生成函数 —
randAlpha、randAlphaNum、randAscii、randNumeric、randBytes、randInt、uuidv4。 - 环境读取函数 —
env、expandenv(读取进程环境变量,而环境变量在不同的操作员工作站和 CI 运行器之间各不相同)。 - 网络解析函数 —
getHostByName。
引擎不会阻止这些辅助函数;它们属于 Sprig v3 函数集。在渲染路径模板中避免使用它们这一做法,由审阅者以及作者和标准库目录所依赖的确定性输出保证来维持。
值模板中的数字
作者编写的数字以数字形式到达值模板。整数是整型并按整数打印:1000000 打印为 1000000。其他任何数字以最短的精确十进制形式打印,从不使用指数形式:作者编写的 0.0000001 打印为 0.0000001,作者编写的 1e21 打印为 1000000000000000000000,无论模板是直接写出该值,还是用 toString、quote、printf "%v" 或 toJson 将其转为文本。数学函数返回的数字——mulf、float64、round 及同类函数——是该函数自己的值,并以该函数自己的形式打印,对于非常小或非常大的值即为指数形式:对于作者编写的 0.0000001,{{ mulf .values.ratio 1 }} 打印为 1e-07。
比较函数——eq、ne、lt、le、gt 和 ge——按值读取两个数字,无论各自由哪种类型承载,因此作者编写的整数可以与模板中写的小数比较,且 3 等于 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → true数字永远不会与文本比较:六个比较函数中的任何一个在收到一个数字和带引号的文本时都会中止构建,并指出两者的类型。请将该数字与不带引号书写的数字比较,或先将其转为文本:
{{ eq .values.port "8080" }} # halts: cannot compare a number with text{{ eq .values.port 8080 }} # .values.port = 8080 → true{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → true该中止为 A value template failed while it ran(值模板在运行时失败)。断言以相同方式读取作者编写的数字;参见此表面上的数字。
存在与空值——两个不同的问题
模板会就一个值提出两个问题之一,每个问题都有各自的辅助函数。
- 作者是否写了它?
hasKey和optional按是否存在作答。作者写出的键无论持有什么都存在——包括0、""和false——只有作者省略的键才不存在。 - 它是否为空?
default、with、if和empty按是否为空作答。0、""、false、空列表、空映射和缺失的值在那里都算作空,与 Helm 中相同。
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| 缺失 | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
可能合法地为 0、"" 或 false 的值——副本数为零、超时为零、关闭的标志——应使用 hasKey 或 optional 测试,这样作者的 0 会以 0 到达输出。default、with 和 if 适用于空形式本身不具含义的值,此时“空”与“未写”可以同等对待。每个模板对同一个键只用一种方式读取:模板同时以点路径读取的键会被视为存在,如 optional 的限制所述。
Aggrega 专用辅助函数
optional — 感知键是否存在的回退
optional <map> <key> <fallback> 在 <map> 中存在 <key> 时返回该键的值,否则返回 <fallback>。与 Sprig 的 default 不同,optional 区分“键不存在”与“键存在但值为零、空或 false”。
该签名将 map 和键作为单独的参数,因为经 Go 模板 | 运算符传递的值已无法访问其父 map。父 map 不在作用域内时,就无法检查键是否存在。
存在性检查有一个限制,它来自模板而非该辅助函数:值模板将不存在的键读作空,其做法是为模板以点分路径命名并作为值读取的每个不存在的键提供一个空值。因此,如果一个模板对同一个键既通过 optional 读取、又以这种路径读取,就会发现该键存在且为空,得到的是空值而非回退值。在每个模板中只用一种方式读取一个键,两种结果就会一致。
# Present and non-zero: returns 3{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator){{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0最后一种情况正是 Sprig 的 default 无法区分的。无论 replicas 被写为 0 还是被省略,{{ .infra.replicas | default 1 }} 都返回 1——这种混同使合理的缩容到零、不重试、无超时和 false 标志等模式无法实现。
键的引用约定:优先使用反引号。 Go 模板对键参数既接受双引号("replicas")也接受反引号(`replicas`)字符串字面量;两者在模板求值时产生相同的字符串。目录和文档示例统一使用反引号形式,因为它在任何引用上下文中都对 YAML 安全。双引号 YAML 标量中的双引号键会在模板中途终止 YAML 字符串:
# BROKEN — the inner " closes the outer YAML string:service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:service_port: "{{ optional .infra `port` 8080 }}"当模板位于 YAML 块标量(| 形式)中或作为裸值标量时,两种形式都能正确渲染。当模板嵌入在双引号 YAML 标量中(即 field: "{{ ... }}" 这种以字段值为模板的模式)时,必须使用反引号。统一的约定(始终使用反引号)可以完全避免 YAML 引用陷阱。
何时优先使用 optional 而非 default。 当字段可以合理地为零、空或 false,且目录作者需要区分“作者未设置此项”与“作者将其设为假值”时,使用 optional。当这种混同可以接受时(例如空值无效的字符串字段、零值无效的数值字段),使用 default。
各表面的可用性。 optional 在渲染器求值的每个表面上都已注册:值模板表面(Recipe valuesMapping、FeatureRecipe injectMapping、provides、pipeline.with、Workload 主体)、断言求值器以及路径模板(Release 边界上的 directory: / subDirectory:)。路径模板表面的不同之处不在于辅助函数集合,而在于缺失键策略:路径模板将不存在的键视为错误而非空值,因为静默为空的路径段会产生损坏的文件系统布局,且只有在构建后才会被发现。optional 读取键时不会先触发这一严格策略,因此它可以在那里使用。
capitalizedWords — 将名称折叠为字母和数字
capitalizedWords <string> 将其参数读作由 ASCII 字母和数字以外的任意字符序列分隔的单词,将每个单词的首字母大写,然后拼接起来。结果中的每个字符都是字母或数字。
之所以提供它,是因为某些目标在用于寻址资源的名称中只接受字母和数字,而 component id 可以合理地包含点、连字符或下划线。在每个需要的 Recipe 中手写这种转换,会让同一个概念出现多种写法;一个统一的辅助函数让每位作者得到相同的结果。
# separators become word boundaries{{ capitalizedWords `payments-db` }} # → PaymentsDb{{ capitalizedWords `payments_db` }} # → PaymentsDb{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter{{ capitalizedWords `café-app` }} # → CafApp🔴 结果无法反推其来源名称。 所有分隔符都会被丢弃,因此仅分隔符位置不同的两个 id 会得到相同的结果——payments-db 和 payments_db 都得到 PaymentsDb。该辅助函数无法检测到这一点,因为它一次只处理一个名称;捕获冲突是按结果寻址资源的一方的职责。这样做的目标会拒绝冲突,而不是生成缺少其中一个的部署:为 CloudFormation 构建时,id 折叠为同一名称的两个 component 会使构建中止,消息会列出得到该名称的每个 id。选择除标点之外还有其他差异的 id,这个问题就不会出现。
各表面的可用性。 capitalizedWords 在 optional 注册的所有位置都已注册:渲染器求值的每个表面,以及结构化 source: 坐标的解析。它在 Aggregate 参数插值中不可用,那里只提供 Sprig 集合。
index — map 必须包含的键
index <collection> <key>... 按位置或按键读取集合,与 Go 自带的 index 相同——只有一处差异。当集合是 map 且 map 不包含该键时,index 会中止构建并指出该键,而 Go 的版本会返回一个打印为字面文本 <no value> 的空值。
# Present: returns the value{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")在键必须存在的地方——例如按 Recipe 计算出的变量名读取的凭据、另一个模板发布的键——应使用它读取,这样缺失的键会停止构建,而不是以 <no value> 的形式进入产物。在键可以合理缺失的地方,先对其进行测试:{{ optional .values `replicas` 1 }} 提供回退值,Sprig 的 get 返回空字符串,hasKey 只测试而不读取。通过 index 读取后再应用 default 无法提供回退值,因为中止发生在 default 运行之前。存在且值为 null 的键不算缺失:index 会返回它,并打印为 <no value>。
这一中止仅是 index 的特性,且在每个表面上都相同——值模板、断言求值器、路径模板、结构化 source: 坐标、Aggregate 参数插值、参数的 validate: 谓词,以及 schema 的 x-aggrega-when: / x-aggrega-validate: 谓词。以点号读取未设置的键遵循其所在表面自身的缺失键策略,不受影响。该中止记录在 errors/fatal-halts.md 的“A template indexes a map with a key the map does not hold(模板使用 map 不包含的键对 map 进行索引)”中。
不可用的常见辅助函数
Helm 在 Go 的 text/template 基础上扩展了一些 chart 模板辅助函数,这些函数常被误认为是通用的 Sprig 辅助函数。Aggrega 的渲染器没有注册其中任何一个。 由 Aggrega 渲染器求值的模板(Recipe valuesMapping:、FeatureRecipe injectMapping:、provides、Workload 主体、断言求值器)无法调用它们:
include:Helm 推荐的调用已定义模板片段并得到可管道传递的字符串输出的形式。Aggrega 的渲染器不注册它。请改用标准 Go 模板的{{ template "name" . }}(仅产生副作用的形式);如需可管道传递的输出,请使用 MappingLibrary 片段和$import:指令进行组合。tpl:将字符串作为嵌套模板,针对当前上下文重新求值。Aggrega 不注册它;嵌套重新求值不属于模板接口的一部分。需要计算值的作者应使用 Sprig 的字符串辅助函数组合出这些值,并直接输出最终值。required:当指定的值缺失时,以自定义消息使 chart 渲染失败。Aggrega 不注册它。Aggrega 的必填字段检查位于类型化参数契约层(带有required: true的 Aggregateparameters:槽位若未被 Release 填充,会以E0165中止构建,并指出该槽位以及 Aggregate 声明它的位置);针对单个模板的必填标记检查使用 Sprig 的fail,抛出携带所给字符串的致命模板错误。warn:向操作者的终端输出一条非致命提示。Aggrega 不注册它。需要以说明性消息中止渲染的模板应使用 Sprig 的fail;需要在不中止的情况下回退的模板应依靠标准 Go 的if/else分支。
跨引擎辅助函数清单(对 MappingLibrary 作者至关重要)
MappingLibrary 片段可以面向以下两种使用位置之一:
- Aggrega 端使用(Recipe
valuesMapping:、FeatureRecipeinjectMapping:等,由 Aggrega 的渲染器求值)。可用的辅助函数为:完整的 Sprig v3(default、coalesce、quote、nindent、indent、b64enc等)加上 Aggrega 自有的辅助函数(optional、capitalizedWords),且index在映射不包含所给键时会中止。chart 模板辅助函数(include、tpl、required、warn)不可用。 - Helm chart 内部使用(chart 的
values.yaml内容或 chart 的templates/*.yaml,由 Helm 自身的模板引擎在下游渲染)。可用的辅助函数为:完整的 Sprig v3 加上 Helm 的 chart 模板辅助函数(include、tpl、required、warn)。Aggrega 自有的辅助函数不可用,且那里的index是 Go 自带的版本,对缺失的键返回空值而不是中止。
两套辅助函数共享 Sprig 接口,但在引擎特有的扩展上有所不同。面向 Helm chart 内部使用的 MappingLibrary 条目遵循 Helm 约定(大写 V 根的 .Values.<key>、| default、基于 include 的组合);面向 Aggrega 端使用的条目遵循 Aggrega 约定(小写的 .values.<key>、用于感知存在性回退的 optional)。该库实体按原样存储片段;编写形式取决于片段打算在何处渲染。
Aggrega 在 Sprig 之上的自定义辅助函数为 optional 和 capitalizedWords,均已在上文说明;其 index 取代了 Go 的版本,同样已在上文说明。辅助函数接口的其余部分正是 Sprig v3 函数集。
交叉引用
template-context-contract.md— 模板在使用 Sprig 辅助函数的同时读取的运行时字段。expansion-matrix.md— 各模板位置的求值顺序。05-templates.md— 模板概述与编写约定。- Sprig v3 文档 — 权威的逐函数参考。