3. Collector驱动开发简介
在平台工程自助目录中，Collector（采集器）驱动是连接基础设施资源与自助服务目录的核心适配层。它负责将云原生环境中异构的、非标准化的资源状态，转换为平台目录可理解、可编排的标准化数据模型。理解驱动的本质、定位与设计原则，是构建可扩展自助目录的起点。
3.1 什么是Collector驱动
Collector驱动是一个可插拔的适配器组件，它封装了与特定外部系统（如云服务商API、Kubernetes集群、数据库、中间件）的交互逻辑，并输出统一的资源描述。其核心职责包括：
- 资源发现：主动或被动地探测目标系统中的资源实例。
- 状态采集：获取资源的实时配置、指标、健康状态。
- 数据转换：将原始API响应转换为平台定义的统一资源模型（URM）。
- 事件推送：将资源变更事件（创建、更新、删除）上报给自助目录引擎。
关键概念：驱动本身不存储资源数据，它只负责“翻译”和“搬运”。数据持久化与索引由自助目录的后端服务完成。
| 维度 | 传统Agent | Collector驱动 |
|---|---|---|
| 部署形态 | 常驻进程，需单独安装 | 轻量级插件，可热加载 |
| 数据模型 | 私有Schema | 遵循平台URM标准 |
| 生命周期 | 与目标系统强绑定 | 由平台目录统一管理 |
| 扩展方式 | 修改Agent代码 | 实现驱动接口即可 |
3.2 驱动在自助目录中的位置
在平台工程自助目录的架构中，Collector驱动位于资源接入层，是目录引擎与基础设施之间的桥梁。下图展示了驱动在整体架构中的位置与交互关系：
架构要点：驱动管理层是关键的“中间层”。它负责驱动的注册、发现、健康检查和数据缓存，使得上层目录引擎无需关心驱动的具体实现细节，实现了关注点分离。
3.3 驱动开发的核心原则
开发高质量的Collector驱动，需要遵循以下四项核心原则。这些原则直接决定了驱动的可维护性、可测试性和可扩展性。
- 单一职责：一个驱动只负责一种资源类型或一个目标系统。例如，K8s Collector只处理Kubernetes资源，不混合处理云资源。
- 无状态设计：驱动实例不应持有业务状态。所有状态（如游标、偏移量、配置）应外部化到驱动管理层或持久化存储中。
- 优雅降级：当目标系统不可用或返回异常时，驱动应返回明确的错误码和错误信息，而不是崩溃或阻塞。支持超时控制和重试策略。
- 可观测性：驱动必须暴露标准的健康检查端点、指标（如采集耗时、成功/失败次数）和结构化日志，便于运维监控。
| 原则 | 违反后果 | 最佳实践 |
|---|---|---|
| 单一职责 | 驱动逻辑臃肿，难以测试和复用 | 每个驱动只对应一个资源域（如：计算、网络、存储） |
| 无状态设计 | 驱动实例故障导致数据丢失或重复采集 | 使用外部存储记录采集进度（如Redis、数据库） |
| 优雅降级 | 目标系统抖动导致驱动连锁崩溃 | 实现断路器模式，设置最大重试次数和退避策略 |
| 可观测性 | 问题定位困难，无法评估驱动健康度 | 集成Prometheus指标和结构化日志（如JSON格式） |
常见陷阱：不要在驱动内部实现复杂的业务逻辑或数据聚合。驱动只负责“采集”和“转换”，任何聚合、过滤、排序操作都应放在驱动管理层或上层服务中完成。否则会导致驱动难以复用，且增加维护成本。
下图总结了驱动开发的核心原则与它们之间的关系：
实践建议：在开始编码前，先定义驱动的接口契约（Interface Contract）。明确输入（配置、认证信息）、输出（资源模型、错误码）和行为（同步/异步、轮询/事件驱动）。契约先行，能有效降低后续集成和测试的成本。