4. 质量门禁架构总览：门禁触发条件、校验流程、反馈闭环
质量门禁（Quality Gate）是自动化校验体系的核心执行单元，它决定了“何时校验、校验什么、如何反馈”。本章从架构视角拆解门禁的三个关键环节：触发条件定义校验时机，校验流程定义执行路径，反馈闭环定义结果处置。三者构成一个完整的控制回路，确保每一次变更都能被客观、可重复地度量。
4.1 门禁触发条件：三类典型事件源
门禁并非持续运行，而是由特定事件驱动。根据变更来源和校验粒度，触发条件分为以下三类：
| 触发类型 | 事件示例 | 校验粒度 | 典型场景 |
|---|---|---|---|
| 代码提交触发 | Git push / PR 创建 | 单次变更（Commit / PR） | 开发分支合并前校验 |
| 定时调度触发 | Cron / 固定周期 | 时间窗口聚合数据 | 每日 SLI 基线校验 |
| 人工/API 触发 | 手动执行 / Webhook 回调 | 按需指定范围 | 紧急修复后重校验 |
设计要点：触发条件应支持组合模式。例如“代码提交 + 仅当目标分支为 main 或 release”可减少无效校验；定时触发应避开业务高峰期，避免与提交触发争抢计算资源。
4.2 校验流程：五阶段执行管线
一次完整的门禁校验遵循固定的管线顺序，每个阶段产出中间结果，供下一阶段消费。流程不可跳过，但可根据配置跳过某些阶段（如不涉及数据库变更时可跳过数据一致性校验）。
- 参数注入阶段：从触发事件中提取上下文（分支、提交 ID、时间戳），合并静态配置（阈值、SLI 口径），生成校验参数包。
- 数据采集阶段：根据参数包中的 SLI 口径，从监控系统、日志平台、数据库拉取原始指标数据。
- 口径计算阶段：对原始数据执行聚合、过滤、去重、归一化，生成标准化的 SLI 值。
- 阈值比对阶段：将 SLI 值与门禁阈值（硬限、软限、趋势线）进行比对，输出 Pass / Warn / Fail 状态。
- 结果持久化阶段：将校验结果写入存储（数据库、消息队列、事件总线），供后续反馈闭环消费。
4.3 反馈闭环：从结果到行动
校验结果持久化后，反馈闭环负责将状态转化为可执行的动作。闭环设计决定了门禁的“威慑力”——如果校验失败后没有任何后果，门禁就形同虚设。典型的反馈闭环包含以下环节：
- 阻断（Block）：Fail 状态直接阻止合并操作（如 GitHub 的 required status check），或阻断流水线下一阶段执行。
- 告警（Alert）：Warn 状态发送通知到即时通讯工具（Slack、钉钉、飞书），附带 SLI 明细和对比基线。
- 记录（Log）：所有校验结果写入审计日志，支持事后追溯和趋势分析。
- 自动修复（Auto-Remediation）：对已知模式（如缓存命中率下降）触发预定义的修复脚本（如扩容、回滚配置）。
- 指标回写（Write-back）：将校验结果回写到 SLI 口径的元数据中，用于后续口径调优和阈值自适应。
闭环关键指标：反馈闭环的时效性直接影响开发体验。建议 Fail 阻断延迟 < 5 秒（从校验完成到流水线收到阻断信号），告警通知延迟 < 30 秒。超过此阈值，开发者可能已切换到其他上下文，导致反馈失效。
4.4 架构总览：触发-校验-闭环一体化
将触发条件、校验流程、反馈闭环整合为一张架构图，可以清晰看到数据流和控制流的走向。门禁引擎作为中心调度器，接收事件源输入，驱动五阶段管线，最终将结果分发到多个反馈通道。
4.5 架构设计原则
在落地质量门禁架构时，需遵循以下原则以保证可扩展性和稳定性：
| 原则 | 说明 | 反例 |
|---|---|---|
| 无状态 | 门禁引擎不持有业务状态，所有上下文从参数包和外部存储获取 | 在引擎内存中缓存 SLI 口径，导致不同触发事件使用过期口径 |
| 幂等校验 | 相同参数包多次执行应产生相同结果（时间戳敏感指标除外） | 数据采集阶段未去重，导致重复计算 SLI |
| 可观测 | 每个阶段输出日志、指标、链路追踪，支持故障定位 | 校验失败后无法定位是数据采集还是口径计算的问题 |
| 优雅降级 | 外部依赖（监控系统、数据库）不可用时，门禁应返回 Warn 而非 Fail | 监控系统超时导致门禁 Fail，阻塞正常发布 |
常见陷阱：反馈闭环中的“自动修复”应谨慎启用。建议先以“建议模式”运行（仅生成修复脚本，不自动执行），观察至少一周的修复准确率后再切换为自动模式。自动修复误操作可能导致比校验失败更严重的后果。