4. 标准模板设计原则：单一职责、可复用性、可组合性、版本化、参数化设计

标准模板是 CI/CD 服务目录的“乐高积木”。如果模板设计不合理，服务目录将变成难以维护的“意大利面条”。本章定义五项核心设计原则，确保模板具备高内聚、低耦合、可演进的特征。

4.1 五项原则总览

4.2 单一职责（Single Responsibility）

每个模板对应 CI/CD 服务目录中的一个原子服务单元。例如：maven-build 只负责编译和单元测试；docker-push 只负责构建镜像并推送到仓库；helm-deploy 只负责执行 Helm 升级。

# 错误示例：一个模板做两件事
stages:
  - build: mvn clean package
  - deploy: kubectl apply -f deploy.yaml

# 正确示例：拆分为两个模板
# template: maven-build
stages:
  - build: mvn clean package
# template: k8s-deploy
stages:
  - deploy: kubectl apply -f deploy.yaml

4.3 可复用性（Reusability）

模板必须与具体项目、环境、秘钥解耦。所有差异化内容通过参数注入。可复用性直接决定服务目录的“模板共享率”。

• 禁止硬编码： 项目名、命名空间、镜像仓库地址、 等必须参数化。
• 环境无关： 模板不区分 dev/staging/prod，环境差异由参数覆盖。
• 秘钥外部化： 敏感信息通过 CI/CD 平台的 Secret 管理或 Vault 引用。

4.4 可组合性（Composability）

模板之间通过标准化的输入/输出契约串联成完整流水线。可组合性使服务目录从“模板列表”进化为“流水线工厂”。

4.5 版本化（Versioning）

模板必须遵循语义化版本 2.0.0（MAJOR.MINOR.PATCH）。版本化是服务目录治理的基石，直接影响变更审计和回滚能力。

4.6 参数化设计（Parameterization）

模板的所有可变项必须通过参数暴露，并附带类型、默认值、描述、校验规则。参数化设计是模板从“黑盒”变为“白盒”的关键。

# 参数化模板示例（YAML 格式）
parameters:
  - name: app_name
    type: string
    description: "应用名称，用于命名空间和标签"
    default: "my-app"
    validation:
      pattern: "^[a-z0-9-]{3,30}$"
      message: "应用名称必须为小写字母、数字、连字符，长度 3-30"
  - name: replicas
    type: integer
    description: "Pod 副本数"
    default: 2
    validation:
      min: 1
      max: 10
  - name: enable_canary
    type: boolean
    description: "是否启用金丝雀发布"
    default: false

4.7 原则协同与验证矩阵

五项原则并非孤立存在，它们共同构成模板质量的五维验证模型。服务目录在收录模板时，必须逐项检查。