发布后发现“订单金额恰好达到一百元时没有优惠”,但上一个版本正常。直接从最新提交往回翻,容易把相关重构当成原因。更有效的办法是固定业务输入和预期,让 Git 在已知好、坏版本之间自动选择待测提交。

本文用九个本地提交演示完整流程。第七个提交把 >= 改为 >,后续版本继续保留缺陷。这是构造的实验历史,不是生产事故。核心交付物是可重复的判定器、准确的提交边界和可复查的二分日志。

先定义什么叫坏

金额单位固定为分;输入 9999、10000、10001,优惠资格应为 False、True、True。只检查大于门槛的输入,会让错误实现也通过。实验中的目标模块 pricing.py 如下:

"""优惠资格演示,金额以分为单位。"""
def can_discount(amount: int) -> bool:
    """判断是否满足满一百元优惠条件。"""
    return amount >= 10000

此函数只服务于受控实验,不是完整的金额输入校验接口。实际业务必须另做服务端类型、非负范围和权限校验。

自动判定器需要放在被二分仓库之外,否则历史切换可能把新测试一起移除。保存为 check_regression.py:

"""为固定业务契约提供二分判定,不能判定时停止或跳过。"""

import sys
from pathlib import Path

source = Path("pricing.py")
if not source.is_file():
    print("当前版本没有目标模块,跳过")
    sys.exit(125)
try:
    module = {}
    exec(compile(source.read_bytes(), str(source), "exec"), module)
    evaluate = module["can_discount"]
    actual = [evaluate(value) for value in (9999, 10000, 10001)]
except OSError, SyntaxError, KeyError, TypeError, NameError, ValueError:
    print("判定环境或模块接口异常,中止二分")
    sys.exit(128)
if actual != [False, True, True]:
    print("满一百元优惠契约不成立")
    sys.exit(1)
print("业务契约通过")
sys.exit(0)

判定器直接编译当前文件字节,避免历史切换与字节码缓存影响这个单文件实验。这里只执行自己信任的代码;exec 不是隔离沙箱,不能用它运行不可信仓库。

退出码是二分协议的一部分:0 表示通过,1 表示目标业务契约失败,125 表示这个版本无法测试,128 表示应中止。Git 把 1—127 中除 125 外的代码都当作坏版本,因此普通运行错误很容易污染结果。上述规则依据 Git bisect 官方文档。

这里将“没有 pricing.py”约定为旧版本尚无模块;若实际故障正是误删模块,就应把缺文件判为坏,不能跳过。示例将常见接口和语法错误转为128;迁移到实际项目时,应在执行边界把其他非业务异常同样映射为中止,并单独保留脱敏诊断,不能直接把整个测试进程的所有非零码映射成业务失败。

完整实验:创建历史、检查端点、执行二分

准备 Git、Python 3.14 或更新版本,无需第三方依赖。将下面文件保存为与判定器同目录的 run_lab.py。它仅在自身目录下新建临时仓库,配置实验身份,不更改全局 Git 设置、不推送、不接触现有项目历史。临时仓库结束后自动清理。

"""创建隔离历史并验证二分结果,所有命令只作用于新建实验目录。"""

import subprocess
import sys
import tempfile
from pathlib import Path

ROOT = Path(__file__).resolve().parent
CHECKER = ROOT / "check_regression.py"


def run(args: list[str], cwd: Path, expected: int = 0) -> str:
    """以字节捕获命令结果,并检查明确约定的退出码。"""
    result = subprocess.run(args, cwd=cwd, capture_output=True, timeout=60)
    if result.returncode != expected:
        raise RuntimeError(
            f"命令执行失败: command={args[0]}, return_code={result.returncode}, expected={expected}"
        )
    if args[:3] == ["git", "bisect", "run"]:
        print(result.stderr.decode("utf-8", errors="replace"))
    return result.stdout.decode("utf-8", errors="strict").strip()


