企业官网建设流程全解析

• 示例工程

本指南以仓库根目录 CONTRIBUTING.md 为骨架，结合仓库内真实源码、测试与工程配置，系统讲解如何向这个以「地道的 Rust 代码 + 泛型化设计」为特色的算法合集（All Algorithms implemented in Rust）提交高质量 Pull Request。读完你将掌握：项目模块的组织规范、mod.rs导出模式、算法与测试同文件的写法，以及提交前必须通过的三条质量检查命令与背后的工程意义。

项目定位：idiomatic code 与 genericity

仓库根目录的 README.md 与 CONTRIBUTING.md 开篇即明确了项目目标：以 Rust 实现常见算法，并强调地道的（idiomatic）代码风格与泛型化（genericity）设计。这意味着贡献的重点不只是「算法正确」，更在于代码是否充分利用 Rust 的模块系统、所有权模型、迭代器与 trait 等语言特性，写出可读、可复用、符合社区惯例的实现。

从 src/lib.rs 可以看到，整个代码库被划分为 24 个顶层公开模块（如backtracking、graph、math、sorting、string等），全部通过pub mod对外暴露。理解这一目录结构，是提交代码前的第一课。

项目结构：分类目录 + 单文件算法 + mod.rs 导出

CONTRIBUTING.md 给出的标准结构如下：

src/ - my_algo_category/ - mod.rs - my_algorithm.rs - some_other_algorithm.rs - some_other_algo_category/ - ...

落实到仓库中，例如 src/backtracking/ 目录下就同时包含mod.rs与n_queens.rs、sudoku.rs、knight_tour.rs等十余个单文件算法实现；src/graph/ 下则聚集了dijkstra.rs、depth_first_search.rs、topological_sort.rs等 29 个图算法文件。规则可以归纳为三条：

1. 每个算法类别一个子目录，目录名使用蛇形命名（snake_case）；
2. 每个算法一个独立.rs文件，文件内同时携带该算法的单元测试；
3. 每个目录的mod.rs负责模块声明与公开导出，对外只暴露经过筛选的 API。

mod.rs 的导出模式

CONTRIBUTING.md 给出了mod.rs的标准写法：

mod my_algorithm; pub use self::my_algorithm::my_algorithm;

即先用mod声明子模块，再用pub use self::...把内部的公开函数提升到当前模块命名空间。仓库中的真实例子完全遵循这一模式，以 src/backtracking/mod.rs 为例：

mod n_queens; mod sudoku; // ... pub use n_queens::n_queens_solver; pub use sudoku::sudoku_solver; // ...

注意这里的具体实践：模块声明使用mod n_queens;，导出时使用pub use n_queens::n_queens_solver;（仓库现行代码省略了文档示例中的self::前缀，两者等价）。src/graph/mod.rs 展示了更复杂的导出形态——不仅可以导出函数（pub use self::dijkstra::dijkstra;），还可以导出结构体（pub use self::bipartite_matching::BipartiteMatching;）甚至同一模块的多个符号（pub use self::prim::{prim, prim_with_start};）。这层「模块内私有、目录级公开」的封装，让使用方只需use the_algorithms_rust::graph::dijkstra即可调用，而无需关心具体文件布局。

算法文件与测试：同文件、同名的约定

CONTRIBUTING.md 要求算法函数与测试放在同一个文件中：

