学习指南: 实践部分 11. 与真实 API 集成：从规范到部署

模块「实践部分 11. 与真实 API 集成：从规范到部署」中第 3 / 5 节课

您正在未登录状态下查看课程。请登录，以保存进度并参加测试。

主题: 实战部分 11。与真实 API 的集成：从规范到部署

难度等级: 中等

预计学习时间: 4-6 小时

前置要求: 熟悉第一卷第 7-9 部分中 SDD（Specify、Plan、Tasks、Implement、Validate）的概念。

了解团队评审的原则（第一卷第 16 部分）。

具备 CLI（命令行）和 Python 的基础知识。

对 Webhook 和 REST API 的工作原理有一般性了解。

学习目标: 掌握本地事件处理流水线：从原始 Webhook 到规范化事件，再到就绪状态（readiness）检查。

学会应用 25 分制就绪状态（readiness）评估模型，以决定是否允许自动修复。

理解并能够在执行实际操作之前识别阻塞条件（audit_trace、stateful workloads）。

掌握 SDD 中的阶段分离，确保规范（specify）阶段不会取代实现（implement）阶段。

能够根据分类法（VALIDATION_ERROR、LLM_CALL_FAILED 等）对 API 和流水线错误进行分类，以便选择恢复策略。

概述: 本章致力于在事件管理和自动修复的背景下与真实 API 进行实战集成。您将学习如何安全地运行从接收原始 Webhook（Grafana/PagerDuty）到受控部署或重启的流水线。作为主要的学习案例，使用生产事件 high_memory_usage。本章演示了如何使用 examples/real-api/ 中的脚本来规范化数据、通过基于 25 分制评分卡的就绪状态网关，并执行试运行（dry-run），确保禁止的操作被阻止、允许的操作有严格依据。

关键概念: Readiness（就绪状态）：根据 25 分制对流水线的正式评估。包含 5 个类别（Spec、Implementation、Verification、Process、Security），每项评分 0 到 5 分。自动允许的阈值为 23/25。如果分数低于此值，流水线将转入半手动模式。

SDD 阶段分离：一种将变更生命周期分为多个阶段的方法论：Specify（用户故事）、Plan（策略）、Tasks（步骤）、Implement（应用）、Validate（验证）。保护系统免于过早执行命令（"立即治疗"）。

Audit trace（审计跟踪）：因果关联日志，通过唯一的 incident_id 将传入的 Webhook、用户命令（例如 /sdd:specify）、创建的规范和差异（diff）连接起来。确保事件的可证明性和可复现性。

Dry-run（试运行）：针对预先批准的操作列表（pre-approved actions）模拟执行操作，而不对基础设施进行实际更改。可以确认操作是否被规范所允许。

Error taxonomy（错误分类法）：对 API 故障的分类（例如 VALIDATION_ERROR、TOOL_EXECUTION_FAILED），使编排器能够选择正确的恢复策略（停止、重试、降级、升级），而不是输出通用的 "failed" 状态。

Degraded mode（降级模式）：系统的状态，其中自动修复被禁用（例如在 LLM 故障或 Readiness 评分低时），但系统仍会继续保存证据并向操作员提供手动确认的步骤。

练习题: 名称: 规范化传入的 Webhook

问题: 您收到了来自 Grafana 和 PagerDuty 监控系统的原始有效负载。您需要运行规范化脚本，并确保输出的 JSON 与参考事件在字段级别完全一致。

解决方案: 1. 切换到示例目录：cd book2/examples/real-api

运行规范化脚本，并指定固件路径：

python3 scripts/normalize_webhook.py --grafana fixtures/webhook_grafana.json --pagerduty fixtures/webhook_pagerduty.json --expected fixtures/incident_event.expected.json

确保脚本以返回码 0 退出。如果返回码非零，请检查 stderr 中的架构验证错误。

难度: beginner

名称: 检查就绪状态网关（Readiness）

