质量内建:TDD、重构与代码评审
本篇要点:把「做对了没有」变成写代码时就能回答的问题,并用一套十分钟内跑得完的自动检查把答案锁住。 前置文章:[《估算与预测:故事点与蒙特卡洛》](/guide/agile/estimation-forecasting.html)用历史速度算出了分位数;这套预测有个沉默的前提——「完成」是真的完成,这一章处理那个前提。
一、为什么需要它
2026 年 2 月,一家支付服务商上线「对账单导出」。三天内收到 41 个工单,17 个是同一类问题:金额显示成 1000.0 而不是 1,000.00,导进 Excel 还成了文本格式。修复花了两天,顺带发现另外三个模块有同样的格式化代码。
复盘时把产能摊开看:40% 花在上个迭代遗留的缺陷上,回归靠三个人手工点两天,OrderService.java 已经 1 100 行,改一处折扣计算要读六个文件才能确认没有别处依赖。团队不缺人,缺的是把缺陷挡在编码阶段的手段。
缺陷不是测试阶段产生的,测试阶段只是发现它的地方。同一处缺陷,需求澄清时改一句话,编码时改一个函数,上线后要动代码、补数据、回客服、写复盘,成本差着两三个数量级。
质量内建(built-in quality)说的是把发现缺陷的动作前移,挪到写代码的那一刻,而不是在最后加一道更严的验收。做法有四层:测试驱动开发(TDD,test-driven development)让「做对没有」可执行,重构让结构不腐化,评审在合并前拦一道,台账和门禁让这些事长期维持。
二、核心概念
6.1 测试金字塔与 TDD 的三拍
测试金字塔(test pyramid,Mike Cohn 提出)讲配比:底层大量单元测试,中层少量集成测试,顶层极少端到端测试。反过来是冰淇淋筒(ice cream cone):几十个端到端用例跑四十分钟,改个按钮文案就红一片,团队最后学会的事是忽略红色。
TDD 的节奏是三拍:
- 红:先写一个会失败的测试,失败原因必须是「功能没实现」,不是「语法写错」。
- 绿:用最少的代码让它通过,允许丑陋,不允许顺手加需求。
- 重构:在测试全绿的保护下改结构,改完再跑一遍。
三拍里最容易被跳过的是第三拍,而它决定这套实践是保护网还是枷锁。只写测试不重构,代码会长成「刚好通过测试」的形状:为断言方便存在的中间变量、一个方法五个分支。
类比:TDD 像先写验收单再施工。验收单写得具体,施工时才知道哪里不能含糊;写成 assert result is not None,施工就是走过场。
6.2 重构:每天几十分钟的事
重构(refactoring)是在不改变外部行为的前提下调整内部结构。两个前提缺一不可:一张跑得快的测试网,以及小步提交。
它和重写(rewrite)不是一回事。重写是几个月的赌注,重构是每天几十分钟的习惯。重写的诱惑在于「旧代码太烂」,风险在于旧代码里的业务规则没人完整知道——它们藏在边界判断里,重写时最容易被「顺手简化」掉,而简化掉的部分往往就是当年出过事故的地方。
触发信号可以量化:一个方法超过 40 行;一个类被五个以上地方 import;改一个功能要动三个以上文件;一个函数参数超过四个。出现任意一条,下次改到这里时顺手处理。这就是童子军规则(Boy Scout Rule):离开时比来时干净一点。
反例是把重构攒成「重构迭代」。攒三个月再重构,等于把小额多期贷款改成到期一次还本,利息更高,而且那次迭代通常第一个被业务需求挤掉。
6.3 代码评审:看什么,看多大
代码评审(code review)的价值是拦住「作者自己看不出来」的问题,不是挑格式。空格、引号、换行交给 linter,人只看四件事,按优先级:正确性与边界、测试是否覆盖新逻辑、可读性、性能与安全。
规模有硬约束:单次改动(PR,pull request)控制在 400 行以内。对商业代码评审的研究建议是 200 到 400 行,超过这个量级缺陷发现率明显下降——读到第 600 行时人在扫,不在读。改动大就拆成几个 PR 顺序提交,每个讲一个能理解的小故事。
时限也要定:24 小时内给首轮回复。卡三天,作者上下文凉了,最后往往是「算了,先合吧」。
评论分级能省掉大量来回。给每条加前缀:blocking: 必须改才能合;suggestion: 建议但不强求;nit: 吹毛求疵,可以不改;question: 提问,可能引出讨论。没有前缀,作者不知道哪条能商量,只能全改或全不改。
表 6-1 是一份可以直接抄进仓库的评审清单。
| 检查项 | 通过标准 | 常见不合格 |
|---|---|---|
| 正确性 | 边界值、空值、并发行为都有明确处理 | 只有主流程,null 直接解引用 |
| 测试 | 新增逻辑有测试,断言能说明问题 | 只测 happy path,断言写 is not None |
| 可读性 | 命名读出意图,函数不超过 40 行 | data、tmp、process2 |
| 错误处理 | 异常有分类,日志带上下文 | catch (Exception e) {} 吞掉 |
| 安全 | 外部输入校验,SQL 参数化,无硬编码密钥 | 字符串拼接 SQL |
6.4 技术债台账:算利息,不算总账
技术债(technical debt)是 Ward Cunningham 在 1992 年用的比喻:借债换速度,利息是之后每次改动的额外成本。它把「代码烂」这种模糊感受换成了两个可比的量——利息和偿还成本。
台账不用记全,记五个字段就够:位置、症状、利息、偿还成本、触发条件。表 6-2 是一份真实的样例。
| 位置 | 症状 | 利息 | 偿还成本 | 触发条件 |
|---|---|---|---|---|
| order/PriceCalculator | 折扣规则堆了 14 个 if-else | 每次加活动多 1 天 | 3 天 | 分支数超过 15 |
| order/api | 金额格式化在 5 处重复 | 每个格式问题改 5 次 | 0.5 天 | 下次出现格式工单 |
| web/checkout | 结算页组件 900 行无测试 | 改动靠手工回归 2 天 | 4 天 | 下个迭代要改结算页 |
利息这一列是关键。没有利息的债不是债,是偏好——某模块命名不合规范,只要没人改它,利息就是零。台账只留利息大于零的条目,否则清单会膨胀到没人看。
偿还节奏用固定配比,不用专门迭代:每迭代留 15% 到 20% 的产能,选利息最高的两条。好处是可持续,坏处是慢。如果某个模块的利息已高到每张卡都受影响,就该集中处理一次,前提是写进迭代目标,而不是偷偷做。
6.5 质量门禁:卡在合并前,不卡在发布前
质量门禁(quality gate)是合并或发布前必须通过的自动检查。最低四条:单元测试全绿;新增代码覆盖率不低于阈值(比如 70%);静态扫描无新增严重问题;产物能启动并通过冒烟(smoke)检查。
门禁有两个约束。一是快,整条控制在 10 分钟以内,超时就会有人绕过。二是可绕过但留痕:允许紧急合入,代价是自动建一张债卡并通知负责人。没有出口的严格,最后都成了集体绕过。
把 TDD 的循环和门禁放进同一条流里,位置关系就清楚了。
图 6-1 红绿重构循环与合并前的质量门禁
如图 6-1 所示,门禁后面有一条回到起点的虚线:每周统计逃到线上的缺陷,每类补一条能复现它的测试。没有这条回路,门禁只是把问题推给下一个模块。
三、动手实践
环境为 Python 3.11、pytest 8、GitHub Actions。用《需求拆解:用户故事与验收标准》那条验收标准做例子:购物车 100.00 元,先满减 20 再打 9 折,应付 72.00 元。
步骤一:先写一个会失败的测试
# tests/test_discount.py
import pytest
from checkout.discount import final_price
def test_stack_coupon_then_percent():
# 100.00 先减 20,再打 9 折
assert final_price(cents=10000, off=2000, percent=0.9, threshold=10000) == 7200
@pytest.mark.parametrize("cents,expected", [(9999, None), (10000, 8000)])
def test_threshold_is_inclusive(cents, expected):
# 门槛判断用 >=,差一分钱不通过
assert final_price(cents=cents, off=2000, percent=1.0, threshold=10000) == expected运行结果:
$ pytest -q
E ModuleNotFoundError: No module named 'checkout.discount'
1 error in 0.31s这个失败是对的:模块还不存在。红的第一层意义是证明测试真会跑,第二层是证明它测的东西还不存在。第一次跑就绿,说明测试没测到东西,那是最危险的一种通过。
步骤二:用最少的代码变绿
# checkout/discount.py
def final_price(cents: int, off: int, percent: float, threshold: int = 0) -> int:
if cents < threshold:
return None
return round((cents - off) * percent)运行结果:
$ pytest -q
... [100%]
3 passed in 0.02s绿了之后先别急着加功能。round 的默认行为是银行家舍入(banker's rounding),round(72.5) 得到 72 而不是 73。金额场景里这会差一分钱,通常要显式指定 ROUND_HALF_UP。这类细节不会出现在设计文档里,只会出现在测试里——这是 TDD 的副产品:它逼你把规则想到位。
步骤三:把质量门禁配进 CI
# .github/workflows/quality-gate.yml
name: quality-gate
on: [pull_request]
concurrency:
group: qg-${{ github.ref }}
cancel-in-progress: true
jobs:
gate:
runs-on: ubuntu-latest
timeout-minutes: 12
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-python@v5
with: { python-version: "3.11" }
- run: pip install -r requirements-dev.txt
- name: unit tests + coverage
run: pytest -q --cov=checkout --cov-report=xml --cov-fail-under=70
- name: lint
run: ruff check --output-format=github .
- name: 改动行数
run: |
base="origin/${{ github.base_ref }}"
changed=$(git diff --numstat "$base"...HEAD | awk '{s+=$1+$2} END {print s+0}')
echo "changed lines: $changed"
[ "$changed" -le 400 ] || echo "::warning::改动 $changed 行,建议拆分"
- name: smoke
run: python -c "from checkout.discount import final_price; assert final_price(10000,2000,0.9,10000)==7200"预期输出:PR 页面底部出现 quality-gate / gate,耗时约 90 秒。覆盖率不足 70 时该检查失败,报 FAIL Required test coverage of 70% not reached;改动超过 400 行只出黄色警告不阻断。这条刻意不阻断,因为行数不是质量指标,用红灯逼出来的通常是「把改动拆成两个空提交」。
步骤四:每周算一次缺陷逃逸率
-- 缺陷逃逸率:上线后发现的 / 全部发现的
SELECT date_trunc('week', created_at) AS week,
COUNT(*) FILTER (WHERE found_in = 'production') AS escaped,
COUNT(*) AS total,
ROUND(100.0 * COUNT(*) FILTER (WHERE found_in = 'production')
/ COUNT(*), 1) AS escape_rate_pct
FROM defects
WHERE created_at >= now() - interval '8 weeks'
GROUP BY 1
ORDER BY 1 DESC;运行结果:
week | escaped | total | escape_rate_pct
2026-11-09 | 3 | 41 | 7.3
2026-11-02 | 6 | 38 | 15.8
2026-10-26 | 5 | 35 | 14.37.3% 到 15.8% 先别看趋势,先看分母:那个 41 是不是一次大版本上线集中报的工单。逃逸率单向下降才算改进,波动本身不是证据。
四、常见误解
很多人以为 TDD 就是「先写测试再写代码」的顺序规定。顺序只是外壳,决定成败的是第三步重构:只写测试不重构,代码会变成测试的镜像,测试越全结构越僵。判断方法很直接——翻提交历史,看有没有「只改结构、不改测试」的提交。
很多人以为覆盖率 80% 就代表质量好。覆盖率只说明这些行被执行过,不说明断言有效,assert result is not None 也能刷数字。要看两个更硬的指标:新增代码覆盖率(只统计本次改动),以及变异测试(mutation testing)的杀死率——故意改坏一行,测试能不能发现。
很多人以为技术债要靠一次「重构迭代」还清。债务持续产生,还完照样会欠。固定配比加触发条件更现实;也不是所有债都该还,利息为零的债去还它只是自我安慰。先算利息,再排优先级。
五、小结
[《估算与预测:故事点与蒙特卡洛》](/guide/agile/estimation-forecasting.html)的预测以「完成」可信为前提,这一章让「完成」有内容。
- 缺陷在编码时产生,在测试时被发现。前移发现动作,成本降一个数量级;最后加严验收,只是把成本推给运维和客服。
- TDD 三拍里红和绿容易被看见,重构最容易被跳过。跳过它,测试就从保护网变成枷锁。
- 重构每天几十分钟,重写是几个月的赌注。触发信号量化到行数、import 数、文件数。
- 评审看四件事,单次不超 400 行,24 小时内回复,评论带 blocking / nit 等前缀。
- 技术债台账记利息不记总账;门禁要快、可绕过但留痕,每周回看逃逸缺陷并补测试。
六、相关文章
这一章的做法都指向同一个方向:让「完成」有分量。一旦完成可信,下一个问题就冒出来——既然每个迭代末都有可交付的增量,为什么还要攒到季度末才发一次?[《交付一体化:迭代节奏与发布节奏解耦》](/guide/agile/devops-agile-integration.html)讲交付一体化:把迭代节奏和发布节奏拆开,用特性开关(Feature Flag)让没做完的功能安全地待在主干上,用小批量发布压低每次上线的风险。
继续阅读:[《交付一体化:迭代节奏与发布节奏解耦》 交付一体化:迭代节奏与发布节奏解耦](/guide/agile/devops-agile-integration.html)