3. 质量门禁规则设计原则

质量门禁（Quality Gate）是嵌入软件交付管道的“检查点”，用于在代码提交、构建、部署、压测等关键环节自动阻断不符合质量预期的变更。设计一套有效的门禁规则，必须遵循以下四项核心原则：可量化、自动化、渐进式、可回溯。

3.1 可量化原则

门禁规则必须基于客观、可测量、可比较的指标，杜绝“性能良好”“代码质量高”等模糊描述。只有量化，才能自动化判断，才能在不同版本间进行趋势对比。

3.2 自动化原则

门禁规则的检查、判定、反馈、阻断必须由工具链自动执行，无需人工介入。人工审核应作为“例外流程”而非“默认流程”。

• 触发自动化：门禁检查应绑定到 CI/CD 管道的特定阶段（如：PR 创建、合并到主干、构建完成、压测结束）。
• 判定自动化：工具根据预设阈值自动输出 Pass / Fail / Warning 结果。
• 反馈自动化：结果自动写入 PR 评论、消息通知（如钉钉/飞书/邮件）、质量看板。
• 阻断自动化：Fail 结果自动阻止合并、阻止部署到下一环境、触发回滚流程。

# 伪代码：自动化门禁判定逻辑示例
def quality_gate_check(report):
    if report.critical_vulnerabilities > 0:
        return "FAIL", "阻断：存在 Critical 级别安全漏洞"
    if report.p99_latency > 200:
        return "FAIL", "阻断：P99 延迟超过 200ms"
    if report.coverage < 80:
        return "WARN", "警告：新增代码覆盖率不足 80%，请补充测试"
    return "PASS", "门禁通过"

3.3 渐进式原则

门禁规则不应一次性全量上线，而应分阶段、分范围、分等级逐步推行，避免因规则过于严格导致交付阻塞，或因规则过于宽松而形同虚设。

3.4 可回溯原则

每一次门禁检查的输入、判定逻辑、输出结果、操作记录都必须被完整记录，并支持事后审计与根因分析。

• 记录内容：检查时间、触发版本/Commit ID、检查项列表、各指标实际值、阈值、判定结果、执行人（如果是手动操作）、备注。
• 存储方式：建议将门禁日志写入不可篡改的存储（如：Elasticsearch + 索引生命周期管理，或对象存储 + 归档）。
• 查询能力：支持按版本、时间范围、服务名、结果状态等维度快速检索。
• 审计用途：用于复盘线上事故、评估门禁有效性、优化阈值设定。

# 门禁检查记录 JSON 示例
{
  "gate_id": "gate_capacity_001",
  "service": "order-service",
  "version": "v2.3.1-rc.2",
  "commit_sha": "a1b2c3d4e5f6...",
  "check_time": "2025-03-21T14:30:00Z",
  "items": [
    {"metric": "p99_latency", "value": 185, "threshold": 200, "result": "pass"},
    {"metric": "error_rate", "value": 0.05, "threshold": 0.1, "result": "pass"},
    {"metric": "cpu_usage", "value": 72, "threshold": 70, "result": "fail"}
  ],
  "final_result": "fail",
  "operator": "system",
  "comment": "CPU 使用率超阈值，自动阻断"
}

3.5 四项原则的关系与落地框架

四项原则并非孤立存在，而是构成一个完整的门禁设计闭环。下图展示了它们之间的依赖与协作关系：