问题: 使用就绪状态检查脚本评估系统的三种不同状态：通过（24/25）、因审计失败（22/25）和因有状态负载失败（24/25，但无备份）。

解决方案: 按顺序运行脚本并分析输出：

python3 scripts/check_readiness.py --readiness fixtures/readiness_pass.json（预期：返回码 0，PASS）。
python3 scripts/check_readiness.py --readiness fixtures/readiness_block_audit.json（预期：返回码 1，因 audit_trace_coverage 原因 BLOCK）。
python3 scripts/check_readiness.py --readiness fixtures/readiness_block_stateful.json（预期：返回码 1，因缺少有状态负载的已确认备份而 BLOCK）。

难度: intermediate

名称: 试运行允许和禁止的操作

问题: 使用 dry-run 脚本针对规范 high_memory_usage 验证两个操作。第一个操作（restart_pod）应被允许，第二个操作（delete_namespace）应作为未授权操作被阻止。

解决方案: 1. 运行允许的操作： python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action restart_pod 确保返回码为 0，且 stdout 中有 PASS。

运行禁止的操作：

python3 scripts/dry_run.py --spec specs/high_memory_usage/specify.md --action delete_namespace 确保返回码为 1，且 stderr 中指明了阻止原因（操作不在 pre-approved 列表中）。

难度: intermediate

名称: 为自己的案例填写就绪状态评分卡

问题: 基于 25 分制模型，评估一个假设的（或您当前的）流水线。填写包含 5 个类别的表格，列出证据工件并识别阻塞条件，以达到 23/25 的阈值。

解决方案: 1. 创建一个包含以下列的表格：类别、分数、证据工件、扣分原因。

依次评估 Spec、Implementation、Verification、Process、Security。
对于 Spec，确保包含 WHY/WHAT/constraints。
对于 Security，检查是否包含回滚和紧急停止。
如果总分低于 23/25，请列出变更清单（例如："添加正式的升级触发器"、"为扩缩容分支实现 dry-run"）。

难度: advanced

案例研究: 名称: 生产事件 high_memory_usage

场景: Grafana 监控系统在 namespace appointments-api 中的 api-7b4 Pod 上检测到 memory_percent=93 持续 10 分钟。PagerDuty 将事件级别提升为 critical。接收到 Webhook，触发系统的自动修复流程。

挑战: 需要降低内存消耗（防止 OOMKill），同时不中断服务。运行简单地重启或删除资源的自动脚本是有风险的——可能会丢失有状态数据或扩大错误的爆炸半径。系统必须了解是否被允许自动执行操作，以及哪个操作是最低限度的。

解决方案: 1. 规范化：脚本 normalize_webhook.py 将来自 Grafana 和 PagerDuty 的数据合并为统一的 incident_event（incident_id=HM-2026-05-17-01）。

就绪状态网关：check_readiness.py 评估流水线。如果 audit_trace 低于 1.0 或有状态工作负载没有备份，则在人工干预之前操作将被阻止。
试运行：dry_run.py 验证操作 restart_pod 是否符合规范（pre-approved actions）。
执行：如果 readiness >= 23/25 且 dry_run 通过 PASS，则启动重启，并强制监控两个窗口和 6 分钟后的回滚路径。

结果: 自动化流水线安全地隔离了问题。允许的操作在完整审计（audit trail）下执行。流水线尝试执行未授权或危险操作的请求被安全网关严格阻止，从而防止了可能发生的整个服务故障。

经验教训: Specify 不应包含具体命令（例如 kubectl delete），而应描述 WHY 和 WHAT。

爆炸半径应受到限制（例如，仅限一个特定的 pod）。

系统故障（例如 LLM 问题）应使其进入降级模式（degraded mode），而不是在无解释的情况下完全停止。

在关键路径上完全不经过人工审查（human-review）的全自动修复仍然是风险实践（前沿领域）。