Notes /react/15-engineering-and-architecture/04-cicd-and-quality-gates

CI/CD 与质量门禁：构建可靠的自动化流程

一句话结论：通过 CI/CD (持续集成/持续部署) 管道，建立一套由 Lint、类型检查、测试和构建组成的自动化“质量门禁”，是确保代码在合并入主干前始终处于健康、可发布状态的关键工程实践。

1. 什么是 CI/CD？

持续集成 (Continuous Integration - CI)：一种开发实践，团队成员频繁地将其代码变更集成到共享的主干仓库中。每次集成都会通过自动化构建和测试来验证，从而尽早地发现集成错误。
持续部署/交付 (Continuous Deployment/Delivery - CD)：
- 持续交付：在 CI 的基础上，将通过所有测试的代码自动发布到一个“准生产”环境，以供手动批准部署到生产环境。
- 持续部署：更进一步，将通过所有测试的代码自动部署到生产环境。

核心目标：实现更快、更可靠、风险更低的软件交付。

2. 自动化质量门禁 (The Quality Gates)

质量门禁是在 CI 流程中设置的一系列自动化检查关卡。只有当代码变更逐一通过所有关卡时，才被允许合并到主分支。

一个典型的 React/TypeScript 项目的质量门禁流水线如下：

Linting (代码风格检查)：确保代码遵循团队统一的编码规范。
Type Checking (类型检查)：利用 TypeScript 捕获类型错误。
Unit & Integration Testing (单元/集成测试)：验证代码逻辑和组件交互。
E2E Testing (端到端测试)：验证关键用户流程。
Build (构建)：确保应用可以成功打包。
(可选) Preview Deployment (预览部署)：为每个 Pull Request 创建一个临时的、可公开访问的应用实例，方便 UI/UX 和产品经理进行审查。

3. 使用 GitHub Actions 实现 CI

GitHub Actions 是一个内置于 GitHub 的强大 CI/CD 工具。你通过在仓库的 .github/workflows/ 目录下创建 YAML 文件来定义工作流。

示例：一个完整的前端 CI 工作流

文件名: .github/workflows/ci.yml

name: CI

# 触发条件：当有代码 push 到 main 分支，或创建/更新一个 Pull Request 时
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  # 定义一个名为 "quality-gates" 的 job
  quality-gates:
    # 运行环境：使用最新的 Ubuntu 系统
    runs-on: ubuntu-latest

    # 定义一系列步骤
    steps:
      # 步骤 1: 检出代码
      - name: Checkout repository
        uses: actions/checkout@v3

      # 步骤 2: 设置 Node.js 环境
      # 使用 pnpm 作为包管理器，并利用其缓存机制
      - name: Setup Node.js and pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 8 # pnpm 版本
          node-version: '18' # Node.js 版本

      # 步骤 3: 安装依赖
      # Turborepo 会自动利用其远程缓存
      - name: Install dependencies
        run: pnpm install

      # 步骤 4: 质量门禁 - Lint
      - name: Run Lint
        run: pnpm lint

      # 步骤 5: 质量门禁 - Type Check
      - name: Run Type Check
        # 在 monorepo 中，通常需要对每个包分别进行类型检查
        # 假设 turbo.json 中配置了 lint 和 typecheck 任务
        run: pnpm typecheck

      # 步骤 6: 质量门禁 - Unit & Integration Tests
      - name: Run Tests
        run: pnpm test

      # 步骤 7: 质量门禁 - Build
      - name: Run Build
        run: pnpm build

      # (可选) 步骤 8: 质量门禁 - E2E Tests
      # E2E 测试通常更耗时，可以放在一个独立的 job 中并行执行
      # - name: Run E2E Tests
      #   run: pnpm test:e2e

工作流解析：

on: 定义了触发工作流的事件。这里是针对 main 分支的 push 和 pull_request。
jobs: 一个工作流可以包含一个或多个 job。它们可以并行或串行执行。
runs-on: 指定了运行 job 的虚拟机环境。
steps: 一个 job 由多个步骤组成，它们会按顺序执行。
uses: 使用社区或官方提供的 Action，例如 actions/checkout 用于拉取代码，pnpm/action-setup 用于设置 pnpm。
run: 执行命令行指令。

结合 Turborepo 和缓存

pnpm 缓存：pnpm/action-setup 会自动配置 pnpm 的内容寻址存储缓存，极大地加快了 pnpm install 的速度。
Turborepo 远程缓存：
1. 在 Turborepo 的官网 (Vercel) 上创建一个账号并关联你的仓库。
2. 在仓库的 Settings > Secrets and variables > Actions 中，添加 TURBO_TOKEN 和 TURBO_TEAM 这两个 secret。
3. 现在，当 GitHub Actions 运行 pnpm build 或 pnpm test 时，Turborepo 会自动连接到远程缓存。如果某个任务的输入没有变化，它会直接下载缓存的产物（例如 dist 目录）和日志，而不是在 CI 服务器上重新执行，从而将 CI 时间从几十分钟缩短到几分钟甚至几十秒。

4. 保护主分支 (Branch Protection Rules)

最后一步是强制执行你的质量门禁。在 GitHub 仓库的 Settings > Branches 中，为你的 main 分支添加保护规则：

Require a pull request before merging: 强制所有变更都必须通过 PR。
Require status checks to pass before merging: 勾选此项。
在下方的状态检查列表中，选择你的 CI job (例如 quality-gates)。

设置完成后，任何未通过 quality-gates job 检查的 PR 都将无法被合并，从而形成了一个完整的、自动化的质量保障闭环。

5. 关联阅读

GitHub Actions 官方文档: docs.github.com/en/actions
Turborepo 官方文档: CI with Turborepo
pnpm in CI: pnpm.io/continuous-integration