TiDB BR 构建与测试实战：从源码构建 br 到提交规范的完整贡献指南-迪斯科星球

TiDB BR 构建与测试实战：从源码构建 br 到提交规范的完整贡献指南

【免费下载链接】tidbTiDB is built for agentic workloads that grow unpredictably, with ACID guarantees and native support for transactions, analytics, and vector search. No data silos. No noisy neighbors. No infrastructure ceiling.项目地址: https://gitcode.com/GitHub_Trending/ti/tidb

本文基于 TiDB 仓库中 BR（Backup & Restore，分布式备份与恢复工具）的贡献指南 br/CONTRIBUTING.md 展开，完整覆盖 BR 的环境要求、make build_br构建流程、单元测试与集成测试的执行方法，以及提交信息规范等贡献者必须遵循的约定。读完本文，你可以从零开始构建出bin/br二进制、运行 BR 的全部测试并生成覆盖率报告，并按仓库约定格式提交一个可被合并的补丁。

构建环境要求

根据 br/CONTRIBUTING.md，开发 BR 需要：

Go 1.23+（文档原文要求）；以当前仓库实际状态为准，go.mod 中声明的版本为go 1.25.12，因此实际构建时建议使用不低于该声明的 Go 版本；
可访问网络，用于下载 Go module 依赖。

BR 是 TiDB 生态的命令行备份恢复工具，入口位于 br/cmd/br/main.go，构建、测试与兼容矩阵的更多背景可参考 br/README.md 与 br/COMPATIBILITY_TEST.md。

构建 BR：make build_br

基本步骤

贡献指南给出的构建流程为：

进入 TiDB 仓库根目录（文档中写作cd ../tidb，这是 BR 尚为独立仓库时的历史表述；在当前仓库布局中br/已是 TiDB 仓库的子目录，直接在仓库根目录执行即可）；
执行构建命令：

make build_br

构建成功后，br二进制会出现在tidb/bin目录下（即仓库根目录的bin/br）。

Makefile 中的实际构建逻辑

从源码结构看，build_br目标定义在根目录 Makefile 中，其核心行为是：

.PHONY: build_br build_br: ## Build BR (backup and restore) tool ifeq ($(shell echo $(GOOS) | tr A-Z a-z),darwin) @echo "Detected macOS ($(ARCH)), enabling CGO" CGO_ENABLED=1 $(GOBUILD) $(RACE_FLAG) -ldflags '$(LDFLAGS) $(CHECK_FLAG)' -o $(BR_BIN) ./br/cmd/br else @echo "Detected non-macOS ($(ARCH)), disabling CGO" CGO_ENABLED=0 $(GOBUILD) $(RACE_FLAG) -ldflags '$(LDFLAGS) $(CHECK_FLAG)' -o $(BR_BIN) ./br/cmd/br endif

可以从中确认三个实现细节：

输出路径：产物写入$(BR_BIN)，而BR_BIN := bin/br定义在 Makefile.common，与贡献指南中“you will findbrintidb/bindirectory”的说法一致；
CGO 策略：macOS（darwin）平台开启CGO_ENABLED=1，其他平台关闭 CGO，即同一份代码在两类平台上有不同的编译开关；
构建入口：直接编译./br/cmd/br包，与源码目录结构对应。

此外，Makefile 还提供一个聚合目标build_tools（依赖build_br build_lightning build_lightning-ctl），适合需要同时构建 BR 与 TiDB Lightning 的场景。

运行测试

贡献指南指出：BR 同时包含单元测试和带覆盖率收集的集成测试，详细方法见 br/tests/README.md。以下结合 Makefile 目标补充可操作的细节。

单元测试

单元测试（源码目录中的*_test.go文件）不应依赖任何外部程序（如 TiKV、PD 进程）。在仓库根目录执行：

make br_unit_test

Makefile 中该目标的实际实现是：

.PHONY: br_unit_test br_unit_test: export ARGS=$$($(BR_PACKAGES)) br_unit_test: ## Run BR (backup and restore) unit tests @make failpoint-enable @export TZ='Asia/Shanghai'; $(GOTEST) --tags=deadlock,intest $(RACE_FLAG) -ldflags '$(LDFLAGS)' $(ARGS) -coverprofile=coverage.txt || ( make failpoint-disable && exit 1 ) @make failpoint-disable

几个值得注意的实现事实：

测试范围由BR_PACKAGES决定，定义在 Makefile.common：go list ./...| grep "github.com/pingcap/tidb/br"，即所有 BR 相关包；
failpoint 机制：构建会先执行failpoint-enable注入故障点桩代码，测试结束后执行failpoint-disable还原，失败分支会确保 failpoint 被关闭；
构建标签与覆盖率：以--tags=deadlock,intest编译，并将覆盖率写入coverage.txt；
时区固定为Asia/Shanghai，保证依赖时间断言的测试行为一致。

运行单个测试时，把包路径与额外测试参数传给ARGS：

make br_unit_test ARGS='github.com/pingcap/tidb/br/pkg/cdclog --test.v --check.v --check.f TestColumn'

也可以绕过 make 直接调用go test，但需要手动切换 failpoint：

make failpoint-enable go test github.com/pingcap/tidb/br/pkg/cdclog --test.v --check.v --check.f TestColumn make failpoint-disable

如果希望一次性执行 BR 的单元测试与集成测试，可使用聚合目标test_part_br（定义为br_unit_test br_integration_test，见 Makefile）；dev目标则是包含多项检查的完整开发工作流。

集成测试

集成测试依赖外部进程（TiDB/TiKV/PD 等），按 br/tests/README.md 的要求需要准备：

