etcd 多模块 Go 仓库组织：模块划分、版本统一发布与跨模块依赖一致性校验

etcd 自 3.5 版本起采用「单仓库、多 Go module」的组织方式，各模块通过统一的版本号发布与严格的依赖一致性校验协同演进。本文以 etcd 官方贡献者指南 modules.md 为主体，结合当前仓库的 go.work、各模块 go.mod 与发布/测试脚本，完整讲解 etcd 的模块体系、跨模块依赖设计、版本统一与打 tag 的发布操作，以及 CI 中 dep / mod_tidy 校验的工作原理，帮助你在为 etcd 贡献代码或在其上游维护依赖时正确操作模块版本与标签。

单仓库多模块：etcd 的模块组织背景

etcd 项目自 3.5 起，所有 Go 模块都托管在同一个代码仓库中，但每个模块拥有独立的 go.mod 和独立发布的版本号。这种「single repo, multiple modules」模式允许客户端库、服务端实现、命令行工具分别演进，同时保证发布时版本对齐。

当前仓库根目录的 go.work 由脚本自动生成（文件头部注明 "This is a generated file. Do not edit directly."），声明了工作区包含的全部模块，并统一使用 go 1.26 与 toolchain go1.26.6：

use (
	.
	./api
	./cache
	./client/pkg
	./client/v3
	./etcdctl
	./etcdutl
	./pkg
	./server
	./tests
	./tests/antithesis/pkg
	./tools/mod
	./tools/rw-heatmaps
	./tools/testgrid-analysis
)

go.work 的存在意味着本地开发时，跨模块引用直接走工作区解析；而真正发布的产物仍是各模块独立的 go.mod。

模块全景：官方文档定义的八个核心模块

modules.md 明确了以下模块及其职责边界：

模块路径	目录	职责
go.etcd.io/etcd/api/v3	api/	API 定义，包含 proto 及 proto 生成的库，定义客户端与服务器之间的通信协议
go.etcd.io/etcd/pkg/v3	pkg/	通用工具包集合，不属于 etcd 特有代码；只有「未来可能被独立拆出仓库」的包才能放这里
go.etcd.io/etcd/client/v3	client/v3/	通过 gRPC 访问 etcd 的客户端库，所有新使用方式均推荐它
go.etcd.io/raft/v3	独立仓库	Raft 分布式共识协议实现，应不包含任何 etcd 特有代码
go.etcd.io/etcd/server/v3	server/	etcd 服务实现；代码属于 etcd 内部，外部项目不应引用，包结构与 API 可在次版本号内变动
go.etcd.io/etcd/etcdctl/v3	etcdctl/	访问和管理 etcd 的命令行工具
go.etcd.io/etcd/tests/v3	tests/	存放 etcd 全部集成测试；注意：所有单元测试（快速、不依赖跨模块）应保留在被测代码所在的本地模块内
go.etcd.io/bbolt	独立仓库	持久化 B 树实现

其中有两条重要的工程约束值得强调：

• pkg 模块的准入原则：文档明确要求避免向 go.etcd.io/etcd/pkg/v3 添加自身依赖繁重的代码，因为这些依赖会自动成为客户端库的依赖，而客户端库需要保持轻量。这一点可以从 pkg/go.mod 得到印证：它的直接依赖仅约十余项（cobra、pflag、zap、otel/trace 等）。
• server 模块的封闭性：server 的代码被视为 etcd 内部实现，外部项目引用它的行为不受保障，API 可能在 minor 版本内变更。

当前仓库中的模块演进

以当前仓库快照核对各目录的 go.mod 首行，模块体系已较 3.5 文档时期有所扩展（各模块当前开发版本号为 v3.8.0-alpha.0）：

模块路径	目录	说明
go.etcd.io/etcd/v3	仓库根目录 go.mod	根模块（含 etcd 主程序入口），通过 replace 指令把所有子模块指向本地目录
go.etcd.io/etcd/client/pkg/v3	client/pkg/	客户端支撑库（transport、logutil、fileutil、types 等），client/v3 与 pkg 均依赖它
go.etcd.io/etcd/etcdutl/v3	etcdutl/	面向直接操作 etcd 存储文件的命令行工具（snapshot、defrag、hashkv 等）
go.etcd.io/etcd/cache/v3	cache/	实验性客户端缓存库，cache/README.md 注明其依赖 RequestProgress RPC，gRPC 代理不支持
go.etcd.io/etcd/tests/v3 的测试辅助模块	tests/antithesis/pkg、tools/mod、tools/rw-heatmaps、tools/testgrid-analysis	仅服务于测试与工具链的辅助模块

