一、复合Hook的设计模式
复合Hook是指将多个独立的Hook步骤按照特定逻辑组合成一个完整的工作流。与单一Hook不同，复合Hook需要处理步骤间的依赖关系、数据传递和异常流转。下面介绍四种核心设计模式，它们是构建任何复合Hook的基础。
串联模式
多个Hook依次执行，前一个的输出作为后一个的输入。适用于有严格顺序依赖的场景，如"先检查格式，再运行lint，最后执行测试"。
并联模式
多个Hook同时独立执行，所有结果汇总后进入下一步。适用于无依赖关系的并行任务，如"同时进行安全检查、性能测试和代码扫描"。
条件分支
根据上一步的执行结果或输出值，决定下一步走哪条路径。适用于需要动态决策的场景，如"如果测试通过则继续部署，否则发送告警通知"。
循环模式
对一组相同类型的项目重复执行相同的Hook操作。适用于批处理场景，如"对仓库中所有微服务模块依次执行构建和发布"。
串联模式详解
串联是最基本也是最常用的复合模式。每个步骤按顺序执行，步骤N必须等待步骤N-1完成后才能启动。串联模式通常用一个有序的步骤数组来定义，运行时按索引顺序依次调用。
# 串联Hook定义示例
hooks:
- name: "format-check"
command: "prettier --check ."
- name: "lint"
command: "eslint src/"
depends_on: "format-check"
- name: "test"
command: "jest --coverage"
depends_on: "lint"
并联模式详解
并联模式可以显著减少总执行时间。所有并联步骤同时启动，调度器等待所有步骤完成后收集结果。并联模式的关键在于步骤之间必须没有依赖关系，否则会产生竞态条件。
设计要点：并联步骤之间不能共享可写资源。如果需要共享数据，考虑使用中间存储（如临时文件），并在所有并联步骤完成后由后续串联步骤读取。
条件分支详解
条件分支赋予复合Hook决策能力。每个分支节点包含一个条件表达式和对应的执行路径。条件可以基于上一步的退出码、输出内容中的特定标记，或自定义的判定函数。
# 条件分支配置示例
steps:
- name: "run-tests"
command: "pytest"
- name: "decision"
type: "condition"
if:
condition: "steps.run-tests.exit_code == 0"
then: "deploy"
else: "notify-failure"
循环模式详解
循环模式的核心是迭代器。它从输入源（如文件列表、项目数组或查询结果）获取项目列表，然后对每个项目执行相同的Hook序列。循环模式可以嵌套使用，形成更复杂的编排逻辑。
二、Hook间状态传递
在多步骤复合Hook中，步骤之间通常需要共享数据。状态传递的方式直接影响编排的可靠性和可维护性。以下是四种常用的传递方式，以及它们的最佳实践。
通过临时文件共享数据
临时文件是最通用的状态传递方式。上游步骤将处理结果写入约定路径的临时文件，下游步骤读取该文件获取数据。临时文件的格式建议统一使用JSON，因为它易于解析且支持复杂数据结构。临时文件应放置在专用的工作目录中，并在整个复合Hook执行完毕后清理。
# 上游步骤写入临时文件
echo '{"status":"passed","coverage":95,"issues":[]}' > $TEMP_DIR/step_result.json
# 下游步骤读取临时文件
result=$(cat "$TEMP_DIR/step_result.json")
coverage=$(echo "$result" | jq -r '.coverage')
使用环境变量传递简单状态
对于简单的字符串或数值状态（如步骤的退出码、计数器、布尔标志），环境变量是最轻量的传递方式。环境变量的作用域仅限于同一复合Hook的执行上下文，不同复合Hook之间不会相互污染。需要注意环境变量的值会被隐式转换为字符串类型。
约定输出格式（JSON）便于下游解析
建议所有步骤的输出遵循统一的JSON Schema约定。每个步骤的标准输出(stdout)应包含一个JSON对象，包含status、data、errors等顶层字段。下游步骤统一使用jq或内置JSON解析器提取数据。这种约定显著降低了步骤间的耦合度。
# 推荐的统一输出格式
{
"status": "success",
"data": {
"passed": 15,
"failed": 0,
"duration_ms": 3200
},
"errors": []
}
状态传递的最佳实践
- 优先使用临时文件传递复杂数据，环境变量传递简单标记
- 所有临时文件放在统一的工作目录下，便于管理和清理
- 输出格式优先选择JSON，避免使用自定义文本格式
- 每个步骤的输出文件应包含步骤名称或序号，防止命名冲突
- 约定明确的错误码规范（0=成功，非0=不同类别的失败）
- 避免在步骤间共享可变状态，尽量使用不可变的数据快照
三、复合Hook实用案例
以下三个案例展示了复合Hook在实际工作流中的典型应用。这些案例覆盖了代码提交、部署发布和代码审查三个最常需要自动化的场景。
案例一：提交前检查链
提交前检查链确保代码在进入版本控制前满足所有质量标准。典型的检查链包含四个阶段：格式化检查（format）→ 代码规范校验（lint）→ 单元测试（test）→ 提交操作（commit）。每个阶段都依赖前一个阶段成功完成，任何阶段失败都会中止后续操作。
工作流程：首先运行prettier检查代码格式，若通过则执行ESlint检查代码规范，然后运行jest单元测试和覆盖率检查，全部通过后自动触发git commit操作。整个链条在30秒内完成，大幅减少CI流水线的返工次数。
案例二：部署审批流程
部署审批流程是一个包含安全和人工审批环节的复合Hook，适用于生产环境的发布管理。流程分为四个阶段：安全检查（扫描依赖漏洞和密钥泄露）→ 测试通过（自动化测试和集成测试全部绿）→ 审批确认（发送审批请求到指定审批人）→ 部署执行（灰度发布或全量发布）。
# 部署审批流程复合Hook伪代码
workflow "production-deploy":
step "security-scan":
run: "trivy image $IMAGE_TAG"
on_fail: "abort"
step "run-tests":
run: "newman run integration-tests.json"
on_fail: "abort"
step "request-approval":
type: "manual-approval"
assignees: ["lead-dev", "ops-lead"]
timeout: 3600
step "deploy-canary":
run: "kubectl set image deployment/app app=$IMAGE_TAG"
on_fail: "rollback"
案例三：代码审查流程
代码审查流程在Pull Request创建后自动触发，形成一个完整的审查闭环：质量检查（运行静态分析和圈复杂度检测）→ diff分析（生成变更文件的差异摘要和影响范围）→ 自动审查（基于规则引擎自动标注潜在问题）→ 结果通知（将审查结果汇总后发送到钉钉或Slack频道）。
关键收益：自动审查可以拦截约70%的常见代码问题（如空指针风险、硬编码密钥、超长函数等），大幅减轻人工Reviewer的负担。人工Review可以聚焦在架构设计和业务逻辑等高价值环节。
四、超时和恢复机制
复合Hook执行时间可能很长，步骤数量多时失败概率也随之增加。健壮的超时和恢复机制是生产级复合Hook不可或缺的组成部分。
复合Hook的整体超时控制
应为整个复合Hook设置一个总超时时间（如30分钟）。当总执行时间超过该阈值时，调度器立即终止所有正在运行的步骤，并将整体状态标记为"超时失败"。总超时应根据历史执行数据设定，建议为P99执行时间的1.5倍。
单个步骤超时不影响其他步骤
在并联模式下，某个步骤超时不应自动终止其他并联步骤。调度器应允许已超时的步骤独立失败，而其他步骤继续执行。后续的串联步骤应根据上游步骤的实际完成状态决定执行路径。超时的步骤应输出明确的超时错误信息，便于排查。
注意：如果某个超时步骤的输出是后续步骤的必要输入（串联依赖），则后续步骤应被跳过并标记为"依赖失败"，而不是被阻塞挂起。这可以避免复合Hook陷入死等状态。
失败步骤的重试策略
对于偶发性失败（如网络抖动、临时资源不可用），自动重试是最有效的恢复手段。重试策略包含三个参数：最大重试次数（建议3次）、重试间隔（建议指数退避，如1s→2s→4s）和重试条件（只对特定的失败码或错误类型重试）。幂等性是重试的前提条件，确保多次执行产生相同的结果。
# 带重试策略的步骤定义
steps:
- name: "deploy-service"
command: "helm upgrade --install myapp ./chart"
retry:
max_attempts: 3
backoff: "exponential"
initial_delay: 1
retry_on_exit_codes: [1, 2, 137]
部分成功时的处理方案
在包含多个并联分支的复合Hook中，经常出现部分分支成功、部分分支失败的情况。设计时应明确约定部分成功的处理策略：
- 严格模式：任一分支失败则整体标记为失败，适合安全敏感场景
- 宽松模式：记录失败分支的日志，但整体继续执行，适合非关键路径
- 降级模式：失败的分支用默认值代替，后续步骤基于降级后的状态继续
五、复合Hook的调试
复合Hook的调试比单一Hook复杂得多，因为涉及步骤间的状态传递和时间顺序。良好的可观测性是调试效率的基石。
每个步骤的日志输出
每个步骤在执行开始、结束和失败时都应输出结构化日志。日志应包含步骤名称、步骤ID、时间戳、执行时长和退出码。建议使用JSON格式输出日志，便于后续的日志聚合和分析工具处理。步骤的stdout和stderr应分别捕获和记录。
中间状态的可视化
在复合Hook执行过程中，调度器应提供一个实时状态面板，展示每个步骤的当前状态（等待中/运行中/已完成/失败/超时）、已用时间和输出摘要。Web界面或CLI仪表盘都可以实现。可视化工具例如：使用Graphviz生成执行流程图，或使用Terminal UI显示实时进度条。
模拟运行和测试
在将复合Hook应用于生产环境之前，应使用模拟模式进行验证。模拟模式下，所有步骤的副作用被禁用（如不实际发送HTTP请求、不修改文件系统），只验证编排逻辑的正确性。模拟运行应输出完整的执行计划和预期结果，方便开发者提前发现逻辑缺陷。
建议：为每个复合Hook编写单元测试和集成测试。单元测试验证单个步骤的输入输出转换逻辑，集成测试验证整个编排流程在模拟环境中的执行结果符合预期。
常见问题排查
- 步骤间数据未传递：检查临时文件路径和环境变量名称是否约定一致
- 并联步骤出现竞态：确认并联步骤之间没有共享可写资源
- 条件分支走错路径：检查条件表达式的语法和步骤索引引用是否正确
- 重试循环不终止：检查重试条件是否过于宽泛，建议增加最大重试次数限制
- 超时设置不合理：根据历史执行数据的P99值调整超时阈值
- 日志丢失：确保日志缓冲区在步骤异常终止时正确刷新