用统一工具链开发、生成、测试并构建 Headscale

方案简介

这是一套面向 Headscale 贡献者的可复现开发工作流：使用 Go 作为主要开发语言，使用 Buf 和 Protobuf 工具处理协议代码，使用 Nix 准备统一开发环境，再由 Make 组织代码生成、测试和构建任务。Go 代码通过 golangci-lint 检查，并使用 golines 与 gofumpt 格式化；Proto 使用 buf 检查、clang-format 格式化。

方案适合参与 Headscale 开发、修改 proto/、运行测试或构建程序的贡献者。项目推荐使用 Nix 管理依赖，以便获得与维护者一致的工具环境；如果不使用 Nix，也可以自行安装依赖并直接使用 Make。

亮点与能力

• 使用 Nix 创建并激活开发 shell，安装开发工具。
• 用 Go 进行 Headscale 代码开发。
• 用 Buf 作为 Protobuf 生成器，并对 Proto 代码进行 lint。
• 修改 proto/ 后通过 Make 重新生成 Go 代码。
• 用 make test 运行测试。
• 用 make build 构建程序。
• 用 golangci-lint 检查 Go 代码。
• 用 golines、gofumpt、clang-format 和 mdformat 等工具统一格式。

组成与分工

• Go：Headscale 的主要开发语言，也是贡献者必须准备的核心工具。
• Buf：Protobuf 生成器，并负责 Proto 代码 lint。
• Protobuf tools：支持从 proto/ 生成 Go 代码。
• Nix：管理依赖并创建统一开发 shell。
• Make：串联 generate、test、build、lint、fmt 等开发任务。
• golangci-lint / golines / gofumpt：分别用于 Go lint 和代码格式化；Proto、文档及其他文件则由对应格式化工具处理。

前置要求

贡献 Headscale 至少需要最新版本的 Go 和 Buf（Protobuf generator）。项目还列出了 Protobuf tools，并推荐使用 Nix 准备开发环境。若使用 Nix，执行 nix develop 后会安装工具并进入开发 shell；若自行管理依赖，则需要自行准备 Makefile 所需工具。

项目没有在所给 README 材料中声明特定操作系统或硬件要求，因此不额外推断运行环境。

实施步骤

1. 进入统一开发环境

推荐使用 Nix 初始化开发工具和 shell：

nix develop

这一步用于获得与 Headscale 维护者一致的开发环境。

2. 生成协议代码

如果修改了 proto/，先执行：

make generate

生成的 gen/ 变更应单独提交，便于审查。

3. 运行测试

make test

4. 构建程序

make build

5. 在提交前检查格式与规范

项目要求在提交前运行 lint 和 fmt：

make lint

make fmt

如果不使用 Nix，也可以直接使用 Make；Makefile 会在缺少工具时发出警告，并建议运行 nix develop。

使用与配置要点

日常开发可以采用两种流程。推荐流程是在 Nix shell 中连续执行测试和构建：

nix develop
make test
make build

如果开发者自行维护依赖，则直接执行：

make test
make build

当修改协议定义时，先运行 make generate，再运行测试和构建；检查 gen/ 中生成代码的变更，并按项目建议单独提交。需要查看可用 Make 目标时，可运行 make help。

注意事项与常见问题

• 修改 proto/ 后必须重新生成 Go 代码。
• gen/ 的变更建议单独提交，以便审查。
• Makefile 会检查工具是否缺失，并建议使用 nix develop。
• Go 代码使用 88 列宽度的 golines，并配合 gofumpt。
• Proto 使用 buf lint 和 clang-format；文档使用 mdformat；Markdown、YAML 等其他内容使用 prettier。
• main 分支可能包含未发布变更；开发和贡献工作仍应注意版本与仓库规则。
• 项目另有 CONTRIBUTING.md 和 AI_POLICY.md，贡献前应阅读。

优缺点

• ✓ 维护者环境一致
• ✓ 生成测试构建流程明确
• ✕ 需要最新 Go 与 Buf
• ✕ 需额外维护多套格式化工具

出处

本方案挖掘自开源项目 juanfont/headscale，方案内容与实施命令均来自其 README 原文。