企业官网建设流程全解析

• 系统底层
• 网络
• 可观测性

导读

本文基于 docs/ebpf/contributing/new-feature.md 整理，系统讲解如何为ebpf-go（cilium/ebpf，一个纯 Go 实现的 eBPF 库）贡献一项新功能。你将掌握四步贡献流程、如何通过最小化新增导出 API 来提高合入概率，以及项目在 API 稳定性上的三条铁律；文中还结合仓库源码（架构文档、CI/apidiff 工作流、哨兵错误实现）说明功能落地时的工程约束与验证手段，适合计划向 ebpf-go 提交 PR 的开发者阅读。

项目背景：ebpf-go 的贡献形态

ebpf-go 是一个纯 Go 库，用于读取、修改、加载 eBPF 程序并将其挂载到 Linux 内核的各类钩子上。库的绝大部分功能分布在ebpf、btf与link三个包中（见 docs/ebpf/contributing/architecture.md），因此"添加新功能"通常不是孤立的代码片段，而是贯穿 ELF 解析、规格（Spec）构造、内核对象加载与链接（Link）挂载的全链路改动。

项目明确表示非常欢迎能够充实库功能的贡献（"We're very much looking for contributions which flesh out the functionality of the library"），本文即围绕这一贡献路径展开。

添加新功能的四步流程

第 1 步：先理解库的架构

在动手之前，务必先通读 架构文档。文档用依赖图给出了核心类型关系，其中关键分层如下：

• ELF 层：BPF 程序通常由 Clang 编译 C 子集得到 ELF 文件，其中既包含程序字节码，也包含 map 的元数据。元数据遵循内核自带 libbpf 的约定，较新的 clang 还会额外发出 BPF Type Format（BTF）元数据。ELF 读取器的输出是一个CollectionSpec，且要求确定性——同一 ELF 在不同系统上必须解析出相同结果，因此依赖内核版本等运行时环境的改动必须推迟到创建 Objects 阶段进行。
• 规格层（Specifications）：CollectionSpec是ProgramSpec、MapSpec、btf.Spec的简单容器，文档明确建议"尽量别给它加功能"。ProgramSpec与MapSpec是内核对象的蓝图，包含执行bpf(2)系统调用所需的全部信息，并引用btf.Spec提供类型信息。
• 对象层（Objects）：Program与Map是规格加载进内核后的结果，凡是依赖当前系统（如内核版本）的功能都在此层实现。加载失败时库有两种应对：回退（Fallback）（如老内核不支持命名，库自动检测后省略名字）与哨兵错误（Sentinel error）（检测到特性不可用时返回包装了ErrNotSupported的错误，该错误也可用于跳过当前内核上无法运行的测试）。
• 链接层（Links）：新挂载点倾向于使用bpf_link，老钩子则依赖系统调用、netlink 消息等组合。架构文档强调：为某个新 link 类型添加支持时不应引入 netlink 之类的大型依赖，因此 XDP 程序或 tracepoint 这类场景被明确排除在 link 层范围之外。每个bpf_link_type对应一个 Go 类型（如link.tracing对应BPF_LINK_TRACING），类型默认不导出，但可以对应多个导出的构造函数（如AttachTracing与AttachLSM都创建 tracing link）。

理解了这条依赖链（Program → ProgramSpec → ELF，btf.Spec 贯穿规格层），你就能判断自己的新功能应该落在哪一层、会牵动哪些既有代码。

第 2 步：先讨论需求，再写代码

加入社区的#ebpf-go-dev频道（项目鼓励通过社区 Slack 讨论）讨论你的需求与实现方式；如果不习惯使用 Slack，也可以直接开启一个 Discussion。讨论阶段最重要的产出是弄清楚：

需要新增多少导出 API？新增的导出 API 越少，功能就越容易合入。

这是本文档最核心的工程理念：新功能与既有 API 的结合点越少，评审负担越小、对现有用户的冲击越小、回归风险越低。讨论时应一并参考下面的 API 稳定性 一节，尽早评估变更的破坏性等级。

第 3 步（可选）：创建 Draft PR 用于讨论实现

如果实现过程中遇到问题，或希望评审者尽早看到方向，可以创建一个Draft PR。文档明确放宽了对 draft PR 的要求：即使编译不过、包含调试语句也没有关系。draft PR 的价值在于把讨论从抽象层面落到具体 diff 上，让维护者与社区成员围绕实际代码给出反馈。

第 4 步：提交可合并的 PR

最终需要提交一个**可以合并（ready to merge）**的 PR，它必须满足两个硬性条件：