这也印证了文档「Future」部分的走向：etcdutl 正是从 etcdctl 中拆分出来的物理存储操作工具。

跨模块依赖设计与本地开发

api 是协议层的地基。 api/go.mod 的直接依赖只有 semver、protobuf、grpc-gateway、grpc 等协议栈相关库，与文档所述「定义客户端与服务器之间通信协议」的定位一致；api/etcdserverpb/、api/mvccpb/ 等目录存放 proto 定义与生成代码。

server 依赖外部共识与存储库。 从 server/go.mod 可以看到，它依赖独立仓库中的 go.etcd.io/raft/v3（当前为 v3.7.0）与 go.etcd.io/bbolt（当前为 v1.5.0），同时以 v3.8.0-alpha.0 依赖本仓库的 api、client/pkg、client/v3、pkg 模块——即文档所述「client/v3@vX 必须依赖 api/v3@vX」的同版本规则在 server 上同样生效。

本地开发依赖 replace 指向本地目录。 各模块 go.mod 末尾带有 replace 指令，例如 server/go.mod：

replace (
	go.etcd.io/etcd/api/v3 => ../api
	go.etcd.io/etcd/client/pkg/v3 => ../client/pkg
	go.etcd.io/etcd/client/v3 => ../client/v3
	go.etcd.io/etcd/pkg/v3 => ../pkg
)

根 go.mod 同样以 replace 把 go.etcd.io/etcd/api/v3 等全部子模块指向本地相对路径。这意味着在仓库内构建时，模块间的引用始终使用本地源码而非已发布版本，修改 api 后 server 能立即感知。

发布操作一：统一所有模块的版本号

文档的第一条发布规则是：所有 etcd 模块必须以同一版本发布，例如 client/v3@v3.5.10 必须依赖 api/v3@v3.5.10。一致性更新通过脚本完成：

% DRY_RUN=false TARGET_VERSION="v3.5.10" ./scripts/release_mod.sh update_versions

结合 scripts/release_mod.sh 源码，可以看清该命令的完整行为：

• 入口函数 update_versions_cmd（scripts/release_mod.sh#L68）首先要求工作区 git 状态干净（assert_no_git_modifications），并强制要求设置 TARGET_VERSION 环境变量，否则直接报错退出；
• 脚本会自动把 v3 版本号换算出对应的 v2 版本号（scripts/release_mod.sh#L80）：sed 's|^v3.\([0-9]*\).|v2.30\1.|g'，即 v3.5.0 对应 v2.305.0，保证历史 v2 模块路径的引用也同步更新；
• 核心逻辑 update_module_version（scripts/release_mod.sh#L42）先用 go mod edit -json 列出当前模块的所有直接依赖，筛出属于 go.etcd.io/etcd 族的 */v3 与 */v2 路径，逐一执行 go mod edit -require "dep@version" 重写版本号，前后各跑一次 go mod tidy 收拢依赖；
• 整个过程由 run_for_workspace_modules 对 go.work 中的每个模块重复执行；
• 安全性：脚本默认 DRY_RUN=true（scripts/release_mod.sh#L27），只打印将执行的操作而不落盘，确认无误后显式加 DRY_RUN=false 才真正修改文件。

发布操作二：为每个模块打独立 tag

第二条规则要求按 Go 模块版本规则（VCS versioning）为每个模块单独打 tag：push_mod_tags 命令：

% DRY_RUN=false REMOTE_REPO="origin" ./scripts/release_mod.sh push_mod_tags

从 push_mod_tags_cmd（scripts/release_mod.sh#L102）的实现可以看到两个关键细节：

• tag 命名规则：tag 名 = 模块版本号去掉模块路径中的 /v3（或 /v2） 段。例如模块 go.etcd.io/etcd/api/v3 版本 v3.5.10 对应 tag api/v3.5.10，模块 go.etcd.io/etcd/v3（根模块）则直接是 v3.5.10。相关逻辑见 scripts/release_mod.sh#L123-L136，其中 subdir 通过 ${path//${ROOT_MODULE}\//} 剥离模块前缀后生成：

  local subdir="${path//${ROOT_MODULE}\//}"
  ...
  tag="${subdir///v[23]/}/${version}"
  run git tag --local-user "${keyid}" --sign "${tag}" --message "${version}"
  

• GPG 签名与推送时序：每个 tag 都使用 git 配置的邮箱对应的 GPG key 签名（get_gpg_key 会校验 key 存在）；循环中对每个模块 sleep 2，脚本注释说明这是一个保证 git describe 将主模块 tag 识别为最新 tag 的时序 hack；最终通过 git push -f 一次性推送所有 tag 到 REMOTE_REPO。

