跳转到内容

第 8 章 测试、CI/CD、代码审查与协作

来自《系统架构与工程化学习》 · 原稿更新 2026-11-09 · 服务器只读阅读视图

8.1 CI、CD 与测试的分工

从修改代码到真实验收的质量门禁

测试检查行为是否符合预期,CI 自动运行已有的检查,CD 把通过门禁的制品交付到目标环境。

我踩过的坑

  • 把 Job 说成“具体执行命令的层”,以为“合并 main 才跑”要用外部事件,还以为装了 CI 就会自动测接口。
  • 两次“CI 绿了却没跑到测试”。第一次 Workflow 只做 py_compile;改成 unittest discover 后收集 60 个,却静默跳过 pytest 风格的测试函数与 fixture,同仓用 pytest 能发现 66 个。
  • CI 跑不起来时我怀疑过 DeepSeek 审查模型欠费。GitHub Actions 配额和调用审查模型的 API 账单是两笔成本,workflow 连 runner 都没启动时,审查请求根本没发生。

正确理解

  • 只配 CI 不写测试,CI 不会自己知道业务接口该怎样工作,它只执行我写好的检查。
  • Workflow → Job → Step:Workflow 定义整条流水线和触发条件;Job 是能独立调度、和其他 Job 并行的单元,先后关系用 needs 表达;Step 是同一个 Job 里依次执行的命令或 Action。命令由 Step 执行,不是 Job。
  • “main 有新提交就跑”用 push 加分支过滤即可,另有 pull_request、workflow_run 等触发事件。
  • 门禁让便宜的检查尽早失败。有些集成测试依赖构建产物,放在构建之后也合理,不是“测试必须全在构建前”。
  • CI 绿了,还要看日志里实际执行的测试命令、收集数、跳过数,和仓库预期的测试清单对不对得上。审查模型的 CI 跑不起来,按排队、checkout、依赖、模型请求、评论写回的顺序查,也别把本地跑通的模型审查说成 CI 通过。

8.2 单测、集成与 E2E

单测、集成和真实 E2E 各自证明不同的东西,谁也不能替谁下结论。

正确理解

  • 单测证明局部逻辑,集成测试证明几个组件能协作,真实 E2E 和产品验收证明用户拿到了预期结果。单测绿了,不能证明外部平台已经收到 Trace。
  • 缺凭据或没有 Redis、跑不了集成测试时,写“环境不足,未验证”,不能算通过,也不能算逻辑失败。
  • 写入型测试用隔离数据或本轮 run_id,删除前列出要清理的对象、备份路径和恢复办法。曾经发生过测试清理把真实计时记录一起删掉。
  • 用户自己把数据改对,只解决了这一次的症状,不代表程序没有边界缺陷。合法输入、非法输入的提示、合法边界的计算要分别判定,用一组合法和非法样本做回归。
  • Headless 和交互模式加载的扩展、工作流可能不同。某旧版扩展在没有 UI 时会主动关掉浏览器审阅流程,所以测试要写明运行模式;CLI 能搜索成功,不代表交互弹窗和用户确认链路验收过了。
  • UI 截图看着正常,但测试要求的 Mock 任务根本没加载,就等于没测到目标场景。先断言 Mock 数据和 DOM 里的任务数、日期、网络响应都在,再截图看布局。

动手前检查

  • 这轮测试删除的数据,能证明只属于本轮吗?
  • 环境不足的用例,是否记为“未验证”而不是“通过”?
  • 测试运行模式(Headless 或交互)写清了吗?

合并后的回归要定位实际阶段(待学习)

合并前后调用次数不同,先分清是前置查询新增了,还是后置规则变了。给断言明确的阶段和业务结果,保留普通输入和例外输入的对照。集成夹具按稳定标识从配置里取模型或供应商,并断言这项存在。一次从列表第一项取夹具再替换模型名,配置调序后配错了组合,测试失败反映的是夹具变了。

组合后的调用阶段 · 稳定标识夹具

8.3 质量门禁、覆盖率和回归集

覆盖率说明测试执行到哪些代码,不说明断言是否真的检查了正确性。

我踩过的坑

  • 把单元测试当作金字塔顶层,回答“上层全部回归、下层挑重要的”。
  • 讲回归测试只说“测老功能”,没想到公共函数变更会沿调用链影响其他功能。