1. 通过 CI：仓库的 .github/workflows/ci.yml 定义了build-and-lint（运行 staticcheck、golangci-lint 并执行go build -v ./...）、generate-and-fix（执行make clean && make container-all后校验生成文件是否有 diff、运行 scripts/go-fix.sh）以及 cross-build 等多个 job；此外 .github/workflows/apidiff.yml 会在 PR 上运行go-apidiff，把 API 差异按semver-type分类并上传产物，用于监督 API 变更的影响面。
2. 包含测试：新功能必须有对应测试（仓库中*_test.go遍布各包，例如features包、link包均有独立的测试文件），且测试应尽量能在当前内核上运行；对无法运行的环境应利用ErrNotSupported哨兵错误跳过（见 docs/ebpf/concepts/features.md）。

补充：若功能需要重新生成测试 ELF 或生成的 Go 源码，需在仓库根目录执行make（依赖 Docker 或 Podman，见 Makefile 中CONTAINER_ENGINE ?= $(if $(shell command -v podman),podman,docker)的取值逻辑）；CI 的generate-and-fixjob 会强制要求生成产物与提交一致，否则判失败。

API 稳定性准则

文档强调：尽管该库目前不保证 API 的稳定性（尚无 1.x 版本承诺），但仍将兼容性放在重要位置。三条准则如下：

准则 1：优先"新增 + 废弃"，其次才是移除

如果可能，应通过引入新 API 的同时废弃旧 API来避免破坏。在 v0.x 中被废弃（deprecated）的 API，可以在 v0.x+1 中移除。

这一条在新旧 API 之间没有直接的转换途径时尤其重要——如果用户无法机械地从旧 API 迁移到新 API，过早移除会让他们陷入困境。

准则 2：破坏性变更可接受，但必须有充分理由

以导致编译失败的方式破坏 API（breaking API in a way that causes compilation failures）是可以接受的，但必须有充分的理由。

编译期暴露的破坏是"可见的破坏"——用户能立刻发现并修正，因而风险相对可控；但这种变更仍需要解释清楚必要性。

准则 3：静默改变语义是强烈不鼓励的

在不引起编译失败的前提下改变 API 的语义（changing the semantics of the API）是强烈不鼓励（heavily discouraged）的。

这类变更最危险：代码能编译、程序行为却悄悄改变，用户无法通过编译器感知。文档用"heavily discouraged"的措辞表明这是绝对红线。

从源码看 API 稳定性如何落地

仓库中的工程实践与上述准则相互印证：

• AGENTS.md 的 Code Style 章节明确："Breaking changes to public API is to be avoided with a few exceptions"、"Public interfaces that haven't appeared in a release yet can be changed at will"（尚未出现在任何发布版本中的公共接口可以随意修改）、"It's better to make an API more restrictive/conservative initially"（API 宁可先保守再逐步放开）——这与文档"新 API 越少越好"的理念一脉相承。
• .github/workflows/apidiff.yml 在每次 PR 上运行go-apidiff并输出semver-type，从工具层面持续监督 API 差异的等级，防止无意识的导出 API 膨胀或破坏。
• 哨兵错误ErrNotSupported定义在 internal/feature.go（var ErrNotSupported = errors.New("not supported")），被features包、btf、link等多处引用。它在功能贡献中承担双重角色：既是"特性不支持"的清晰信号，又是测试的跳过机制，详见 docs/ebpf/concepts/features.md 中对错误语义的约定（nil= 支持、ErrNotSupported= 不支持、其他错误 = 探测不确定）。

把新功能做进架构：落地时的检查清单

结合四步流程与架构分层，一个高质量的功能 PR 应当满足：

1. 功能定位清晰：明确新功能作用于 ELF 读取、Spec 构造、对象加载还是 Link 挂载哪一层，避免在错误的抽象层引入逻辑（例如依赖内核版本的逻辑应放在创建 Objects 时而非解析 ELF 时，以保持CollectionSpec的确定性）。
2. 导出 API 最小化：优先使用未导出的内部类型 + 少量导出构造函数（参照link.tracing的模式），能复用Link接口就不新增类型。
3. 兼容性自检：对照三条 API 稳定性准则评估变更等级；若必须破坏，在 PR 描述中说明充分理由；尽量走"新增 + 废弃"路线。
4. 测试与 CI 完备：新增针对性测试并通过 .github/workflows/ci.yml 的全部 job；不可运行的测试用ErrNotSupported优雅跳过；涉及生成产物（ELF、stringer/gentypes 生成的 Go 文件）时先运行make并保持产物与代码同步。
5. 与维护者保持沟通：讨论阶段明确 API 边界，draft PR 用于校验实现方向，最终 PR 应聚焦、易评审。

结语

为 ebpf-go 添加新功能，本质上是一次"架构理解 + 最小化 API 设计 + 严格兼容性纪律"的工程实践。遵循"先讨论、再实现、后提交"的顺序，牢记新增 API 越少越易合入，并用好ErrNotSupported哨兵错误与 apidiff 等既有机制，你的贡献就能以较低的摩擦进入这个以严谨著称的纯 Go eBPF 库。

• 系统底层
• 网络
• 可观测性