3. 标准模板定义：YAML/JSON模板规范、模板变量与占位符、模板版本管理

标准模板是CI/CD服务目录跨环境同步的“契约”与“蓝图”。一个定义良好的模板必须同时解决三个核心问题：用什么格式描述（规范）、如何注入差异化参数（变量与占位符）、如何追踪变更历史（版本管理）。本章将逐一拆解这三层设计。

3.1 YAML/JSON模板规范

模板格式的选择直接影响可读性、可维护性与工具链兼容性。在CI/CD服务目录场景中，YAML 因其天然的缩进结构和注释支持，成为首选；JSON 则常用于程序化生成或需要严格Schema校验的场景。下表对比了两种格式在模板定义中的关键差异：

一个标准的CI/CD服务目录模板应遵循以下规范：

• 顶层结构固定：包含 apiVersion、kind、metadata、spec 四个根字段，与Kubernetes资源模型对齐。
• 字段命名采用驼峰式：如 pipelineName、triggerBranch，保持与主流CI/CD平台一致。
• 注释即文档：YAML模板中每个关键字段上方必须包含 # 注释，说明用途与可选值。
• 禁止硬编码：所有环境相关的值（仓库地址、命名空间、超时时间）必须使用变量占位符。

3.2 模板变量与占位符

变量与占位符是模板实现“一次定义，多环境复用”的核心机制。在服务目录同步场景中，变量通常分为三个层级：

1. 全局变量：所有环境共享，如团队名称、制品仓库地址。
2. 环境变量：按环境区分，如 dev、staging、prod 的Kubernetes命名空间、数据库连接串。
3. 实例变量：单个服务实例特有，如微服务名称、端口号、副本数。

占位符语法推荐采用 {{ .VARIABLE_NAME }} 格式（Go模板风格），与主流工具（Helm、Kustomize、ArgoCD）兼容。以下是一个标准模板片段：

apiVersion: v1
kind: ServiceCatalogTemplate
metadata:
  name: {{ .ServiceName }}
  namespace: {{ .Environment.Namespace }}
spec:
  pipeline:
    triggerBranch: {{ .Git.Branch }}
    timeoutSeconds: {{ .Pipeline.Timeout | default 3600 }}
  deployment:
    replicas: {{ .Deployment.Replicas }}
    image: "{{ .Registry.Address }}/{{ .ServiceName }}:{{ .Image.Tag }}"
    env:
      - name: DB_CONNECTION
        value: "{{ .Environment.DbConnectionString }}"

变量值的来源与注入方式决定了模板的灵活性。下表列出了三种主流策略：

3.3 模板版本管理

模板版本管理是服务目录同步的“审计追踪”与“回滚基石”。没有版本管理的模板，在跨环境同步时会导致“配置漂移”和“变更不可追溯”。推荐采用语义化版本（SemVer）结合Git标签的双重策略：

• 主版本号（Major）：模板结构发生不兼容变更时递增，如删除必填字段、改变变量注入方式。
• 次版本号（Minor）：新增可选字段或变量时递增，保持向后兼容。
• 补丁版本号（Patch）：修复模板中的错误、优化注释或默认值时递增。

在Git仓库中，模板版本通过以下方式管理：

# 模板目录结构示例
templates/
├── v1.0.0/
│   ├── service-template.yaml
│   └── values/
│       ├── dev.yaml
│       ├── staging.yaml
│       └── prod.yaml
├── v1.1.0/
│   ├── service-template.yaml
│   └── values/
│       └── ...
├── v2.0.0/
│   ├── service-template.yaml
│   └── values/
│       └── ...
└── latest -> v2.0.0/   # 符号链接指向当前稳定版本

版本管理的关键实践包括：

3.4 模板规范检查清单

在将模板纳入服务目录之前，建议使用以下检查清单进行质量门禁：

• 格式校验：YAML/JSON语法正确，无缩进错误或多余逗号。
• 变量完整性：所有占位符在对应的值文件或环境变量中都有定义。
• 默认值覆盖：非必填变量提供合理的默认值。
• 版本声明：模板元数据中包含 templateVersion 字段。
• Schema匹配：模板结构通过JSON Schema或自定义规则校验。
• 注释完整：每个字段上方有中文注释说明用途。
• 安全扫描：模板中无明文密钥、或敏感路径。