九个可执行文件放入 TiDB 根目录的bin/（版本要求 ≥ 2.1.0）：bin/tidb-server、bin/tikv-server、bin/pd-server、bin/pd-ctl、bin/go-ycsb、bin/minio、bin/mc、bin/tiflash、bin/cdc；大部分依赖可通过 br/tests/download_integration_test_binaries.sh 安装，再执行make failpoint-enable && make && make failpoint-disable构建 tidb 本体；
系统工具：mysql客户端、curl、openssl、wget、lsof、psmisc；
目录权限：执行测试的用户必须能创建/tmp/backup_restore_test，所有测试产物写入该目录。

若已安装 Docker，可跳过上述手工准备，直接运行 br/tests/up.sh 构建并拉起测试容器：

br/tests/up.sh --pull-images

执行流程为：

构建br.test测试二进制：make build_for_br_integration_test；
确认九个外部可执行文件与br均可用；
通过环境变量选择用例：export TEST_NAME="<test_name1> <test_name2> ..."；
执行br/tests/run.sh。

其中build_for_br_integration_test（见 Makefile）除编译出带覆盖率的$(BR_BIN).test外，还会构建一组集成测试专用辅助二进制：bin/locker、bin/gc、bin/fake-oauth、bin/rawkv、bin/txnkv、bin/utils，分别对应br/tests/br_key_locked、br_z_gc_safepoint、tools/fake-oauth、br/tests/br_rawkv、br/tests/br_txn等测试用例的模拟程序。

补充说明：

br/tests/run.sh会先在后台以本地存储启动 PD、TiKV、TiDB，再运行所有tests/*/run.sh；加--debug参数可在所有服务器启动后暂停，便于排查；
Makefile 中另有br_integration_test（依赖br_bins build_br build_for_br_integration_test后执行cd br && tests/run.sh）与br_integration_test_debug（追加--no-tiflash）两个目标，可直接代替手工流程；
测试结束后执行make br_coverage，覆盖率报告输出到/tmp/backup_restore_test/all_cov.html。

测试分组与新增测试用例

br/tests/run_group_br_tests.sh 将全部集成测试拆分为G00～G08 共九个分组并行执行，每组尽量装满以压缩 CI 等待时间；脚本会扫描tests/*/run.sh，发现任何未被分组的用例（others）会直接报错退出，从而强制新用例必须入组。分组内所有用例还统一开启ENABLE_ENCRYPTION=true。

新增一个集成测试的正确姿势（摘自 br/tests/README.md）：

在tests/TEST_NAME/run.sh编写 shell 脚本，失败时必须以非零错误码退出；
将TEST_NAME追加到 br/tests/run_group_br_tests.sh 中已有的分组（推荐），或新建分组（新分组名需同步登记到 CI 流水线）；
脚本内可使用仓库提供的便捷命令：
- run_sql <SQL>— 在 TiDB 上执行 SQL；
- run_br— 以必要配置执行br.test；
- run_lightning [CONFIG]— 用tests/TEST_NAME/CONFIG.toml启动tidb-lightning；
- check_contains <TEXT>/check_not_contains <TEXT>— 校验上一条run_sql的结果是否包含/不包含指定文本（-E表格格式）。

仓库中已存在大量可参照的用例目录，例如br/tests/br_full、br/tests/br_incremental、br/tests/br_pitr、br/tests/br_s3等，每个目录内含run.sh及按需的*.sql、*.toml数据文件。

更新依赖

BR 使用 Go module 管理依赖。贡献指南给出的做法是：新增或更新依赖时，使用go mod edit命令变更依赖声明。在当前仓库中，BR 与 TiDB 共享同一份根 go.mod，修改依赖后需保证go.sum同步且构建测试通过。

贡献流程与提交规范

标准贡献流程

br/CONTRIBUTING.md 规定的贡献者工作流为：

从作为工作基线的分支（通常是master）创建主题分支；
以逻辑单元组织提交，若变更修复了 bug 或新增了功能，必须附带测试用例；
运行测试并确保全部通过；
确保提交信息符合下述格式；
将变更推送到自己 fork 仓库的主题分支；
提交 Pull Request；
PR 必须获得两位维护者的 LGTM 才能合并。

代码风格

BR 采用 Go 社区推荐的编码风格（即官方 Code Review Comments 中所约定的风格），目的是让 BR 易于评审、维护和二次开发。提交前建议按 Go 工具链惯例格式化代码，并保持与现有 BR 源码一致的命名与注释习惯。

Commit Message 格式

仓库约定提交信息回答两个问题：what changed（改了什么）和 why（为什么改）。主题行承载 what，正文描述 why。规范示例：

restore: add comment for variable declaration Improve documentation.

更正式的模板为：

<subsystem>: <what changed> <BLANK LINE> <why this change was made> <BLANK LINE> <footer>(optional)

格式约束与变体规则：

第一行（主题行）不超过70 个字符；第二行必须为空行；其余行按80 字符换行，保证在 git 工具和代码托管页面上都易读；
变更涉及多个子系统时，用逗号分隔，例如backup,restore:；
变更波及大量子系统时，用*代替，例如*:；
如果没有具体理由，可以使用指南列出的通用表述：Improve documentation.、Improve performance.、Improve robustness.、Improve test coverage.。

小结

BR 的贡献门槛集中在三件事上：能在仓库根目录用make build_br构建出bin/br；能用make br_unit_test和br/tests/run.sh（配合build_for_br_integration_test与br_coverage）跑通单元与集成测试；能按<subsystem>: <what changed>格式撰写提交信息并保证每个行为变更都有测试覆盖。相关实现与脚本均位于 Makefile、br/tests/README.md、br/tests/run_group_br_tests.sh 等路径下，可作为后续深入阅读的入口。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析