正确理解

  • 测试金字塔:单元测试在底层,数量多、跑得快、定位准;集成测试在中间;E2E 在顶层,覆盖关键用户流程,但环境成本高。比例按产品风险定,不是固定公式。
  • 回归测试是改完之后重跑已有的行为检查,可以包括单测、集成和 E2E,不是另一层测试。便宜的单测尽量全跑,昂贵的集成和 E2E 按影响面、风险和预算挑,但不能只测新功能不管旧行为。
  • 重要 Bug 修好后加进回归集,复杂场景再补边界值和关键失败路径。
  • lint、类型检查和单测谁更快,要看真实项目和 CI 数据。
  • 两种检查测试是否有效的方法:变更覆盖率(Diff Coverage)看新改的代码被执行了多少,避免历史覆盖率掩盖新增盲区;突变测试(Mutation Testing)故意改掉关键条件,看现有断言能不能抓到。突变测试成本高,可以先用在核心逻辑上。两者都替代不了真实用户路径的验收。
  • 门禁的数字要带条件看。旧个人 AIHOT 实验里,第一次 Gate 检出 2 个圈复杂度超限和 1 个失败断言,针对性修复后报告 579 个测试通过、变更行覆盖 93%。这只说明当时的规则和测试过了门槛,替代不了业务需求、用户体验、权限和部署验证;门禁自己的覆盖率参数和测试范围也要有单测。
  • 评分器读 JSON 证据之前,要先检查来源文件本身。一次个人 Agent 代码审查用了打开后 fstat、O_NOFOLLOW、有界读取、严格 UTF-8/JSON 校验、关闭 fd,防止 symlink、超大文件、编码损坏污染 Gate 账本。O_NOFOLLOW 一般不保护所有父路径,目录可能被替换时,要用基于目录 fd 的方案。(来自一次子代理审查报告,未复跑。)
  • 评估账本的输入有非法 UTF-8 时,要拒绝,并证明原文件一个字节都没变。测试不只看有没有抛异常,还要比对落盘哈希、有没有半写、索引状态。失败路径的数据保护要和成功路径一样严格。

检查结果与阻断条件分开(待学习)

把无规则、缺测量、符合、违规分开。只有反对样本时,仍可检查明确要避开的区间。没有证据时保留空评分,构建是否继续由调用方按契约决定。必须豁免一种提示时,用明确的列表限制范围,新出现或未识别的缺口沿用原保护。测试分别覆盖正常通过、没有足够证据、真实违规和应拦的未知提示,也确认独立 CLI 与真实构建入口的退出行为。

偏好证据边界 · 检查与构建门禁 · 证据豁免的范围

8.4 Secrets、Cache 与 Artifact

三者分别是输入凭据、可复用的中间产物、本次运行的输出。

类型 用途
Secrets(输入凭据) 流水线用的 Token、密码,按权限提供,不写进源码和普通日志
Cache(复用中间产物) 缓存可重建的依赖、构建中间结果,减少重复工作
Artifact(本次输出) 保存此次运行的报告、包、截图供后续 Job 或人下载

我踩过的坑

  • 只记住三件套名称,没理解“输入凭据 / 重用 / 输出”的不同,也分不清 CI Secrets 和容器运行时的 Secret。

正确理解

  • CI 平台的 Secret 通常通过表达式或运行环境交给 Step;容器的 Secret 常通过挂载文件交给服务,不是同一套实现。
  • 日志自动掩码挡不住误打印或换了编码的凭据。用最小权限、短期凭据,日志里不输出敏感值。

校验最终产物和真实写入位置(待学习)

开源检查分开查当前源码、Git 历史、图片和最终安装包。曾在 Swift 发布可执行文件里发现源码搜索没找到的本机路径,来自调试信息和资源回退代码。按同一产物重新扫描后才确认这类命中消失。命中为零只覆盖本轮检查项。

测试安装命令时,除临时工作目录和 HOME,还要查包管理器的缓存与全局前缀。例如 npm 全局安装应确认前缀和目标目录也在隔离范围内。实际运行后核对写到哪里、预期文件是否存在、完成输出有没有出现。退出码为零时也可能停在交互选择器。

最终安装包隐私检查 · 隔离安装的写入路径

8.5 Issue、PR 与分支复审

Issue 说清问题,PR 说清改动和证据,独立分支隔离未完成的工作。

我踩过的坑

  • 2026-09-15 我反馈:额度快重置时会同时交给 Agent 多个任务,有的显示已完成,隔天测试才发现代码没进 main。问题不在 worktree,而在“改好分支”和“交付到目标分支”被混成一个状态。
  • AI 加快了代码产出,也挤掉了我深入理解细节的时间。提交 PR 前,我要能讲清业务背景、调用链、影响范围和测试证据。

Issue 与 PR

  • Issue 记录复现步骤、目标和验收标准;PR 记录实际修改、测试结果和风险。
  • 动手前先读仓库规则、主分支和调用链,在独立分支或 worktree 里改。审查时看需求有没有覆盖全、边界有没有考虑、证据是否充分。
  • 自我审查不能只在本次 PR 打一次勾。反复发现的漏项可以转成提交前检查项,但检查表要跟项目更新。
  • 有效的二次检查包括:用户强调的限制是否还在、改过的文件有没有回读、测试证据是否对应提交的版本、索引和链接和状态是否同步、已知风险是否记录。

