4. 模板语法与引擎：Jinja2/YAML 模板语法、变量、循环与条件渲染、模板继承与宏

在标准模板驱动的发布工程自助门户中，模板引擎是连接“抽象配置”与“具体环境”的核心桥梁。本章聚焦 Jinja2（Python 生态最成熟的模板引擎）与 YAML（作为数据描述语言）的协同工作方式，系统讲解变量注入、循环与条件控制、模板继承与宏复用等关键能力。

4.1 Jinja2 与 YAML 的协作模型

Jinja2 负责逻辑渲染（循环、条件、继承），YAML 负责数据描述（结构化的变量与配置）。两者通过“模板文件 + 变量文件”分离的模式协作：

组件	职责	典型文件后缀	示例
Jinja2 模板	定义渲染逻辑、占位符、控制结构	.j2、.jinja、.yaml.j2	deployment.yaml.j2
YAML 变量文件	提供结构化数据（字符串、列表、字典）	.yaml、.yml	values-prod.yaml
渲染产物	最终生成的、可被下游工具消费的配置	.yaml、.json、.conf	deployment-prod.yaml

4.2 变量语法与作用域

Jinja2 使用 {{ variable }} 输出变量值，使用 {% ... %} 执行语句。变量可以来自 YAML 文件的顶层键或嵌套结构。

4.2.1 基础变量插值

# YAML 变量文件 (values.yaml)
app_name: "order-service"
replicas: 3
image:
  repository: "registry.example.com/order"
  tag: "v1.2.0"

# Jinja2 模板片段 (deployment.yaml.j2)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ app_name }}
spec:
  replicas: {{ replicas }}
  template:
    spec:
      containers:
        - name: {{ app_name }}
          image: "{{ image.repository }}:{{ image.tag }}"

4.2.2 变量作用域规则

作用域层级	说明	示例
全局	在模板顶层定义的变量，所有继承块可见	{{ global_var }}
块局部	在 {% block %} 内通过 {% set %} 定义	{% set local_var = "temp" %}
循环局部	{% for %} 循环内部自动创建的 loop 对象	{{ loop.index }}、{{ loop.first }}
宏局部	宏参数和宏内部 {% set %} 定义的变量	{% macro input(name, value='') %}

4.3 循环渲染：列表与字典遍历

循环是生成重复配置结构（如多个容器、多个端口、多个环境变量）的核心手段。

4.3.1 遍历列表

# YAML
ports:
  - 8080
  - 8443
  - 9090

# Jinja2 模板
ports:
{% for port in ports %}
  - containerPort: {{ port }}
{% endfor %}

4.3.2 遍历字典

# YAML
env:
  DB_HOST: "mysql-primary"
  DB_PORT: "3306"
  CACHE_URL: "redis://cache:6379"

# Jinja2 模板
env:
{% for key, value in env.items() %}
  - name: {{ key }}
    value: "{{ value }}"
{% endfor %}

4.3.3 循环内置变量

变量	说明	示例输出（第2次迭代）
loop.index	当前迭代次数（从1开始）	2
loop.index0	当前迭代次数（从0开始）	1
loop.first	是否为第一次迭代	False
loop.last	是否为最后一次迭代	False
loop.length	序列总长度	3

4.4 条件渲染：if/elif/else 与测试

条件渲染用于根据环境特征、开关变量或数据状态，决定是否输出某段配置。

4.4.1 基础条件结构

{% if env_type == "production" %}
replicas: 5
{% elif env_type == "staging" %}
replicas: 3
{% else %}
replicas: 1
{% endif %}

4.4.2 常用测试（Tests）

测试语法	说明	示例
{% if var is defined %}	变量是否已定义	避免引用未定义变量导致渲染错误
{% if var is none %}	变量是否为 None	判断可选配置是否被显式置空
{% if list|length > 0 %}	列表是否非空	决定是否渲染 ports 段
{% if var is string %}	变量类型是否为字符串	类型安全检查
{% if 'error' in log_level %}	字符串包含关系	匹配日志级别前缀

4.5 模板继承与块（Block）

模板继承允许定义基础骨架模板，子模板只覆盖差异部分，大幅减少重复代码。

4.5.1 基础模板定义

# base_deployment.yaml.j2
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ app_name }}
  labels:
    app: {{ app_name }}
    environment: {{ env_type }}