def main() -> None:
    """验证正常边界、失败判定、跳过及首个坏提交。"""
    with tempfile.TemporaryDirectory(prefix="history-", dir=ROOT) as directory:
        repo = Path(directory)
        run(["git", "init", "-q"], repo)
        run(["git", "config", "user.name", "Bisect Lab"], repo)
        run(["git", "config", "user.email", "lab@example.invalid"], repo)
        source = repo / "pricing.py"
        commits = []
        for index in range(9):
            operator = ">=" if index < 6 else ">"
            source.write_text(
                f'"""优惠资格演示,金额以分为单位。"""\n'
                f"def can_discount(amount: int) -> bool:\n"
                f'    """判断是否满足满一百元优惠条件。"""\n'
                f"    return amount {operator} 10000\n"
                f"# 实验版本:{index}\n",
                encoding="utf-8",
            )
            run(["git", "add", "pricing.py"], repo)
            run(["git", "-c", "commit.gpgsign=false", "commit", "-qm", f"实验版本 {index}"], repo)
            commits.append(run(["git", "rev-parse", "HEAD"], repo))
        run([sys.executable, str(CHECKER)], repo, 1)
        source.unlink()
        run([sys.executable, str(CHECKER)], repo, 125)
        source.write_text("def invalid(\n", encoding="utf-8")
        run([sys.executable, str(CHECKER)], repo, 128)
        run(["git", "restore", "pricing.py"], repo)
        run(["git", "checkout", "-q", commits[0]], repo)
        run([sys.executable, str(CHECKER)], repo)
        run(["git", "checkout", "-q", commits[-1]], repo)
        try:
            run(["git", "bisect", "start", commits[-1], commits[0]], repo)
            print(
                run(
                    ["git", "bisect", "run", Path(sys.executable).as_posix(), CHECKER.as_posix()],
                    repo,
                )
            )
            found = run(["git", "rev-parse", "refs/bisect/bad"], repo)
            if found != commits[6]:
                raise AssertionError(f"首个坏提交定位不符: {found}, {commits[6]}")
            print("九提交历史:正确定位第七个提交")
            print("判定器退出码:正常0、回归1、缺模块125、语法异常128")
            print(run(["git", "bisect", "log"], repo))
        finally:
            run(["git", "bisect", "reset"], repo)
        mutant = ROOT / "always_good.py"
        mutant.write_text("raise SystemExit(0)\n", encoding="utf-8")
        try:
            result = subprocess.run(
                [sys.executable, str(mutant)], cwd=repo, capture_output=True, timeout=10
            )
            if result.returncode == 1:
                raise AssertionError("变异判定器不应检出回归")
            if result.returncode != 0:
                raise AssertionError("变异运行异常")
            print("恒通过变异:坏端点预检发现返回0,拒绝使用该判定器")
        finally:
            mutant.unlink()


if __name__ == "__main__":
    main()

在 PowerShell 中执行(python 应指向已准备好的解释器):

$env:PYTHONIOENCODING = 'utf-8'
python .\run_lab.py

PYTHONIOENCODING 明确了本实验 Python 子进程的中文输出编码,外部命令仍以字节捕获后解码。运行器对命令设置超时并检查退出码;Git 输出按本次验证环境的 UTF-8 约定处理。若部署环境明确使用其他编码,需要在对应命令适配边界配置,不能用忽略解码错误掩盖问题。

验收不能只看 bisect found first bad commit:还要看到独立断言确认“第七个提交”,且其父提交通过、该提交失败。实验会先检查好端点0、坏端点1,再测试缺模块125和语法错误128。随后自动二分,并把 refs/bisect/bad 与构造历史中预先记录的第七个提交比较。

最后故意创建一个永远返回0的判定器。它在坏端点也通过,因此必须拒绝用于二分。这个检查证明端点预检能够发现漏测,不能以“命令运行成功”代替测试有效。

迁移到实际项目

先用独立克隆或专用工作树保留排查现场,记录当前分支与干净状态。不要在带有未保存修改的工作区中直接开始二分。选择真实确认过的好版本与坏版本,用同一判定器、同一脱敏输入分别验证,两端必须稳定产生相反结果。

进入专用仓库后,按顺序执行 git bisect start <坏提交> <好提交>、git bisect run <解释器绝对路径> <仓库外判定器绝对路径>。Windows 参数建议使用正斜杠且单独传参;不要把业务输入拼接进 shell 字符串。通过 git bisect log 保存选择过程,结束时执行 git bisect reset 返回开始位置。重放可使用 git bisect replay <日志文件>,相关行为见同一份官方文档。

编译类项目需要每个候选版本重建制品,不能复用上一次构建产物。缓存键至少包含源代码版本、工具链和关键构建选项。测试超时、依赖不可达、权限拒绝都应进入环境失败路径;若只是某个历史版本确实无法构建,可按预先约定返回125。跳过首个坏提交附近的版本可能只能得到候选集合,此时不能宣称已经唯一定位。

一次二分只追踪一个稳定谓词。如果回归出现、修复后再次出现,或测试依赖当前日期、远程数据和随机调度,结果不一定代表最早一次故障。先固定依赖与数据、重复验证端点;必要时缩小区间。对于合并历史,还需判断目标是具体引入改动还是主线集成节点,再决定是否采用 first-parent 策略,不能把线性实验直接外推。

本次实测结果与边界

在 Windows、Git 2.54.0 与当前项目 Python 环境下,实际创建了九提交历史,自动二分正确定位第七个提交。0/1/125/128四条判定路径、恒通过变异拒绝均通过。完整代码经过 Ruff 格式与静态检查。

首次在受限沙箱中运行时,Git for Windows 的 sh.exe 创建 MSYS 命名对象遭拒,错误码仍被二分当作坏版本,最终定位错误;独立提交断言发现了问题。获准在沙箱外重跑后,实际业务判定输出出现且提交断言通过。这是执行环境失败,不是业务回归。实际排查必须同时查看测试输出和标准错误,不能只信二分工具的结论。

没有验证远程仓库、CI权限、真实编译链、合并图、子模块、Git LFS 或大项目耗时;125在本次只验证了判定器出口,没有演练连续跳过后的歧义集合。临时仓库会清理,生产排查应把日志保存到仓库外受控位置再清理工作树。定位提交只提供因果排查入口,修复后仍需补充项目回归测试与发布验收。