先查再撤的最短命令索引(待复习):git status --short --branch 查工作树和分支;git diff 看未暂存差异,git diff --cached 看本次待提交内容;git log --oneline -10 与 git show <commit> 查历史。撤销暂存和丢弃正文是不同动作,已共享提交通常用新反向提交恢复。旧速查里“没 push 可以随便 reset”“reflog 一定能救回”的说法不能照搬,未提交内容仍需先保全。Git历史速查。

有依赖的 PR

  • 有依赖的 PR:子 PR 可基于父 PR 分支,独立功能从最新主分支开始。父 PR 更新、改写历史或以 Squash 合并后,要核对每层的新基础提交、祖先关系和独立 diff,可用 range-diff 比较,或受控地用 rebase --onto 重放子分支提交再重新验证。
  • 显示“可合并”和旧的 CI 结果,都不能证明子分支已经在新的父版本上验证过。
  • --force-with-lease 比直接强推安全,但仍会改写远端历史,只在获得授权的个人分支上用,主干不强推。
  • 待补:父 PR Squash 合并后怎样保持子 PR 的 diff 干净,要按真实的 Git 历史判断是否需要重建提交。

秘密与 .gitignore

  • 在公开源码里发现硬编码密钥,不能因为“公开能看到”就拿去调用验证。应通过拥有者或平台的安全披露渠道报告,由有权限的人核对暴露范围、撤销或轮换、清理历史并审计使用记录。秘密只要在 Git 历史里出现过,删掉当前代码也不等于风险消失。
  • .gitignore 不影响已经被跟踪的文件和历史。停止跟踪、清理当前提交、处理远端历史是三件事,要分别核对,并且不能误伤无关改动。

交付状态

  • 任务收尾要说明改动所在分支、对应 PR、已完成的验证,以及是否还等合并或冲突处理。未合并的改动要有可回查的归宿,不能只报“完成”,也不能为凑完成状态擅自合并或删除。
  • 封存记录说收尾规则已经写进正式规范,不等于所有历史分支都已经逐一核验过。

Worktree 软链接、规范落地和交接模板的具体故障,案例见附录 A.8.1、A.8.2、A.8.3。

来源

旧库 90-归档/20-个人/20-草稿箱/AI规范优化收件箱-已归档.md 第 3241—3246 行的用户原话;AI规范优化收件箱-20260923-最终封存.md 第 9—10 行的后续处理记录。

确认 Agent 和构建跑在正确的仓库(待学习)

外部任务入口成功触发后,先核对实际挂载的仓库、分支和工作目录。某次入口能回消息,但挂的仍是另一仓库。环境面板与触发入口是否消费同一份配置,需要用实际任务确认。

复用依赖前核对当前工作区的锁文件与构建根目录。曾有 worktree 通过依赖软链接跑过类型和单测,构建器却拒绝根目录外的链接。改在该 worktree 按锁文件安装后构建通过。三种验证结果分别记录。

外部触发实际仓库 · Worktree 依赖对照

复用时仍需核对的边界(待学习)

触发入口还要分清新版 Cloud 与 Legacy:面板发布成功,不证明集成入口消费了这份配置。2026-11-04 的排查中,Linear 仍走 Legacy;旧环境具体绑定尚未核实,不能用新版设置替它作证。

8.6 安全重构的接口兼容

先保留已有接口行为,再逐步迁移调用方。

我踩过的坑

  • 以为改完上游输出就算完成,没想到旧的下游可能解析失败,或者悄悄走进默认业务分支。

正确理解

  • 拆分大的 types 文件时,先让 index.ts 继续 re-export 原有类型,验证没问题后再逐步迁移旧的 import。
  • 图片对象有 source_url(原图)和 archive_url(归档图)两个地址。归档图曾短时间不可读,导致多模态调用返回 400。当时的做法是默认仍然“归档优先”,只让这一处多模态调用显式改成“原图优先”,并实测原图可用。
  • preferred_url 从属性改成 preferred_url(priority=...) 方法后,旧调用处要补上括号,并测试“地址缺失”和“优先级”组合出的四种情况。
  • 新字段的契约还没确认时,先保持旧行为,新路由默认关闭。某个环境里 1,382 个单测通过,不等于灰度已经验收。
  • 跨服务新增字段的一种发布顺序:先让消费者同时接受旧数据缺字段和新数据带字段,再让生产者逐步输出新字段,真实语义启用前保留默认关闭的开关。例如旧事件只有 name,新事件增加 display_name,兼容窗口内不能因升级生产者就停发旧消费者需要的字段。
  • 消费者要测试新旧版本混跑、消息重放和迟到任务。破坏性变更按“扩展—迁移—收缩”推进,必要时双读或短期双写,并准备版本指标和回退计划。
  • 回滚前先查哪些消费者已经用了新字段、数据有没有落库。代码回退不会撤销已经产生的副作用,见第 6.9 节。
  • 删除“已停用的服务”也要沿依赖层逐层检查。旧的翻译或摘要入口可能已经停用,但内部的解析、翻译实现仍被其他业务调用,Embedding 生成层也可能还在给图片搜索用。
  • 先分清对外接口层、共享实现层、生成与存储层,搜出真实调用方和动态注册的入口,验证迁移后的功能正常,再分阶段删除。
  • 批量处理的规则可以共享,但每个输入的期望、实际结果、评分、错误和证据要分开保存;预览和真实请求要用同一份结果。