spec:
  replicas: {{ replicas }}
  selector:
    matchLabels:
      app: {{ app_name }}
  template:
    metadata:
      labels:
        app: {{ app_name }}
    spec:
      containers:
        - name: {{ app_name }}
          image: "{{ image.repository }}:{{ image.tag }}"
          ports:
{% block container_ports %}{% endblock %}
          env:
{% block container_env %}{% endblock %}
          resources:
{% block container_resources %}
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
{% endblock %}

4.5.2 子模板覆盖块

# prod_deployment.yaml.j2
{% extends "base_deployment.yaml.j2" %}

{% block container_ports %}
            - containerPort: 8080
            - containerPort: 8443
{% endblock %}

{% block container_env %}
            - name: DB_HOST
              value: "{{ db_host }}"
            - name: DB_PORT
              value: "{{ db_port }}"
{% endblock %}

{% block container_resources %}
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              cpu: "2"
              memory: "4Gi"
{% endblock %}

4.6 宏（Macro）：可复用渲染函数

宏类似于编程语言中的函数，用于封装重复的渲染逻辑，支持参数传递和默认值。

4.6.1 定义与调用宏

# macros/helpers.j2
{% macro env_var(name, value, secret=false) %}
{% if secret %}
- name: {{ name }}
  valueFrom:
    secretKeyRef:
      name: {{ name | lower }}-secret
      key: {{ value }}
{% else %}
- name: {{ name }}
  value: "{{ value }}"
{% endif %}
{% endmacro %}

# 在模板中导入并调用
{% import "macros/helpers.j2" as helpers %}

env:
{{ helpers.env_var("DB_HOST", db_host) }}
{{ helpers.env_var("DB_PASSWORD", "db-password", secret=true) }}

4.6.2 宏与继承的对比

特性	模板继承（Block）	宏（Macro）
适用场景	整体页面/文件骨架差异	局部重复片段、参数化渲染
复用粒度	块级别（大段替换）	行/段级别（细粒度）
参数传递	通过上下文变量隐式传递	显式参数列表，支持默认值
典型用法	不同环境的基础配置差异	环境变量、端口、卷挂载等重复结构

4.7 模板语法与引擎工作流

下图展示了从“变量文件 + 模板文件”到“最终渲染产物”的完整流程，以及 Jinja2 引擎在其中的核心位置。

4.8 过滤器（Filter）链式处理

过滤器用于对变量值进行后处理，支持管道式链式调用。

过滤器	说明	示例	输出
default('val')	变量未定义时使用默认值	{{ timeout | default('30') }}	30
lower	转换为小写	{{ "OrderService" | lower }}	orderservice
upper	转换为大写	{{ "prod" | upper }}	PROD
tojson	将对象转为 JSON 字符串	{{ labels | tojson }}	{"env":"prod","team":"platform"}
regex_replace	正则替换（需安装 jinja2-ansible-filters）	{{ name | regex_replace('_', '-') }}	order-service

# 链式过滤器示例
{{ "Order_Service_Prod" | lower | regex_replace('_', '-') }}
# 输出: order-service-prod

4.9 模板组织与文件布局

在自助门户项目中，推荐按以下结构组织模板文件，以支持跨环境同步：

templates/
├── base/                          # 基础骨架模板
│   ├── base_deployment.yaml.j2
│   ├── base_service.yaml.j2
│   └── base_configmap.yaml.j2
├── macros/                        # 可复用宏库
│   ├── env_vars.j2
│   ├── volumes.j2
│   └── probes.j2
├── environments/                  # 环境变量文件
│   ├── values-dev.yaml
│   ├── values-staging.yaml
│   └── values-prod.yaml
└── outputs/                       # 渲染产物输出目录（自动生成）
    ├── dev/
    ├── staging/
    └── prod/

4.10 常见错误与调试

错误现象	根因	解决方案
UndefinedError: 'xxx' is undefined	模板引用了变量文件中未定义的变量	使用 default() 过滤器，或在变量文件中补充定义
YAML 缩进错乱	Jinja2 模板中的空格/换行未正确处理	使用 {%- 和 -%} 控制空白符；在模板顶部加 #jinja2: lstrip_blocks: True, trim_blocks: True
布尔值判断失效	YAML 中 true 与 Jinja2 中 True 大小写不一致	统一使用 {% if enabled %} 隐式布尔判断
宏导入路径错误	Jinja2 加载器未正确配置搜索路径	设置 FileSystemLoader 的搜索目录包含 macros/ 文件夹