2.2 持续集成实践

2.2 持续集成实践

本节摘要：持续集成（CI）要求所有开发者频繁把代码合入主干，并且每次合入都触发自动化的构建与测试，几分钟内给出判决。本节用一份完整的流水线配置、一段真实的失败排查记录和一套性能优化清单，讲清 CI 的构成要件与运转纪律。核心观点：CI 的价值不在工具，而在"主干永远可信"这个状态。

学习目标

1. 说出持续集成的定义与三个硬性要件
2. 读懂并编写覆盖构建、测试、制品发布的流水线配置
3. 按"五层定位法"快速排查 CI 失败
4. 用缓存、分层与并发把流水线压进十分钟

一、CI 到底解决什么问题

先看没有 CI 的时代。一个十人团队各自开发两周，周五"集成日"一起合并代码。合并冲突解三个小时是常态，合完之后编译不过、测试互相踩踏，最后往往演变成"谁的模块出问题谁负责在周末修好"。集成本该是确认彼此兼容的动作，却成了每周一次的受难日。根本原因是集成批量太大、频率太低——问题攒到周五集中爆发。

持续集成的处方直截了当：每天至少一次把代码合入主干；每次合入自动触发构建与测试；失败则以最高优先级立刻修复。这个定义里的三个"每天/每次/立刻"是硬性的，缺一个，CI 就退化成"自动化的周集成"——只是把受难日自动化了。

CI 追求的状态是：主干在任何时刻都是可构建、可测试、可发布的最新的代码。有了这个状态，后续的持续交付（第 3 章）才有可靠的原材料；没有它，每次发布都是从一堆"不知道能不能跑"的代码里赌一把。

二、一条真实的流水线

下面是一条简化但结构完整的流水线配置，来自一个容器化的 Web 服务项目。它覆盖了 CI 的标准五段：检出、静态检查、构建、测试、制品发布。

# 流水线定义：提交触发，目标 10 分钟内出结果
stages: [check, build, test, package]

jobs:
  lint:
    stage: check
    script:
      - lint-cli run --config strict   # 静态检查：风格 + 明显缺陷
    cache:
      key: lint-deps
      paths: [.lint-cache/]

  build:
    stage: build
    script:
      - docker build --target deps -t cache:latest .   # 依赖层缓存
      - docker build -t app:$CI_COMMIT_SHORT_SHA .     # 应用层构建
    cache:
      key:
        files: [package-lock.json]      # 锁文件不变则命中缓存
      paths: [node_modules/]

  unit-tests:
    stage: test
    script:
      - test-runner unit --coverage --parallel 4
    coverage: '/覆盖率\s+(\d+\.\d+)%/'
    artifacts:
      reports: { junit: reports/unit.xml }
      paths: [coverage/]
      expire_in: 1 week

  integration-tests:
    stage: test
    services:
      - name: postgres:16
        alias: db
    script:
      - migrate up --dsn $TEST_DB_URL
      - test-runner integration --parallel 4

  package:
    stage: package
    only: [main]                        # 只有主干打正式制品
    script:
      - docker push registry.internal/app:$CI_COMMIT_SHORT_SHA
      - provenance generate --image app:$CI_COMMIT_SHORT_SHA  # 制品溯源清单
​

几个设计决策值得展开。

静态检查放在最前面，因为它最便宜（秒级），能让拼写类的低级问题在三分钟内被打回，不占用后面的构建资源。

集成测试拉起真实的服务依赖（例中的数据库），而不是全用模拟。模拟会让测试跑得飞快，但会掩盖真实的兼容性问题——集成测试的价值恰恰在"真"。

只有主干打正式制品，特性分支只跑测试不打包。这样制品仓库里每个镜像都对应一个被评审、被完整测试过的提交，版本纪律不会涣散。

每个制品带溯源清单，记录它是哪个提交、哪条流水线、什么依赖版本构建的。第 3 章讲部署时你会看到它的用处：部署到生产的每个制品都能回答"我从哪里来"。

三、一次失败的排查实录

流水线不会永远绿色。下面是一次真实的失败与排查过程，展示标准的定位思路。

10:32:14  unit-tests 阶段失败（第 3 次重试）
10:32:15  FAILED tests/order/coupon.test.js
10:32:15  Expected: 87.50
10:32:15  Received: 75.00
10:32:16  at Object.<anonymous> (coupon.test.js:88)
​

