4. 服务目录的核心组件：服务蓝图、模板、配置项、依赖关系、SLA定义
服务目录并非简单的服务列表，而是一个包含丰富元数据和操作逻辑的活文档。在平台工程视角下，服务目录的每个条目都应具备五个核心组件，它们共同构成了服务的完整生命周期描述。缺少任何一个组件，都可能导致自助服务体验的断裂或运维事故。
4.1 核心组件全景
下表展示了五个核心组件在服务目录中的角色定位与关键属性：
| 组件 | 角色定位 | 关键属性 | 消费者视角 |
|---|---|---|---|
| 服务蓝图 | 服务交付的流程与交互设计 | 阶段、触点、可见性、证据 | “我如何获得这个服务？” |
| 模板 | 可重复使用的标准化产出物 | 参数化、版本、引擎类型 | “我如何快速创建？” |
| 配置项 | 服务实例的运行时参数集合 | 键值对、作用域、校验规则 | “我的服务长什么样？” |
| 依赖关系 | 服务间的拓扑与调用链路 | 类型、方向、版本约束 | “这个服务依赖谁？” |
| SLA定义 | 服务质量的承诺与度量标准 | 指标、阈值、时段、惩罚 | “我能得到什么保障？” |
4.2 服务蓝图：交付流程的可视化契约
服务蓝图是服务目录的“用户体验地图”，它从消费者发起请求到服务交付完成的整个过程中，定义了所有交互触点、后台动作和支持流程。在自助门户中，服务蓝图帮助开发者理解“我点下‘创建’按钮后，背后发生了什么”。
平台工程实践要点： 服务蓝图应区分“前台可见步骤”与“后台不可见步骤”。前台步骤展示在门户进度条中，后台步骤记录在审计日志中。例如，一个“创建微服务”的蓝图可能包含：开发者填写表单（前台）→ 触发CI流水线（后台）→ 代码仓库初始化（后台）→ 返回服务端点信息（前台）。
4.3 模板：标准化产出的核心引擎
模板是服务目录中实现“自助”的关键。它将重复性的基础设施和代码结构封装为可参数化的产出物。一个高质量的模板应包含以下要素：
- 参数化接口：暴露给消费者的可配置变量，如服务名称、环境、副本数。
- 引擎类型：模板的执行引擎，如 Terraform、Helm、Pulumi、Cookiecutter。
- 版本管理：模板自身的版本号，确保消费者使用的模板可追溯。
- 输出产物：模板执行后生成的具体资源列表，如 Deployment、Service、ConfigMap。
最佳实践： 模板应遵循“黄金路径”原则，提供一组经过验证的默认值，同时允许高级用户覆盖关键参数。避免暴露过多底层细节，降低消费者的认知负担。
4.4 配置项：服务实例的个性化参数
配置项是服务实例在运行时所需的参数集合。与服务目录中的模板参数不同，配置项通常是在服务创建后，由平台或消费者根据实际运行环境进行调整的。
配置项的管理应遵循以下原则：
- 分层管理：区分全局配置、环境配置、实例配置，优先级从低到高。
- 校验规则：对每个配置项定义类型、取值范围、正则表达式，防止错误配置。
- 变更审计：记录每次配置变更的操作人、时间、前后值，支持回滚。
- 动态注入：支持配置项在服务运行时动态刷新，无需重启实例。
4.5 依赖关系：服务拓扑的精确描述
依赖关系定义了服务目录中各个服务条目之间的连接方式。在微服务架构中，一个服务可能依赖数据库、消息队列、认证服务等多个下游组件。依赖关系的管理直接影响服务的可用性和变更风险。
依赖关系通常分为以下类型：
| 依赖类型 | 描述 | 示例 | 影响范围 |
|---|---|---|---|
| 强依赖 | 服务不可用时，当前服务完全不可用 | 数据库、认证服务 | 功能完全中断 |
| 弱依赖 | 服务不可用时，当前服务降级运行 | 推荐引擎、日志收集 | 部分功能缺失 |
| 数据依赖 | 依赖上游服务产生的数据 | 事件流、消息队列 | 数据一致性 |
| 基础设施依赖 | 依赖底层平台资源 | DNS、负载均衡、存储卷 | 网络与资源可用性 |
4.6 SLA定义：服务质量的量化承诺
SLA（Service Level Agreement）定义是服务目录中消费者最关心的组件之一。它明确了平台团队对服务可用性、性能、响应时间等方面的承诺。在自助门户中，SLA信息应清晰展示在服务详情页，并作为服务健康度的衡量标准。
一个完整的SLA定义应包含以下要素：
- 指标定义：如可用性（99.9%）、P99延迟（< 200ms）、错误率（< 0.1%）。
- 测量方式：如何采集和计算指标数据，如Prometheus查询语句、日志采样率。
- 时间窗口：SLA的统计周期，如月度、季度、滚动30天。
- 排除条件：哪些情况不计入SLA违约，如计划内维护、第三方服务故障。
- 补偿机制：SLA未达标时的处理方式，如服务积分、工单升级。
常见陷阱： 不要定义无法测量的SLA指标。例如，如果平台无法采集端到端的用户感知延迟，就不要在SLA中承诺“页面加载时间 < 1秒”。SLA定义必须与现有的监控和可观测性能力对齐。
4.7 组件间的协同关系
五个核心组件并非孤立存在，它们共同构成了服务目录的完整语义。例如：
- 服务蓝图中的“后台动作”步骤，会引用具体的模板来执行资源创建。
- 模板执行后生成的配置项，会被注入到服务实例中。
- 服务实例的依赖关系，决定了其SLA中可用性指标的计算范围（如依赖服务故障是否计入）。
- 当SLA违约时，平台应自动触发服务蓝图中的“故障恢复”流程。
在平台工程实践中，建议使用版本控制工具（如Git）来管理这五个组件的定义文件，确保每次变更都有记录、可审计、可回滚。服务目录的元数据本身，也应被视为平台工程团队的核心资产。