来源

旧 Wiki 10-wiki/personal/wiki/concepts/发布顺序(消费者优先).md 和历史 2026-07-26 代码链路草稿。旧例子未重新验证今天的分布式服务版本。

字段不再使用,不等于现在就能删(待学习)。旧提问是“后端已经不用一个请求字段了,为什么不能直接删掉?”调用方可能依赖字段生成类型或做表单校验。先保持名称、类型和默认值,在接口文档标 deprecated,并说明不再影响业务;核对所有调用方不再依赖后再删除。标废弃本身不等于运行时拒收旧请求。

来源:后端-Python与接口实践。

批量路径替换要覆盖测试和动态加载(历史踩坑)。原记录提醒:只匹配 from 会漏掉 lazy(() => import(...)) 与 vi.mock(...)。迁移后要核对业务 import 与 mock 指向同一模块,否则测试可能误用真实 API;搜索旧路径时也要查这两类调用。

来源:工具-开发工作流。

8.7 TDD 的纵向切片

一次只推进一个可验证的用户行为,而不是先写一堆测试再写一堆实现。

2026-09 的 bigpowers 第三方 develop-tdd Skill 提供了一个反面例子:先批量写 10 个互不对应的测试,再一次写完 10 段实现,表面上走过 Red/Green,但失败时很难判断哪项业务需求真的被落实。

正确理解

  • TDD 以一个可验证的行为为单位:先写一个失败的测试,再写最小实现,重跑通过后走一遍真实用户路径,然后才进入下一块。
  • 测试关注输入、输出、数据库和 UI 这些外部契约;权限、异步取消和视觉布局,还需要集成测试或页面上的证据。
  • 第三方 Skill 里“只在特性分支工作、禁止动 main”的规定,不是本仓库的授权规则。借鉴它的测试方法即可,不照搬它的目录和角色限制。
来源

旧第三方源码快照 20-个人/20-调研报告/bigpowers-技能源码/develop-tdd/SKILL.md 和 REFERENCE.md,原项目仓库 bigpowers。不代表本人仓库已接入该 Skill。

本章原始笔记

《CI/CD》 · 《Issue 与 PR》

8.8 隔离工作树,也要隔离依赖与验证组合(待学习)

worktree 只隔离文件。按当前锁文件建立环境,核对解释器和 Shell;无关 SDK 类型错或 Bash 空数组差异,先在未改基线复现。绝对软链接在本机可用,也可能让干净克隆或构建器失败;类型、单测与构建分别验。

多个 PR 同改一函数,文本合并成功不代表导入、单位和阈值仍兼容。保留各自分支,临时组合跑双方回归;只能证明该组合,不冒充最终合并或线上验收。

来源与当时边界

原始记录 2026-10-29 · 原始记录 2026-10-30 · 原始记录 多个 PR 修改同一

8.9 异步测试等可观察结果,不猜 flush 次数(待学习)

固定一次 flush 不证明真实异步读取和状态提交结束,长 setTimeout 也不能说明正确。按行数、saved、轮询选择等条件等待;账号切换等旧请求结束再做负断言。立即反馈仍立即测,不能全部延后。30 个负载下独立进程通过只提供稳定性证据,不保证永不波动。

来源与当时边界

原始记录 2026-11-01

8.10 安装命令按原样执行,再验真实 MCP 协议(待学习)

Git 安装不带分支会落默认分支,包还在功能分支时,配置语法正确也启动不了;基础 CLI 装好也不代表可选 MCP SDK 已装。干净环境按原命令执行,再用 stdio 客户端 list_tools 和一次调用,分别记录安装、启动、协议和 GUI。预览分支已跑通协议,默认命令失败、三个 GUI 未测,盲选偏好或文档分数不能抹掉这些条件。

来源与当时边界

原始记录 复制 MCP 启动命