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 仓库中 BRBackup 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。构建 BRmake 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_ENABLED1 $(GOBUILD) $(RACE_FLAG) -ldflags $(LDFLAGS) $(CHECK_FLAG) -o $(BR_BIN) ./br/cmd/br else echo Detected non-macOS ($(ARCH)), disabling CGO CGO_ENABLED0 $(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 策略macOSdarwin平台开启CGO_ENABLED1其他平台关闭 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_testMakefile 中该目标的实际实现是.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 TZAsia/Shanghai; $(GOTEST) --tagsdeadlock,intest $(RACE_FLAG) -ldflags $(LDFLAGS) $(ARGS) -coverprofilecoverage.txt || ( make failpoint-disable exit 1 ) make failpoint-disable几个值得注意的实现事实测试范围由BR_PACKAGES决定定义在 Makefile.commongo list ./...| grep github.com/pingcap/tidb/br即所有 BR 相关包failpoint 机制构建会先执行failpoint-enable注入故障点桩代码测试结束后执行failpoint-disable还原失败分支会确保 failpoint 被关闭构建标签与覆盖率以--tagsdeadlock,intest编译并将覆盖率写入coverage.txt时区固定为Asia/Shanghai保证依赖时间断言的测试行为一致。运行单个测试时把包路径与额外测试参数传给ARGSmake br_unit_test ARGSgithub.com/pingcap/tidb/br/pkg/cdclog --test.v --check.v --check.f TestColumn也可以绕过 make 直接调用go test但需要手动切换 failpointmake 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见 Makefiledev目标则是包含多项检查的完整开发工作流。集成测试集成测试依赖外部进程TiDB/TiKV/PD 等按 br/tests/README.md 的要求需要准备九个可执行文件放入 TiDB 根目录的bin/版本要求 ≥ 2.1.0bin/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_NAMEtest_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 将全部集成测试拆分为G00G08 共九个分组并行执行每组尽量装满以压缩 CI 等待时间脚本会扫描tests/*/run.sh发现任何未被分组的用例others会直接报错退出从而强制新用例必须入组。分组内所有用例还统一开启ENABLE_ENCRYPTIONtrue。新增一个集成测试的正确姿势摘自 br/tests/README.md在tests/TEST_NAME/run.sh编写 shell 脚本失败时必须以非零错误码退出将TEST_NAME追加到 br/tests/run_group_br_tests.sh 中已有的分组推荐或新建分组新分组名需同步登记到 CI 流水线脚本内可使用仓库提供的便捷命令run_sql SQL— 在 TiDB 上执行 SQLrun_br— 以必要配置执行br.testrun_lightning [CONFIG]— 用tests/TEST_NAME/CONFIG.toml启动tidb-lightningcheck_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 RequestPR 必须获得两位维护者的 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 等路径下可作为后续深入阅读的入口。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考