4. 模板元数据设计：模板名称、版本号、描述、分类标签、维护者、依赖关系、输入参数定义（JSON Schema）

模板元数据是自助目录中每个模板的“身份证”与“说明书”。平台工程团队通过标准化的元数据字段，让开发者能够快速检索、理解、使用和治理模板。本节将逐一拆解核心元数据字段的设计原则与最佳实践。

4.1 元数据字段全景

一个完整的模板元数据通常包含以下七个核心字段，它们共同构成了模板的语义层与操作层：

4.2 模板名称与版本号

模板名称 是开发者搜索和引用模板的第一入口。命名应遵循以下规范：

• 领域+技术栈+用途：如 “Python 数据管道”、“Go gRPC 服务”、“React 前端应用”。
• 避免模糊词：不使用 “通用模板”、“测试模板” 等无区分度的名称。
• 全局唯一：在自助目录中，名称+版本号构成唯一标识。

版本号 强制使用 语义化版本（SemVer） 格式：MAJOR.MINOR.PATCH。

• MAJOR：模板结构或输入参数发生不兼容变更时递增。
• MINOR：新增可选参数或功能，向后兼容时递增。
• PATCH：修复缺陷或文档更新时递增。

4.3 描述与分类标签

描述 应遵循“一句话原则”：在 80 个字符内说明模板的核心价值。例如：

• ✅ “基于 Spring Boot 3.x 的 RESTful 微服务脚手架，内置日志与监控。”
• ❌ “这是一个用于创建微服务的模板，它使用 Java 语言和 Spring 框架……”

分类标签 是平台搜索与推荐系统的核心数据源。设计标签体系时需注意：

• 层级扁平化：避免超过两层的标签树，优先使用平标签 + 命名空间。
• 标签粒度：每个模板 3~5 个标签，覆盖技术栈、架构风格、部署环境。
• 标准化：建立平台级标签字典，禁止随意创建同义标签（如 “java” vs “Java”）。

4.4 维护者与依赖关系

维护者 字段确保模板有明确的责任人。推荐使用 团队别名（如 “platform-engineering”）而非个人邮箱，避免人员流动导致失联。同时可附加 Slack 频道 或 GitHub 仓库 链接。

依赖关系 声明模板运行所需的平台级服务或外部资源。典型依赖包括：

• 基础设施：Kubernetes 集群、数据库实例、消息队列。
• 平台服务：日志收集、监控告警、CI/CD 管道。
• 外部系统：LDAP、Vault、Artifactory。

4.5 输入参数定义（JSON Schema）

输入参数定义是模板元数据中技术含量最高的部分。它使用 JSON Schema 标准描述用户需要填写的参数，包括参数名称、类型、默认值、校验规则和 UI 提示。

一个典型的 JSON Schema 示例：

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["serviceName", "replicas"],
  "properties": {
    "serviceName": {
      "type": "string",
      "title": "服务名称",
      "description": "请输入服务名称，仅支持小写字母和连字符",
      "pattern": "^[a-z]+(-[a-z]+)*$",
      "minLength": 3,
      "maxLength": 32
    },
    "replicas": {
      "type": "integer",
      "title": "副本数",
      "description": "初始部署的 Pod 副本数量",
      "default": 2,
      "minimum": 1,
      "maximum": 10
    },
    "enableMonitoring": {
      "type": "boolean",
      "title": "启用监控",
      "description": "是否自动接入 Prometheus 监控",
      "default": true
    },
    "env": {
      "type": "string",
      "title": "部署环境",
      "enum": ["dev", "staging", "prod"],
      "default": "dev"
    }
  }
}

JSON Schema 的核心设计要点：

• 必填字段：通过 required 数组声明，避免用户遗漏关键参数。
• 校验规则：使用 pattern、minimum、maxLength 等约束，将错误前置到 UI 层。
• UI 提示：title 和 description 字段用于生成表单标签和帮助文本。
• 枚举与默认值：enum 提供下拉选择，default 减少用户输入量。

4.6 元数据生命周期与治理

元数据并非一成不变。平台工程团队应建立以下治理机制：

• 版本冻结：已发布的模板元数据不可修改，只能通过新版本发布变更。
• 废弃策略：标记为 deprecated 的模板保留 90 天后自动隐藏，期间提示用户迁移。
• 审计日志：记录每次元数据变更的操作人、时间与变更内容。

下图展示了模板元数据从创建到废弃的完整生命周期：

4.7 元数据文件结构示例

在实际平台中，元数据通常以 YAML 或 JSON 文件形式存储在模板仓库中。以下是一个完整的 template.yaml 示例：

apiVersion: catalog.platform.io/v1
kind: Template
metadata:
  name: spring-boot-microservice
  version: 1.2.0
  description: "基于 Spring Boot 3.x 的 RESTful 微服务脚手架"
  tags:
    - java
    - spring-boot
    - microservice
    - kubernetes
  maintainer: "team:platform-engineering"
  dependencies:
    kubernetes: ">=1.24"
    monitoring: "prometheus-operator"
    logging: "loki-stack"
spec:
  inputSchema:
    $schema: https://json-schema.org/draft-07/schema#
    type: object
    required:
      - serviceName
      - replicas
    properties:
      serviceName:
        type: string
        title: 服务名称
        pattern: "^[a-z]+(-[a-z]+)*$"
      replicas:
        type: integer
        title: 副本数
        default: 2
        minimum: 1
        maximum: 10
      enableMonitoring:
        type: boolean
        title: 启用监控
        default: true

通过标准化的元数据设计，平台工程团队能够为开发者提供一致、可预测的模板使用体验，同时为后续的模板治理、搜索优化和自动化编排奠定坚实基础。