• 网络
• 桌面应用
• 数据可视化

Sniffnet 是一款用 Rust 编写的开源网络流量监控工具，其仓库维护者奉行"少而精"的贡献策略。本文以仓库根目录下的 CONTRIBUTING.md 为核心主线，结合 src/gui/sniffer.rs、src/gui/types/conf.rs、src/translations、Cargo.toml 与 CHANGELOG.md 等源码与工程文件，完整解读 Sniffnet 的贡献规则、架构约束、质量门禁与 PR 评审流程，帮助你在提交第一个 Pull Request 之前就掌握全部"潜规则"，提高合并成功率。

一、Sniffnet 的贡献理念：重质不重量

CONTRIBUTING.md 开篇即点明了项目基调：为了保持 Sniffnet 的高质量，维护者对提交的贡献非常挑剔（very selective）。这意味着贡献者不应抱着"能跑就行"的心态，而要把每一行代码都当成自己必须负责的产品代码来对待。

由此引出了第一条硬性规则：

纯粹的 LLM 生成代码会被强烈劝阻，且极大概率被拒绝。你必须理解并能够捍卫你提交的每一行代码，如果在过程中使用了 AI 辅助，必须如实披露。

这一条并非空泛要求。Sniffnet 是一个网络嗅探与解析项目，涉及 pcap 抓包、IPFIX 收集、数据包解析（见 lib/sniffnet-packet-parser）等底层逻辑，任何不经理解而生成的代码都可能引入难以排查的网络层错误。因此，贡献者需要具备"为自己的每一行代码负责"的能力，并在 PR 描述中主动说明 AI 辅助的使用情况。

二、开始编码前：Issue 认领与问题报告流程

在动手写代码之前，CONTRIBUTING.md 明确了两步"排他性"检查：

1. 检查 Issue 是否已被认领：开始开发某个功能前，务必确认对应的 issue 没有被分配给其他人，避免与别的贡献者撞车、浪费双方的工作。
2. 优先认领带[help wanted]标签的 Issue：这是项目方主动"招工"的信号，认领这类任务意味着功能方向已被维护者认可，合并阻力最小。

如果仓库中不存在与你计划的功能或修复对应的 issue，则需要先自行开一个 issue：

• 功能类（feature）：开 issue 与维护者讨论，获取反馈后再动手，避免做出来一个不符合项目愿景的功能；
• 缺陷类（bug）：先确认问题真实存在、可复现、且未被报告过，并在 issue 中提供尽可能多的信息（如适用，附上截图）。

这一流程与 CHANGELOG.md 中大量"PR #XXXX — fixes #XXXX"的条目形成闭环：每一个被合并的改动都能追溯到一个明确的问题编号，这正是项目对"可追溯贡献"的工程化要求。

三、代码编写规范与架构约束

3.1 复用现有代码，保持 PR 小而聚焦

第四条规则要求：尽可能复用现有代码和库，保持 PR 小而聚焦，质量优先于数量。Sniffnet 本身就是一个"复用"的典范——它的工作区由主程序和sniffnet-packet-parser库组成（见 Cargo.toml 的[workspace] members），主程序重度依赖pcap、etherparse、iced、tokio、maxminddb等成熟生态库。贡献者在新增功能时也应遵循同样的取舍：能用现成 crate 解决的问题就不该手写轮子。

3.2 面向用户文案必须国际化（i18n）

第五条是针对 GUI 改动的专项要求：如果新增了面向用户（UI-facing）的句子，必须国际化，具体做法是：

• 在 src/translations 模块中新增对应方法；
• 必须提供英文翻译；
• 其他语言只有在你是母语者时才添加（避免引入不自然的翻译）。

从源码结构看，src/translations/mod.rs 将翻译拆分为translations到translations_6共 6 个文件，每个文件中都包含大量形如Language::EN => "..."、Language::ZH => "..."的匹配分支（参见 src/translations/translations.rs）。新增 UI 文案时，需要找到对应主题的翻译函数，在Language枚举中补齐英文条目，而不是把硬编码字符串直接写进页面组件。

3.3 修改 Sniffer 结构体时的"持久化 vs 临时"判断

第六条是理解 Sniffnet 状态管理的核心规则：如果修改了Sniffer结构体：

• 若新字段需要跨运行持久化，必须同步加入Conf结构体；
• 若新字段需要在每次抓包会话开始时重置，则在Sniffer::reset()中清理。

这一规则直接对应两个真实源码位置：

• Sniffer结构体定义于 src/gui/sniffer.rs，它的文档注释明确写着"它承载状态、网络流量统计等"，并持有conf: Conf、info_traffic、logged_notifications、search、timing_events等几十个字段；
• Conf结构体定义于 src/gui/types/conf.rs，负责所有需要跨运行保存的配置（如data_repr数据表示、host_sort_type排序方式等），并通过confycrate 序列化到磁盘；
• Sniffer::reset()实现于 src/gui/sniffer.rs，每次重置都会关闭旧抓包通道、递增 capture id 以忽略旧消息，并把info_traffic、addresses_resolved、latency_statuses、logged_notifications等会话级状态全部清空。

判断一个字段该放哪里，本质上是在问："它描述的是用户偏好（放Conf，跨运行保留），还是某次抓包的瞬时状态（放Sniffer并在reset()里清理）？" 例如frozen（抓包是否冻结）是会话级状态，所以它在reset()中被重置为false；而data_repr是用户偏好，因此作为Conf字段持久化。

3.4 修改 lib 目录下库的版本管理规则

