gRPC 工程化工具箱全解：深入 tools 目录的构建、测试与发布体系

gRPC 工程化工具箱全解深入 tools 目录的构建、测试与发布体系【免费下载链接】grpcC based gRPC (C, Python, Ruby, Objective-C, PHP, C#)项目地址: https://gitcode.com/GitHub_Trending/gr/grpc导读本指南以 gRPC 仓库的 tools 目录 为核心系统梳理这套支撑 gRPC 全语言C、Python、Ruby、Objective-C、PHP、C# 等日常开发、CI 测试与发布流程的工程化工具链。你将掌握构建文件如何由模板统一生成、单元/互操作/性能测试如何一键运行、跨语言兼容性矩阵如何维护以及 Docker 测试镜像与 Kokoro CI 的协作机制从而能够快速定位问题、复现 CI 行为并参与 gRPC 的测试与发布工作。tools 目录gRPC 的第二套代码库gRPC 是一个多语言、多构建系统Bazel、CMake、Makefile、各语言原生打包的大型项目仅靠src/下的业务代码远不足以支撑其工程化运转。仓库根目录的 tools/README.md 用一份极简索引给出了答案tools目录承载了从模板渲染构建系统、语言包分发、Docker 测试镜像、文档生成、云基础设施脚本到 CI 集成、互操作矩阵与并行测试的全部辅助逻辑。原文档列出的 11 个模块职责如下后文将逐一展开模块职责buildgen构建系统的模板渲染器distrib各语言包分发脚本与分发辅助脚本dockerfile用于测试 gRPC 的 Docker 文件doxygen通过 Doxygen 生成 gRPC C/C 文档gce在 GCE 上搭建测试基础设施的脚本gcp与 GCP 各种服务交互的辅助脚本internal_ci在内部 CI 平台上运行测试的支持interop_matrix构建、上传并以各种语言/运行时组合运行 Docker 中的 gRPC 客户端jenkins在 Jenkins 上运行测试的支持run_tests并行运行 gRPC 测试的脚本run_tests/performance性能测试详见其 README注jenkins在当前的目录结构中已不再存在其职责已被internal_ciKokoro取代这一点在下文有相应说明。构建系统生成buildgen 与 codegenbuildgen一套模板五套构建文件gRPC 同时维护 BazelBUILD、CMakeCMakeLists.txt、Makefile、build_config.rb与package.xml等构建描述若手工同步必然产生漂移。buildgen模块将构建描述统一收敛为两棵 YAML 源build_handwritten.yaml仓库根目录手工维护的元数据build_autogenerated.yaml由 Bazel BUILD 文件自动提取生成。入口脚本 tools/buildgen/generate_projects.sh 的流水线是通过 tools/buildgen/extract_metadata_from_bazel_xml.py 从 Bazel BUILD 文件生成build_autogenerated.yaml运行 tools/buildgen/build_cleaner.py 清理两棵 YAML建立 Python 虚拟环境安装指定版本grpcio-tools生成 xds protos 与 Python 辅助包tools/distrib/python/make_grpcio_tools.py等由 tools/buildgen/generate_projects.py 合并两棵 YAML渲染出所有目标平台的构建文件最后调用 tools/artifact_gen/artifact_gen.sh 生成构件元数据。模板渲染依赖 Mako见 tools/buildgen/_mako_renderer.py并配有plugins/下多个扩展插件如expand_version.py展开版本号、list_protos.py收集 proto 列表、transitive_dependencies.py计算传递依赖。codegen核心代码的代码生成器tools/codegen/ 并非 grpc 协议代码生成器而是为 gRPC C-core 本身生成机械性代码的工具包括core/gen_experiments.py与gen_config_vars.py从 YAML 实验与配置定义生成 C 声明core/gen_stats.py生成统计指标注册代码core/gen_header_frame.py、core/gen_if_list.py、core/gen_join.py等生成各种列表/开关样板core/gen_huffman_decompressor.cc、generate_trace_flags.cc生成 HTTP/2 HPACK Huffman 解码表与 trace 标志core/optimize_arena_pool_sizes.py优化 arena 池大小。测试运行体系run_teststools/run_tests/README.md 说明该目录刻意以 Python 脚本作为测试入口目的是无论你使用什么平台都能用同一命令行运行测试。其核心脚本有四单元测试run_tests.pyrun_tests.py 构建指定语言的 gRPC 并运行单元测试支持并行执行其 docstring 即 Run tests in parallel并借助python_utils/jobset管理任务并发。用法tools/run_tests/run_tests.py -l python -c dbg常用选项还有很多其他选项--use_docker构建一个包含指定语言全部前置依赖的 Docker 容器并在容器内运行测试--build_only只构建、不运行测试。两点注意事项原文档明确给出若报ImportError: No module named httplib2之类错误说明缺少 Python 模块安装报错中列出的模块即可部分测试可能偶发不稳定flaky可到 Issues 页查阅已知问题完整单元测试套件运行耗时较长数十分钟级。互操作测试run_interop_tests.pyrun_interop_tests.py 用于跨平台/跨语言互操作测试测试语义定义见 doc/interop-test-descriptions.md。它还能利用与 grpc 仓库并列检出的 grpc-java、grpc-go 源码运行相应互操作测试。示例tools/run_tests/run_interop_tests.py -l python -s c --use_docker若用 Docker 运行时遇到no space left on device需确保 Docker 镜像构建目录所在磁盘空间充足。性能基准run_performance_tests.py 已弃用run_performance_tests.py已被标记为 deprecated官方推荐改用 gRPC OSS benchmarks 框架详见下文性能基准测试一节本地手动方式仅保留给专家使用。构件与包task_runner.pytask_runner.py 是一个按标签运行预定义任务的通用框架用于构建二进制构件、发行包并测试它们。示例tools/run_tests/task_runner.py -f python artifact linux x64即运行带python、artifact、linux、x64四个标签的构建任务。任务定义在tools/run_tests/generated/下由 buildgen 生成的 JSON 中维护。性能基准测试两种途径tools/run_tests/performance/README.md 提供了两套方案是本目录内信息密度最高的子文档下面完整保留其关键操作。途径一推荐gRPC OSS benchmarks 框架该框架基于 GKE通过 LoadTest 资源YAML 描述 driver、server 与一个或多个 client运行测试每个 LoadTest 只跑一个场景scenario场景配置内嵌在 LoadTest 配置中。相关脚本与 CI 联动脚本为 grpc_e2e_performance_gke.sh 与 grpc_e2e_performance_gke_experiment.sh。导出/统计场景scenario_config_exporter.py 可将场景导出为文件也可统计既有场景。持续集成通常运行scalable类别例如统计该类场景./tools/run_tests/performance/scenario_config_exporter.py --count_scenarios --categoryscalable输出示例部分c 56、python_asyncio 19、java 16、go 12、node 12、csharp 9、dotnet 9、python 7、ruby 5以及若干以 c 作为对端语言client/server的跨语言场景合计 170 个category: scalable。Client/Server 语言仅在跨语言场景中设置。生成 LoadTest 配置loadtest_config.py 从模板生成一组场景的 LoadTest 配置输出为多部分 YAML到文件或 stdout每个配置内嵌一个场景。生成的 LoadTest 名称唯一可用kubectl apply提交到运行 LoadTest controller 的集群执行kubectl apply -f loadtest_config.yaml一个完整的生成示例C# 与 Java含 c 对端、每个测试跑两遍./tools/run_tests/performance/loadtest_config.py -l go -l java \ -t ./tools/run_tests/performance/templates/loadtest_template_basic_all_languages.yaml \ -s client_poolworkers-8core -s driver_pooldrivers \ -s server_poolworkers-8core \ -s big_query_tablee2e_benchmarks.experimental_results \ -s timeout_seconds3600 --categoryscalable \ -d --allow_client_languagec --allow_server_languagec \ --runs_per_test2 -o ./loadtest.yamlloadtest_config.py的核心选项模板为 loadtest_template_basic_all_languages.yaml 等-l/--language待基准的语言可重复-t/--template模板文件可含多个 client/server 配置与替换键-s/--substitutionkeyvalue形式的替换键controller 运行时设置的环境变量DRIVER_PORT、KILL_AFTER、POD_TIMEOUT默认被忽略也可显式指定覆盖-p/--prefix测试名前缀默认取用户名同时写入metadata.labels.prefix-u/--uniquifier_element用于保证测试名唯一的元素可重复与日期字符串、运行序号拼接成 uniquifier-d快捷追加日期字符串作为 uniquifier 元素-a/--annotation写入metadata.annotations的keyvalue注解可重复-r/--regex按正则筛选场景默认.*--category按类别筛选场景默认all持续运行通常用scalable--allow_client_language允许指定语言的跨语言客户端典型为c可重复--allow_server_language允许指定语言的跨语言服务端典型为node或c可重复--instances_per_client为每个测试生成多个 client 实例实例以 client 名加索引命名未命名则为0,1, ...--runs_per_test每个测试重复 n 次n1 时运行序号并入 uniquifier-o/--output输出文件名缺省流式输出到 stdout。脚本自动为每个 LoadTest 打标metadata.labels含language场景语言与prefixmetadata.annotations含scenario场景名与uniquifier含运行序号。labels 可用于资源选择器查询如按 prefix 选择某次生成的全部资源annotations 则提供人类可读的辅助信息。拼接配置多语言配置可一次生成也可用 loadtest_concat_yaml.py 将多次生成的 YAML 拼接为一份后一次性运行loadtest_concat_yaml.py -i infile1.yaml infile2.yaml -o outfile.yaml生成示例与模板loadtest_examples.sh 生成所有支持语言的基础示例与预构建镜像模板配置loadtest_template.py 可从一组既有配置反向生成模板。例如生成基础模板./tools/run_tests/performance/loadtest_template.py \ -i ../test-infra/config/samples/*_example_loadtest.yaml \ --inject_client_pool --inject_server_pool \ --inject_big_query_table --inject_timeout_seconds \ -o ./tools/run_tests/performance/templates/loadtest_template_basic_all_languages.yaml \ --name basic_all_languagesloadtest_template.py选项包括-i/--inputs输入文件列表可重复、-o/--output、--inject_client_pool把 client 的 pool 属性替换为${client_pool}、--inject_driver_image${driver_image}、--inject_driver_pool${driver_pool}、--inject_server_pool${server_pool}、--inject_big_query_table${big_query_table}、--inject_timeout_seconds${timeout_seconds}、--inject_ttl_seconds${ttl_seconds}、-n/--name、-a/--annotation。注入替换键的选项对模板复用最有价值——切换节点池、结果表、超时与 TTL 时无需重写模板。运行测试loadtest_config.py生成的测试集合由独立仓库 grpc/test-infra 中的 test runner 应用并监控完成可并行部署到多个节点池并限制每池并发数。途径二仅限专家本地手动基准手动方式先决条件worker/driver 构建脚本预期已运行过 linux_performance_worker_init.sh。本地运行在仓库根目录启动 run_performance_tests.py。远程手动启动 driver 与 workers准备一台 driver 与若干 worker 机器如同一 zone 的 GCE 实例。在每个 worker 上以--driver_port启动对应语言 worker。C-core 系语言C、Python、C#、Node、Ruby都位于本仓库内较为简单cd grpc_repo_root tools/run_tests/performance/build_performance.sh tools/run_tests/performance/run_worker_language.sh每个语言有独立脚本如 run_worker_csharp.sh、run_worker_java.sh、run_worker_python.sh等。运行 driver场景 JSON 由 scenario_config.py 生成qps_json_driver 通过--scenarios_json参数接收形如{scenario: json_list_of_scenarios}的字符串。设置QPS_WORKERS环境变量为逗号分隔的 worker 列表driver 会在列表中第一个host:port上启动 benchmark server其余作为 clientexport QPS_WORKERShost1:10000,host2:10000,host3:10000 bins/opt/qps_json_driver --scenario_jsonscenario_json_scenario_config_string性能相关环境变量QPS_WORKER_CHANNEL_CONNECT_TIMEOUTqps_worker 消费整数秒配置基准 client 等待连上 server 的通道就绪时长适用于 server 启动较慢的环境若调大建议同时调大场景配置中的warmup_secondsQPS_WORKERSqps_json_driver 消费host:port逗号列表每个场景的num_servers决定前 N 个作为 server、其余作为 client。示例性 profiling测试期间可附加 profiler 到 server。例如统计 grpc-go server 的 syscall 数netstat -tulpn | grep driver_port取 pid再perf stat -p worker_pid -e syscalls:sys_enter_write内存剖析可用go tool pprof --text --alloc_space http://localhost:pprof_port/debug/heap。跨语言兼容性矩阵interop_matrixtools/interop_matrix/README.md 描述该模块为每种语言/运行时组合构建 gRPC Docker 镜像并上传到 Artifact RegistryAR这些封装了特定 release/tag 的镜像用于验证 gRPC 各发布版本之间的版本兼容性。夜间测试持续验证旧 client 最新 server的向后兼容。为某新 release 添加兼容性镜像的步骤授权gcloud auth login会打开浏览器也支持非浏览器方式见--help与gcloud auth configure-docker us-docker.pkg.dev在 client_matrix.py 中新增或更新指向该 release github tag 的条目构建新 client 镜像例如为 C 与 wrapper 语言 releasev1.9.9执行tools/interop_matrix/create_matrix_images.py --git_checkout --releasev1.9.9 --upload_images --language cxx python ruby php验证镜像已上传gcloud artifacts docker images list us-docker.pkg.dev/grpc-testing/testing-images-public或加--include-tags查看特定 tag验证新镜像能通过向后兼容测试docker pull .../grpc_interop_java:v1.9.9后执行docker_image.../grpc_interop_java:v1.9.9 tools/interop_matrix/testcases/java__master提交改动并发 PR触发 adhoc interop matrix 测试跑通后请求评审。新增语言/运行时在template/tools/dockerfile/下创建Dockerfile.template与build_interop.sh.template→ 运行 tools/buildgen/generate_projects.sh 生成 tools/dockerfile/ 下的实际文件 → 在client_matrix.py中追加条目 → 运行 create_matrix_images.py 构建并上传镜像。新增测试用例LANGgo ./create_testcases.sh # 生成 ./testcases/go__master同时是可执行的 bash 脚本 LANGgo KEEP_IMAGE1 ./create_testcases.sh # 保留本地镜像之后可直接 ./testcases/go__master 运行生成后提交./testcases/lang__release文件。注意手动docker rmi image_id清理保留的镜像。运行测试用例run_interop_tests.pyREADME 中也写作 run_interop_matrix_test.py的常用选项--releasegit release tag默认all需先用 create_matrix_images.py 建好对应 tag 镜像、--language默认all。全部运行tools/interop_matrix/run_interop_matrix_test.py --releaseall结果写入 JUnit 风格 XML默认report.xml。手动跑单个镜像docker_image.../grpc_interop_go1.8:v1.16.0 ./testcases/go__master。路径约定tools/或template/开头相对仓库根./开头相对当前目录tools/interop_matrixAR 路径us-docker.pkg.dev/grpc-testing需要读写权限。测试用 Docker 镜像dockerfiletools/dockerfile/README.md 解释CI 上绝大多数 Linux 测试都在 Docker 容器内运行以维持测试环境与依赖的可维护性、可复现性便于本地复现 CI 问题。镜像定义位于tools/dockerfile/third_party/rake-compiler-dock除外。版本管理每个 dockerfile 目录对应的.current_version文件如 tools/dockerfile/test/cxx_debian12_x64.current_version记录当前使用镜像的完整名称含 AR 位置、镜像名、tag 与 SHA256 digest形如us-docker.pkg.dev/grpc-testing/testing-images-public/cxx_debian12_x64:[CURRENT_CHECKSUM]sha256:[CURRENT_SHA256_DIGEST]该信息可直接传给docker run获得与 CI 完全一致的环境。更新镜像权威镜像存于us-docker.pkg.dev/grpc-testing/testing-images-public。修改 dockerfile 后上传新版本gcloud auth configure-docker us-docker.pkg.dev gcloud auth login # 安装 qemu/binfmt 以支持多架构容器 sudo apt-get install binfmt-support qemu-user-binfmt docker run --rm --privileged multiarch/qemu-user-static --reset -p yes tools/dockerfile/push_testing_images.sh仅本地构建、不上传适合快速本地实验速度更快LOCAL_ONLY_MODEtrue tools/dockerfile/push_testing_images.sh迁移期特性TRANSFER_FROM_DOCKERHUBtrue tools/dockerfile/push_testing_images.sh可从旧 dockerhub 拉取既有镜像而非从零构建。CI 集成internal_ci 与 Kokorotools/internal_ci/README.md 说明gRPC 的大部分开源测试由名为 Kokoro即 internal CI的 CI 工具驱动。该目录存放 Kokoro 测试任务的外部部分——作业定义本体在内部仓库这里保存的是实际执行测试的 shell 脚本入口。目录按平台组织linux/约 195 个文件含大量.cfg作业配置与.sh脚本、macos/、windows/另有helper_scripts/。前文提到的性能 CI 入口 grpc_e2e_performance_gke.sh 就在linux/下。原 README 中列出的jenkins模块在当前仓库中已由 Kokoro 取代。分发、发布与代码质量distrib 与 releasetools/distrib/ 承担语言包分发与辅助脚本python/下有生成 grpcio_tools 的 make_grpcio_tools.py、文档生成 docgen.py 等其余还有大量代码风格与静态检查脚本如clang_format_code.sh、clang_tidy_code.sh、buildifier_format_code.shBazel 格式化、isort_code.sh、pylint_code.sh、pyright_code.sh、ruff_code.sh、check_copyright.py、check_include_guards.py等以及 IWYU 辅助 add-iwyu.py。tools/release/ 提供发布支持backport_pr.shPR 回移、release_notes.py发布说明、update_supported_bazel_versions.sh等。Bazel 化测试bazelify_teststools/bazelify_tests/README.md 介绍一个实验性机制把非 Bazel 世界的构建与测试cmake 构建、run_tests.py 测试、构件、distribtests 等包装成可在 Bazel 下运行的目标。核心是//tools/bazelify_tests:repo_archive目标通过 workspace_status_cmd.sh 获取 grpc 及全部子模块的 commit SHA从 bazel execroot 越狱 访问 workspace 并生成确定性归档源码未变则校验和不变。归档后bazel 化测试在 Docker 容器中解包归档、建立临时 workspace 再执行所需动作如 run_tests.py、cmake 构建。容器执行有两种方式RBE 下所有 action 天然在容器内本地运行则用 Bazel docker sandboxWindows 暂不支持。测试规则会基于 gRPC 测试镜像自动配置exec_properties。RBE 运行--genrule_strategyremote,local允许 fallback 本地执行tools/bazel --bazelrctools/remote_build/linux.bazelrc test --genrule_strategyremote,local --workspace_status_commandtools/bazelify_tests/workspace_status_cmd.sh //tools/bazelify_tests/test:basic_tests_linux本地 docker sandbox 运行tools/bazel --bazelrctools/remote_build/linux_docker_sandbox.bazelrc test --workspace_status_commandtools/bazelify_tests/workspace_status_cmd.sh //tools/bazelify_tests/test:basic_tests_linux文档、云基础设施与辅助工具doxygenrun_doxygen.sh 依次对core、c、objc、php等含.internal变体执行doxygen tools/doxygen/Doxyfile.variant输出到doc/ref/variant/。对应 Doxyfile 位于 tools/doxygen/。gce搭建测试基础设施的脚本如创建 Linux Kokoro 性能 worker 的 create_linux_kokoro_performance_worker.sh 与节点初始化脚本 linux_kokoro_performance_worker_init.sh也是手动性能基准的前置条件。gcp与 GCP 服务GKE、BigQuery 等交互的辅助脚本其utils/被 run_tests.py 复用。调试与分析内存泄漏检查工具 error_ref_leak.pysrc/core引用泄漏、chttp2_ref_leak.py性能剖析 profiling/bloat、memory、qpstools/gource/ 用于生成仓库演进可视化。远程构建tools/remote_build/ 提供 RBE/Kokoro 用的各平台.bazelrclinux.bazelrc、mac.bazelrc、windows.bazelrc等与 workspace status 脚本。HTTP/2 互操作工具tools/http2_interop/ 是一套 Go 实现的 HTTP/2 互操作测试套件含s6.5.go等对应 http2-interop-test-descriptions.md 的用例与测试。快速定位指南与延伸阅读面对一个 gRPC 工程问题时可按此表快速定位 tools 下的对应入口需求入口重新生成全部构建文件tools/buildgen/generate_projects.sh跑某语言单元测试tools/run_tests/run_tests.py跨语言互操作测试tools/run_tests/run_interop_tests.py性能基准推荐框架tools/run_tests/performance/README.md构建/上传互操作矩阵镜像tools/interop_matrix/create_matrix_images.py获取与 CI 一致的容器环境tools/dockerfile/ 下对应.current_version分发语言包/跑风格检查tools/distrib/在 Bazel 中跑非 Bazel 测试tools/bazelify_tests/README.md从源码结构看tools目录与仓库根部的build_handwritten.yaml、build_autogenerated.yaml、Bazel 文件以及各 CI 作业配置形成了模板生成 → 构建 → 测试 → 发布的完整闭环理解它是深入参与 gRPC 开发、排障与发布流程的起点。【免费下载链接】grpcC based gRPC (C, Python, Ruby, Objective-C, PHP, C#)项目地址: https://gitcode.com/GitHub_Trending/gr/grpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考