按五层定位法走：**第一层，环境问题？**看失败是否只在某台执行机上出现、重试是否可复现。本次三次重试全部失败且稳定复现，排除环境抖动。**第二层，顺序依赖？**单独跑这个测试文件看是否通过。单独跑通过了——说明测试之间有隐藏依赖。**第三层，并行污染。**这份配置用了四路并行，某些测试框架会共享进程内单例（比如货币汇率缓存），并行时另一个测试改了汇率缓存，导致本测试的期望值失效。**第四层，确认根因。**查看另一并行分片里的提交记录，昨天有人给汇率模块加了"测试内重置缓存"的逻辑，恰好与本测试的初始化顺序冲突。**第五层，修复并加防护。**修复方式不是去掉并行（那会把流水线拖长一倍），而是把汇率缓存改为显式注入，测试各自持有独立实例；同时在 CI 里加一个"随机排序跑两遍"的守护任务，让顺序依赖今后会自动暴露。

这个案例的教训有普遍意义：流水线失败大致符合二八分布——八成是代码问题，两成是流水线自身的问题（缓存、并发、依赖漂移）；但排障的顺序应该先怀疑便宜的原因（环境、顺序），再怀疑昂贵的原因（业务逻辑）。顺序反了，你会花两小时去审一段根本没错的业务代码。

四、CI 的运转纪律

工具配好后，CI 的成败取决于三条纪律。

**纪律一：红了必须马上修，不允许"先合再说"。**主干红灯超过一小时，所有人的提交都在往一个已知有问题的基线上叠加，问题会指数恶化。成熟团队有个明确规则：主干红时，唯一被允许的合并是修复它的合并。必要时锁定主干——这不是官僚，是止损。

**纪律二：提交前本地预跑。**推送前在本地跑一遍快速检查（格式、单测子集），把最便宜的错误拦在自己机器上。CI 的十分钟应该留给本地跑不了的重量级检查（集成测试、全量构建）。

**纪律三：把流水线当产品维护。**有人对它负责：时长超过十五分钟要优化，flaky（时红时绿）的测试要隔离或删除，缓存策略要随依赖更新调整。放任不管的流水线会慢慢膨胀到人人绕行——那时 CI 就名存实亡了。

五、流水线性能优化清单

反馈速度是 CI 的生命线。一套按性价比排序的优化清单：

依赖缓存。按锁文件哈希做缓存键，锁文件不变直接复用依赖目录，通常省下两到四分钟。构建分层。把变更频率低的依赖层和频繁变更的应用层分开构建，依赖层只在锁文件变化时重建。测试并发。四路并发接近线性加速，但前提是先消灭测试间的隐藏依赖（前面案例的教训）。按影响面选择性执行。提交只改了文档就跳过全量构建；改了哪个模块就重点跑那个模块的测试与相关联的集成测试，其余靠主干定期全量兜底。失败快速化。把最常失败的检查放最前面，让最常见的失败以最低的成本暴露。

优化前后对比（同项目实测）
──────────────────────────────────────
             优化前        优化后
检出+安装     4m10s   →   0m40s（依赖缓存）
构建          3m20s   →   1m05s（分层构建）
单元测试      5m50s   →   1m30s（四路并发）
集成测试      4m30s   →   2m10s（选择性执行）
──────────────────────────────────────
合计         17m50s   →   5m25s
提交到反馈    半小时级  →   分钟级
​

反馈从十七分钟压到五分钟意味着什么？开发者还沉浸在代码上下文里时判决就到了，修复几乎是顺手的事；十七分钟则足以让人切换去做别的事，回来时上下文已经冷了。这是反馈原则最直观的一次兑现。

本节要点回顾

• CI 定义三要件：每天合入、每次触发、失败立刻修——缺一则退化为自动化周集成
• 目标状态：主干任何时刻可构建、可测试、可发布
• 流水线五段：检出、静态检查、构建、测试、制品发布；便宜检查在前，只有主干打正式制品并附溯源清单
• 五层定位法：环境 → 顺序依赖 → 并行污染 → 代码根因 → 加守护防复发
• 三条纪律：红锁主干、本地预跑、流水线有人当产品维护
• 性能清单：依赖缓存、分层构建、并发、选择性执行、失败快速化——反馈时长决定修复成本