pub fn my_algorithm() { // ... } #[cfg(test)] mod tests { #[test] fn my_test() { // ... } }

仓库源码忠实地执行了这一约定。以 src/math/greatest_common_divisor.rs 为例，文件内先定义了greatest_common_divisor_recursive、greatest_common_divisor_iterative、greatest_common_divisor_stein三个公开函数，随后在#[cfg(test)] mod tests中分门别类地写了递归、迭代、Stein 算法的正数、负数、混合符号共 8 组测试，覆盖了0与负数等边界情况（如assert_eq!(greatest_common_divisor_recursive(0, -5), 5);）。

测试不止于 assert_eq：属性测试（property testing）

虽然 CONTRIBUTING.md 只给出了#[test]的最小示例，仓库工程已通过 Cargo.toml 的[dev-dependencies]引入quickcheck = "1.0"与quickcheck_macros = "1.0"，用于随机化属性测试。例如 src/data_structures/lazy_segment_tree.rs 的测试模块中，既有针对具体数组的test_min_segments、test_max_segments、test_sum_segments断言式测试（验证区间查询query(4..7)等结果），也有通过#[quickcheck]标注、配合quickcheck::TestResult对随机输入验证线段树性质的属性测试；src/data_structures/probabilistic/bloom_filter.rs 同样大量使用#[quickcheck]与自定义Arbitrary实现。如果你贡献的算法具有可形式化的不变量（如「查询结果与暴力实现一致」），可以参考这些文件引入 quickcheck，把测试质量提升一个台阶。

命名规范：不要使用缩写

CONTRIBUTING.md 特别强调了一条容易踩坑的规则：不要使用缩写，并给出反例——DFS应写作depth_first_search。这与 Rust 官方 API 命名惯例（snake_case 全小写、单词全拼）一致，也与仓库实际代码吻合：遍历图算法在 src/graph/depth_first_search.rs 中命名为depth_first_search，src/graph/breadth_first_search.rs 中的breadth_first_search同理；排序模块里的binary_insertion_sort、cocktail_shaker_sort（见 src/sorting/mod.rs）也都是全拼单词。这意味着新增算法文件、函数、参数、测试函数时，都要避免dfs、bfs、lcs这类缩写，保持全拼。

提交 PR 前的质量门槛：三条命令

CONTRIBUTING.md 规定，提交 Pull Request 前必须依次运行三条命令，并强调「就这些」（And that's about it!）：

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

下面逐一说明其作用与仓库对应的工程配置。

cargo test：验证算法正确性

cargo test编译并运行全部单元测试与属性测试，是验证「算法结果正确」的第一道关卡。仓库的每个算法文件都自带测试模块，因此新增文件后运行该命令即可验证自己的用例，同时确保没有破坏既有模块（例如修改 src/lib.rs 新增模块声明后，整个依赖图的编译与测试都会被检查）。

cargo fmt：统一代码风格

cargo fmt调用rustfmt按官方风格自动格式化代码，消除缩进、换行、空格等风格分歧，让评审者专注于算法逻辑而非格式细节。仓库将格式化直接纳入本地 Git 钩子 git_hooks/pre-commit，其中第一条命令就是cargo fmt——也就是说，在本地git commit之前，代码已经被要求先格式化。

cargo clippy --all -- -D warnings：以零警告收尾

这条命令对整个工作区（--all）运行 Clippy 静态分析，并通过-D warnings把任何 lint 警告升级为编译错误，强制贡献者交付「零警告」代码。仓库为此在 Cargo.toml 中配置了极为细致的[lints.clippy]规则集：以cargo、nursery、pedantic、restriction四组严格 lint 为默认warn，再针对算法代码的实际情况逐条allow掉不适用项（如cognitive_complexity、missing_errors_doc、float_arithmetic、unwrap_used等），形成「严格但不苛求」的平衡；clippy.toml 则通过allowed-duplicate-crates = ["glam"]放行特定依赖重复。理解这套配置，有助于在本地复现 CI 的检查结果——本地跑出的告警，正是仓库维护者会拒绝合并的那一类。

提交前的本地防线：pre-commit 钩子

仓库在 git_hooks/pre-commit 中提供了本地钩子脚本，内容为：

cargo fmt cargo test

将其安装为.git/hooks/pre-commit后，每次git commit都会自动先格式化再跑测试，提前拦截大部分问题；而 Clippy 零警告检查则仍需按 CONTRIBUTING.md 的要求显式执行。

提交清单与工作流小结

综合 CONTRIBUTING.md 与仓库实际工程配置，一个合规的贡献流程可以总结为：

1. 建目录：在 src/ 下按算法类别创建（或沿用既有）分类目录；
2. 写实现：新建my_algorithm.rs，函数全拼命名、避免缩写，内部使用地道的 Rust 写法并尽量泛型化；
3. 写测试：在#[cfg(test)] mod tests中补充覆盖正常与边界情况的#[test]；若算法有可验证的不变量，可参考 src/data_structures/lazy_segment_tree.rs 引入 quickcheck 属性测试；
4. 更新 mod.rs：在分类目录的mod.rs中先mod声明、再pub use导出公开 API（参考 src/graph/mod.rs）；
5. 过三道门：依次运行cargo test、cargo fmt、cargo clippy --all -- -D warnings，确保全部通过、零警告；
6. 提交 PR：提交时说明算法思路与测试覆盖，交由维护者按上述标准评审。

这套规范的价值在于：它以最小化的约定（结构、命名、测试、三条命令）换来了整个仓库的一致性与可持续维护性——任何贡献者都能快速定位代码、放心重构，而 Clippy 配置与 pre-commit 钩子把质量检查前置到了本地，最终让这个拥有 24 大算法分类、数百个算法文件的仓库始终保持统一的代码水准。

• 示例工程