单仓多包的 CI 策略与受影响分析

仓库规模放大三重成本：
  1. 任务数量放大：N 个包 × M 个任务（build/test/lint）= N×M 个执行单元
  2. 依赖深度放大：底层工具包一变，所有下游包全部失效
  3. 队列放大：任务多了，runner 不够，等待时间超过执行时间

输入：git diff 得到的改动文件列表
输出：需要重跑的任务集合

步骤：
  1. 把改动文件归属到包（文件路径 → 包）
  2. 在依赖图上做「反向可达」：找出所有（直接或间接）依赖这些包的包
  3. 把这些包的对应任务加入待跑集合
  4. 叠加「始终要跑」的任务（如全局 lint、契约测试）

# 相对目标分支的合并基（merge base）——最常用
BASE=$(git merge-base HEAD origin/main)

# 相对 PR 的目标分支
nx affected -t build --base=origin/main --head=HEAD

# Turborepo 的等价写法
turbo run build --filter='...[origin/main]'

基线选择要点：
  - 用 merge-base 而非分支 tip：分支 tip 会被别人后来的提交污染
  - 合并队列里要用「队列前一个候选」作为基线，而非 main
  - 主分支上的直接提交（hotfix）通常退化为全量，属预期

libs/design-system 被 30 个包依赖
  → 改动它 → 30 个包 + 它们的下游全部失效
  → 一次提交触发几乎全量 CI

缓解手段：
  1. 把高频变动的代码上移为「叶子包」，减少依赖扇出
  2. 对底层包引入版本化发布，下游按版本依赖而非源码依赖
  3. 把底层包拆成更细粒度，避免「一处改动、全体重算」

包图：  web → ui → tokens
任务图（每个包展开为 build/test/lint）：
  tokens#build → ui#build → web#build
  web#build → web#test → web#e2e
  ^build 语义：先跑所有依赖包的 build，再跑本包 build

# .github/workflows/ci.yml — CI 只做触发与汇总
name: ci
on:
  pull_request:
jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # 受影响分析需要完整历史
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - name: Run affected tasks
        run: npx nx affected -t lint test build --base=origin/main --head=HEAD

L1（秒级，PR 必跑）：lint、格式检查、类型检查、受影响包的单元测试
L2（分钟级，PR 必跑）：受影响包的集成测试、构建产物
L3（十分钟级，合并后或 nightly）：全量 E2E、跨包契约测试、性能基准
L4（小时级，定时）：全量回归、安全扫描、依赖审计

# Nx：限制并行任务数，避免打爆 runner
nx affected -t build --parallel=4

# Turborepo：设置并发度
turbo run build --concurrency=50%

并行的两个天花板：
  1. 图结构：依赖链越长，可并行的宽度越小（关键路径决定下限）
  2. 资源：runner 数量、CPU/内存、外部服务（如数据库）连接数

# GitHub Actions 矩阵分片
strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx nx affected -t test --base=origin/main --shard=${{ matrix.shard }}/4

分片粒度选择：
  按包分片   → 天然均衡，但包大小不均时会倾斜
  按任务分片 → 更均衡，但同一包的任务可能跨机器，制品传递变复杂
  动态分片   → 由工具根据历史耗时分配（Nx DTE、Bazel 远程执行）

反模式：每个下游任务都重新编译依赖包的源码
  → 同一个包被编译 N 次，缓存命中率再高也救不回

正模式：依赖包的构建产物作为「输入」传递给下游任务
  → 依赖包命中缓存 → 下游拿到确定性产物 → 下游也可命中缓存

# 方式一：工作区内直接共享（同机、同工作区）
# 编排器约定产物目录（dist/），下游从相对路径读取

# 方式二：CI 制品上传下载（跨 job/跨机器）
- uses: actions/upload-artifact@v4
  with:
    name: libs-ui-dist
    path: libs/ui/dist
    retention-days: 1
- uses: actions/download-artifact@v4
  with: { name: libs-ui-dist, path: libs/ui/dist }

# 方式三：包管理器本地链接（pnpm workspace / npm workspaces）
# 下游通过 workspace: 协议引用，无需发布

缓存（cache）：按输入哈希复用「任务输出」，是优化手段，命中与否不影响正确性
制品（artifact）：构建的「正式产物」，要被打包、发布、部署，是交付物

区别：缓存可以随时清空重建，制品必须可追溯、可复现、有版本

合并队列的行为：
  1. PR 进入队列后，用「队列中前一个候选的结果」作为新基线
  2. 在最新基线上重跑受影响分析 + 受影响任务
  3. 通过则合入，失败则弹出并通知作者

单仓收益：主干始终保持「可发布」状态，避免「合完就红」

错误做法：队列中的候选仍用 origin/main 作为基线
  → 看不到「前面已合入候选」带来的影响 → 漏跑
正确做法：用「队列中前一个候选的合并结果」作为基线
  → 每个候选都相对真实的上游状态计算影响

# 分支保护要点
- 要求 PR 通过「必需检查」（required checks）
- 必需检查应覆盖：受影响任务的聚合结果 + 全局门禁
- 禁止直接推送 main（含管理员）
- 要求分支最新（require branches up to date）或启用合并队列

阶段一：建立依赖图
  - 统一包清单格式，确保依赖声明完整
  - 用静态分析补齐隐式依赖，输出可视化图

阶段二：引入受影响分析
  - CI 中改为 nx affected / turbo --filter
  - fetch-depth: 0，正确计算 merge-base

阶段三：分级与编排
  - L1/L2 进 PR，L3/L4 移到主分支与定时
  - 用编排器替代手写 YAML DAG

阶段四：合并队列
  - 启用合并队列，修正基线为「队列前一个候选」

阶段五：度量与收敛
  - 上报命中率、CI 时长、漏跑率

必看指标：
  - CI 平均时长（P50/P90）
  - 受影响任务命中率（affected 集合 / 全量集合）
  - 漏跑率（合并后主分支失败的 PR 占比）
  - 缓存命中率
  - 排队等待时长 vs 执行时长