第七条针对工作区中的子库：如果修改或新建了lib文件夹下的库，必须：

1. 提升（bump）其版本号；
2. 更新其自身的CHANGELOG.md；
3. 同步更新Cargo.toml的依赖与 workspace members 配置。

以仓库中唯一的子库 lib/sniffnet-packet-parser 为实证：它的 Cargo.toml 当前版本为0.2.1，通过default = ["full"]特性开关控制etherparse与pcap依赖；主程序 Cargo.toml 中通过sniffnet-packet-parser = { path = "lib/sniffnet-packet-parser", version = "0.2.1" }引用它，同时它也被列入[workspace] members。其 CHANGELOG.md 完整记录了0.1.0 → 0.2.0 → 0.2.1的演进：0.2.0加入 IGMP 支持与 VLAN ID 支持，0.2.1新增NetInfo::ether_type。贡献者修改该库后，必须遵循同样的三步流程，否则主程序将无法通过依赖版本解析。

四、质量门禁：提交前必须通过的三道检查

第八条定义了每个 PR 在提交前必须通过的硬性质量门禁：

cargo test cargo clippy -- -D warnings cargo fmt --all -- --check

• cargo test：补充单元测试来断言实现的正确性（如果适用）。项目在[dev-dependencies]中引入了rstest、serde_test、serial_test等测试工具（见 Cargo.toml），说明测试是项目工程文化的一部分；
• cargo clippy -- -D warnings：将 Clippy 的所有警告视为错误。这与 Cargo.toml 中[workspace.lints.clippy]的严格配置一致——pedantic级别告警、unwrap_used、expect_used、panic、todo、unimplemented、dbg_macro、print_stdout等全部开启为warn。换句话说，提交的代码不能包含unwrap()滥用、dbg!残留、直接println!等习惯性写法；
• cargo fmt --all -- --check：检查整个工作区（含子库）的代码格式是否符合rustfmt标准。

此外，Cargo.toml 的[workspace.lints.rust]中设置了unsafe_code = "forbid"，即整个项目禁止不安全代码。这意味着你的贡献同样不允许出现unsafe块——如果实现需要unsafe，应当重新设计或用现有安全抽象替代。

五、CHANGELOG 维护：每个改动都必须留痕

第九条要求：必须更新 CHANGELOG.md 的[UNRELEASED]小节，为改动写一行描述，并在适用时附带对应 PR 和 issue 的链接，格式遵循已有条目的样式。

从 CHANGELOG.md 的当前[UNRELEASED]小节可以看到真实格式范例：

## [UNRELEASED] - IPFIX collector capabilities: receive and analyze network traffic from remote devices - Added support for IGMP connections and messages - Added support for VLAN-tagged connections - Enhance update checks - Show output file path in Overview page when exporting a PCAP file

正式发布条目则遵循更完整的版本号 - 日期+PR — fixes issue格式，例如：

## [1.5.1] - 2026-07-22 - Show latency of connections ([#1194] — fixes [#845]) - Added Hungarian translation

注意 CHANGELOG 是"面向用户的功能变更日志"，不是代码提交日志——只有对用户可感知的变化（新功能、修复、翻译、打包变更等）才应被记录，内部重构若无用户影响则不需要。贡献者只需在[UNRELEASED]下追加一行，不必为每个 commit 都写条目。

六、PR 评审节奏与最终裁量权

第十、十一条是两条关于"心理预期"的规则，同样重要：

1. 评审可能需要较长时间，尤其是改动规模较大的 PR。Sniffnet 的维护者会认真逐行审查，贡献者应耐心等待，不要频繁催促；
2. 即使满足了以上所有规则，贡献仍可能在维护者的自由裁量下被拒绝——如果改动与项目愿景不一致，或引入了不必要的复杂性。

这两条看似"软性"，实则与第一条"非常挑剔"的基调一脉相承：Sniffnet 把长期可维护性置于短期功能增长之上。贡献者能做的，是严格遵循上述流程、把 PR 控制在合理范围内，并在提交前自己先做一遍代码审查。

七、开发环境搭建与社区行为规范

CONTRIBUTING.md 最后给出了两个预备步骤：

1. 搭建开发环境：参考项目的Build from source（从源码构建）Wiki 页面。仓库中 README.md 同样包含构建说明，项目依赖libpcap（Linux 上还需libasound2、libfontconfig1等运行时库，见 Cargo.toml 的 deb 打包元数据），并基于 Rust 2024 edition 与 workspace 结构组织，本地开发可通过如下方式克隆与验证：

   git clone https://gitcode.com/GitHub_Trending/sn/sniffnet cd sniffnet cargo build

2. 遵守社区行为规范：贡献者需阅读 CODE_OF_CONDUCT.md，其中明确了社区期望的开放、友善、包容的行为标准，以及违反后的分级处理流程（纠正、警告、临时封禁、永久封禁）。

结语

Sniffnet 的贡献指南虽然严格，但正如文末所言："不要因为我们的严格而不敢分享想法——所有扩大或改进 Sniffnet 的提议都受到热烈欢迎。"这份指南的价值在于把"好贡献"的标准显性化了：小且聚焦的 PR、真实可追溯的 issue、完整通过的测试与 lint、规范的 i18n 与 CHANGELOG，以及对每一行代码的深度理解。按照这套流程提交，你的贡献不仅更容易被合并，也会让 Sniffnet 社区继续维持它引以为傲的代码质量。

• 网络
• 桌面应用
• 数据可视化