发布操作三：CI 校验依赖一致性与 go.mod 整洁

文档第 3、4 条规则对应 scripts/test.sh 中的两个校验 pass，均可用 PASSES 变量单独触发（脚本默认 pass 集为 bom dep build unit，见 scripts/test.sh#L76）：

% PASSES="dep" ./test.sh        # 校验所有模块依赖版本一致
% PASSES="mod_tidy" ./test.sh   # 校验 go.mod 无冗余依赖且符合 go mod tidy 格式

• dep pass：dep_pass（scripts/test.sh#L482）先对 go.work 中每个模块执行 dump_module_deps 导出「依赖,版本,直接/间接,来源模块」清单并排序，然后检查同一依赖在不同模块中是否出现不同版本——一旦发现重复依赖名对应多个版本，就以 FAIL: inconsistent versions for dependency 报错并列出各处取值；同时检查各模块是否遗漏了相同依赖。这直接落实了文档「所有 etcd 模块应依赖相同版本的底层依赖」的要求。
• mod_tidy pass：mod_tidy_pass（scripts/test.sh#L590）对每个模块执行 go mod tidy -diff：只要 tidy 后的输出与现有 go.mod/go.sum 存在差异即判定失败，从而保证 go.mod 不含未使用的依赖且格式符合 tidy 规范。

跨模块批量操作的入口：make fix

文档第 5 条建议：需要对所有模块触发统一动作（例如自动格式化全部文件）时，使用或扩展 make fix。当前仓库 Makefile#L109 中该目标已聚合了多个修复动作：

fix: fix-mod-tidy fix-bom fix-lint fix-yamllint sync-toolchain-directive \
	update-go-workspace fix-shell-ws

各子目标分别对应 scripts/fix/ 下的脚本（如 fix/mod-tidy.sh 删除并重新 tidy go.sum、sync_go_toolchain_directive.sh 同步各模块的 toolchain 指令、根目录 update_go_workspace.sh 重建 go.work），与「对全部模块批量执行同一操作」的初衷一致。此外 scripts/test.sh 中的 go_workspace_pass 会检查 go.work.sum 是否处于同步状态，并在失败时提示运行 make fix 修复——这解释了为什么 go.work 被标记为生成文件、禁止手改。

未来规划：North Star 模块模型

文档最后给出了模块体系的演进方向（North Star），目标模型如下图所示：

该模型包含三个前提：

1. 将 etcdmigrate/etcdadm 从 etcdctl 二进制中拆分出来。拆分后 etcdctl 成为纯粹的网络客户端 API 的命令行封装，而 etcdmigrate/etcdadm 则支持对 etcd 存储文件的直接物理操作。当前仓库中的 etcdutl/ 模块（提供 snapshot、defrag、hashkv、migrate 等子命令）可以视为这一拆分思路的阶段性落地。
2. 将 etcd-proxy 从 ./etcd 二进制中拆分出来。代理功能包含更多实验性代码，会引入额外风险与依赖，独立成模块可隔离这部分风险。
3. 弃用 v2 协议支持。这也与发布脚本中 v2 版本号换算逻辑（v2.30\1. 前缀）相呼应——脚本仍需为兼容历史 v2 模块路径而维护双版本号映射，v2 弃用后这部分逻辑将随之简化。

小结：模块操作速查

目的	命令	关键源码
统一所有模块版本到目标版本	DRY_RUN=false TARGET_VERSION="v3.5.10" ./scripts/release_mod.sh update_versions	scripts/release_mod.sh#L68
为每个模块打签名的独立 tag 并推送	DRY_RUN=false REMOTE_REPO="origin" ./scripts/release_mod.sh push_mod_tags	scripts/release_mod.sh#L102
校验跨模块依赖版本一致	PASSES="dep" ./scripts/test.sh	scripts/test.sh#L482
校验 go.mod 符合 tidy 格式	PASSES="mod_tidy" ./scripts/test.sh	scripts/test.sh#L590
对全部模块批量修复（tidy/BOM/lint/workspace 等）	make fix	Makefile#L109

需要牢记的三条边界：server 模块仅供 etcd 内部使用、外部不应引用；pkg 模块只收可能独立拆出、且不拉重客户端依赖的通用工具包；本地开发时 go.work 与 replace 指令保证模块间走本地源码，而发布版本一致性则由上述脚本与 CI pass 强制保障。