📚 课程目录第4章巡检模板设计原则

4. 巡检模板设计原则：通用性、可扩展性与字段规范

巡检模板是服务目录平台容量水位巡检的“骨架”。一个设计良好的模板，能够覆盖多类服务（数据库、中间件、容器、存储），并在业务扩张时平滑接入新服务类型，避免频繁重建模板。本章围绕模板设计的三大核心原则展开：通用性、可扩展性、字段定义规范。

  核心观点： 巡检模板不是针对单一服务的“硬编码”清单，而是一套可复用的元数据模型。字段名称、类型、单位、阈值四要素必须统一，才能支撑自动化巡检引擎的批量调度与告警收敛。

4.1 通用性：抽象共性，屏蔽差异

通用性要求模板能够描述不同服务类型的容量指标，而不需要为每个服务单独设计一套字段。实现通用性的关键在于指标抽象层：将物理/逻辑资源拆解为“资源域 + 指标名 + 阈值”的三元组。

资源域（Resource Domain）：CPU、内存、磁盘、网络、连接数、文件句柄等。
指标名（Metric Name）：使用率、剩余量、总量、等待时间、队列深度。
阈值（Threshold）：统一使用百分比或值，但模板中只定义“阈值类型”和“默认值”，具体值由服务实例覆盖。

服务类型	资源域	通用指标	单位	默认阈值
MySQL	磁盘	used_percent	%	80
Redis	内存	used_percent	%	80
Kafka	磁盘	used_percent	%	75
Nginx	连接数	used_percent	%	85

上表展示了“used_percent”这个通用指标如何覆盖不同服务。模板中只定义一次字段结构，各服务通过“服务类型”标签关联即可。

4.2 可扩展性：预留扩展点，避免硬编码

可扩展性确保当新服务（如 Elasticsearch、RabbitMQ）接入时，无需修改模板引擎代码，只需在模板配置中增加新的“指标行”。设计时需预留以下扩展点：

自定义标签（Tags）：允许为每个指标附加键值对，例如 tier=hot、az=cn-east-1a，用于后续的聚合与过滤。
阈值覆盖（Threshold Override）：模板提供默认阈值，但允许服务实例级覆盖，避免“一刀切”。
采集周期（Interval）：每个指标可独立配置采集周期（如 60s、300s），适应不同指标的波动敏感度。
计算表达式（Expression）：支持简单的四则运算，例如 (total - free) / total * 100，避免在采集端硬编码。

设计建议： 使用 JSON Schema 或 Protobuf 定义模板结构，版本号（version）字段必须保留。每次模板变更时递增版本，巡检引擎根据版本号决定是否需要重新解析。

4.3 字段定义规范：名称、类型、单位、阈值

字段定义是模板的“语法”。不规范的定义会导致解析失败、单位混淆、阈值误判。以下为四要素的详细规范：

4.3.1 字段名称（Name）

使用小写字母 + 下划线（snake_case），例如 cpu_used_percent、disk_read_bytes。
禁止使用空格、连字符、大写字母开头。
名称应自解释，避免缩写歧义（如 mem_util 应写为 memory_used_percent）。

4.3.2 字段类型（Type）

类型	说明	示例
float	浮点数，用于百分比、速率	85.5
int64	整数，用于计数、总量	1048576
string	枚举或状态值	ok / warning / critical
bool	布尔状态	true / false

4.3.3 单位（Unit）

单位必须使用标准缩写，且统一为小写。巡检引擎根据单位自动进行数值换算（如 KB → MB）。

百分比：%
字节：bytes、kbytes、mbytes、gbytes
时间：ms、s、min、h
计数：count、ops、qps
温度/其他：celsius、rpm

4.3.4 阈值（Threshold）

阈值定义采用“三级告警”模型，模板中只定义默认值，实例可覆盖。

级别	标签	默认触发条件	颜色标识
Info	info	使用率 > 60%	蓝
Warning	warning	使用率 > 80%	橙
Critical	critical	使用率 > 95%	红

避坑提醒： 阈值字段必须明确是“大于”还是“大于等于”，避免边界值重复告警或漏告。建议统一使用“大于”（>），并在文档中注明。

4.4 模板结构总览（SVG）

下图展示了一个符合通用性、可扩展性、字段规范的巡检模板结构。模板由“元数据头”和“指标行列表”组成，每个指标行包含四要素及扩展标签。

4.5 模板定义示例（JSON）

以下是一个符合上述规范的巡检模板 JSON 片段，展示了字段名称、类型、单位、阈值的完整定义：

{
  "template_id": "capacity_check_v3",
  "version": 3,
  "service_type": "mysql",
  "interval_seconds": 60,
  "tags": {
    "env": "prod",
    "tier": "hot"
  },
  "metrics": [
    {
      "name": "cpu_used_percent",
      "type": "float",
      "unit": "%",
      "default_threshold": {
        "warning": 80,
        "critical": 95
      },
      "tags": {
        "resource_domain": "cpu"
      }
    },
    {
      "name": "disk_used_percent",
      "type": "float",
      "unit": "%",
      "default_threshold": {
        "warning": 75,
        "critical": 90
      },
      "tags": {
        "resource_domain": "disk",
        "mount_point": "/data"
      }
    }
  ]
}

  实践要点：
  模板上线前需通过“字段规范校验器”，检查名称是否 snake_case、类型是否在允许列表内、单位是否标准化。
每个模板必须附带 version 字段，巡检引擎根据版本号决定是否重新加载模板缓存。
阈值覆盖遵循“实例 > 服务类型 > 全局默认”的优先级，避免误覆盖。

4.6 通用性与可扩展性的平衡（SVG）

下图展示了通用性与可扩展性在模板设计中的协作关系：通用性提供统一的字段骨架，可扩展性通过标签、表达式、覆盖机制允许差异化。

4.7 本章小结

通用性：通过资源域 + 指标名 + 阈值三元组抽象，覆盖多类服务。
可扩展性：预留 tags、override、expression、interval 扩展点，避免硬编码。
字段规范：名称 snake_case、类型标准化、单位统一缩写、阈值三级告警。
模板结构：元数据头 + 指标行列表，JSON 或 Protobuf 定义，版本管理。