4. 模板语法入门：Go 模板基础、模板函数、管道与作用域、模板注释与空白控制

Helm 使用 Go 语言的 text/template 包作为模板引擎。理解模板语法是编写灵活、可维护 Chart 的核心能力。本章将系统讲解 Go 模板的四大基础模块：模板语法结构、内置函数与自定义函数、管道与作用域机制、注释与空白控制策略。

4.1 Go 模板基础：数据注入与动作标记

Go 模板将静态文本与动态动作（Action）混合。动作使用双花括号 {{ }} 包裹，用于输出变量、执行控制结构或调用函数。

{{- /* 从 values.yaml 读取副本数，默认值为 1 */ -}}
replicas: {{ .Values.replicaCount | default 1 }}

{{- /* 条件判断：仅当 service.enabled 为 true 时创建 Service */ -}}
{{- if .Values.service.enabled }}
apiVersion: v1
kind: Service
metadata:
  name: {{ .Release.Name }}-svc
spec:
  ports:
    - port: {{ .Values.service.port }}
{{- end }}

4.2 模板函数：内置函数与自定义函数

Helm 模板内置了超过 60 个函数，涵盖字符串操作、类型转换、数学运算、集合处理、编码解码等场景。此外，Chart 开发者可以通过 _helpers.tpl 定义命名模板（自定义函数），实现逻辑复用。

4.2.1 常用内置函数分类

4.2.2 自定义函数：命名模板

在 templates/_helpers.tpl 中定义命名模板，使用 define 关键字声明，通过 include 或 template 调用。

{{- /* _helpers.tpl */ -}}
{{- define "myapp.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- /* deployment.yaml 中调用 */ -}}
name: {{ include "myapp.fullname" . }}

4.3 管道与作用域：数据流与上下文切换

管道（Pipeline）是 Go 模板中数据传递的核心机制，作用域（Scope）决定了 . 指向的对象。理解两者的配合是编写复杂模板的关键。

4.3.1 管道机制

管道使用 | 符号将前一个命令的输出作为后一个命令的输入，形成数据流链。管道可以串联多个函数，实现复杂的转换逻辑。

{{- /* 管道链：先转大写，再截断，最后加引号 */ -}}
{{ .Values.serviceName | upper | trunc 10 | quote }}

{{- /* 管道与 default 配合：优雅处理缺失值 */ -}}
{{ .Values.image.tag | default "latest" | printf "myapp:%s" }}

4.3.2 作用域切换：with 与 range

with 和 range 会改变当前作用域，使 . 指向新的上下文。作用域切换后，外部变量需要通过 $ 根对象访问。

{{- /* with 作用域示例 */ -}}
{{- with .Values.database }}
database:
  host: {{ .host | quote }}
  port: {{ .port | default 5432 }}
  {{- /* 访问根对象：使用 $ */ -}}
  release: {{ $.Release.Name }}
{{- end }}

{{- /* range 作用域示例 */ -}}
{{- range $index, $item := .Values.containers }}
- name: {{ $item.name }}
  image: {{ $item.image }}
  {{- /* 使用 $index 获取当前索引 */ -}}
  index: {{ $index }}
{{- end }}

4.4 模板注释与空白控制

Helm 模板中的空白控制直接影响 YAML 渲染结果的格式。不恰当的空白会导致缩进错误或多余空行。Go 模板提供了精确的空白修剪语法。

4.4.1 模板注释

使用 {{/* */}} 包裹注释内容，注释不会出现在最终渲染的 YAML 中。注释可以跨行，用于解释复杂逻辑或临时禁用代码块。

{{- /*
  这是一个多行注释
  用于解释下方配置的目的
  该配置仅在 production 环境生效
*/ -}}
{{- if eq .Values.environment "production" }}
resources:
  limits:
    memory: "2Gi"
{{- end }}

4.4.2 空白控制语法

在动作标记的左右两侧添加 - 可以修剪空白：{{- 修剪左侧空白（包括换行和缩进），-}} 修剪右侧空白。

{{- /* 错误示例：多余空行 */ -}}
apiVersion: v1
kind: Service
metadata:
  name: my-svc
{{ if .Values.enabled }}
spec:
  ports:
    - port: 80
{{ end }}

{{- /* 正确示例：使用空白控制消除空行 */ -}}
apiVersion: v1
kind: Service
metadata:
  name: my-svc
{{- if .Values.enabled }}
spec:
  ports:
    - port: 80
{{- end }}

4.5 综合实战：构建一个带条件与循环的 ConfigMap 模板

以下示例综合运用了变量输出、管道、作用域、空白控制和自定义函数，展示一个生产级别的 ConfigMap 模板。

{{- /* _helpers.tpl 中定义命名模板 */ -}}
{{- define "myapp.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.Version | quote }}
{{- end -}}

{{- /* configmap.yaml */ -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
data:
  {{- /* 使用 with 简化嵌套字段访问 */ -}}
  {{- with .Values.config }}
  {{- range $key, $value := . }}
  {{ $key }}: {{ $value | default "undefined" | quote }}
  {{- end }}
  {{- end }}

  {{- /* 条件注入：仅当 enabled 为 true 时添加额外配置 */ -}}
  {{- if .Values.features.enabled }}
  feature_flag: "true"
  feature_timeout: {{ .Values.features.timeout | default 30 | int | quote }}
  {{- end }}