2、服务目录基础概念

2.1 什么是服务目录

服务目录（Service Catalog）是微服务架构中所有可运行服务的元数据注册中心。它不存储业务数据，而是记录每个服务的身份信息、网络位置、版本状态以及服务间的调用关系。在云原生环境中，服务目录是服务发现、流量治理、策略执行和故障诊断的基础数据源。

当 Policy Check 失败时，运维人员首先需要确认服务目录中的记录是否准确——错误的服务名、过期的端点、缺失的依赖关系都会直接导致策略判定异常。

2.2 服务目录的组成元素

一个完整的服务目录条目通常包含以下四大核心元素：

2.2.1 服务名与版本

服务名是目录的主键，必须遵循统一的命名规范。版本字段支持策略引擎做精细化路由：

• 精确匹配： version == "v2.1.0" —— 仅允许该版本通过
• 范围匹配： version >= "v2.0.0" —— 允许所有 v2 大版本
• 前缀匹配： version ^ "v2" —— 常用于灰度发布场景

2.2.2 端点

端点字段通常包含多个协议地址（HTTP、gRPC、TCP），以及对应的健康检查路径。策略引擎在检查流量时，会校验请求目标是否匹配目录中注册的端点集合。

2.2.3 依赖关系

依赖关系以有向边列表的形式存储，是服务拓扑图的核心数据。Policy Check 中的“依赖缺失”错误，绝大多数源于目录中依赖关系未及时更新。

# 服务目录依赖关系示例（YAML 格式）
services:
  - name: order-service
    version: v2.1.0
    endpoints:
      - http://order-svc.prod:8080
      - grpc://order-svc.prod:9090
    dependencies:
      - name: user-service
        version: ^v3
      - name: payment-service
        version: v1.5.0
      - name: inventory-service
        version: ^v2

2.3 服务目录在微服务架构中的作用

服务目录在微服务架构中承担以下五个关键职责：

1. 服务发现的数据底座： 客户端和网关通过查询服务目录获取目标服务的可用端点，实现动态路由。
2. 策略执行的判定依据： Policy Check 引擎读取目录中的服务名、版本、依赖关系，判断请求是否合规。
3. 服务拓扑的可视化基础： 运维平台基于目录中的依赖关系生成实时服务调用拓扑图。
4. 变更影响分析： 当某个服务版本升级或端点变更时，通过目录反向查询所有依赖方，评估影响范围。
5. 多环境隔离与治理： 同一套服务目录可以按环境（dev/staging/prod）或租户进行逻辑隔离，避免策略冲突。

2.4 服务目录与 Policy Check 的关联

Policy Check 引擎在执行策略判定时，会依次执行以下步骤：

1. 解析请求目标： 从请求中提取目标服务名、版本号、端点。
2. 查询服务目录： 根据服务名在目录中查找对应的元数据记录。
3. 校验版本兼容性： 对比请求版本与目录中注册的版本范围。
4. 校验端点合法性： 确认请求端点存在于目录的端点列表中。
5. 校验依赖完整性： 检查请求链路上的所有依赖服务是否都在目录中注册且状态正常。

任何一个步骤失败，都会产生 Policy Check 错误。因此，服务目录的准确性直接决定了策略判定的正确率。