近 7 万星是勋章还是包袱

原创2026-11-12 13:31:15180 阅读
文章标签:示例工程教程

近 7 万星是勋章还是包袱

67,113 star、21,516 fork、6,098 个已提交 PR——这是 TheAlgorithms/Java 在 2026 年 11 月的账面数字。它长期占据“Java 算法学习”搜索结果的头部,也被无数教程当作“第一个能提 PR 的开源项目”。但星数是一个滞后指标:它记录的是过去十年里多少人觉得这个仓库“看起来有用”,而不记录今天维护者审一个 PR 要花多少分钟。这篇文章不谈情怀,只把仓库翻开:用本地源码、CI 配置、豁免清单和最近一个月的 PR 队列,量化一个问题——在 67,113 星的体量下,这个项目的结构还能不能自洽。

一、先看清这颗星到底压在什么结构上

把所有平台无关的叙事剥掉,仓库的真实体积是可以用一条命令量出来的:

find src/main -name '*.java' | wc -l          # 848
find src/test -name '*.java' | wc -l          # 797
find src/main -name '*.java' -exec cat {} + | wc -l   # 88,673
find src/test -name '*.java' -exec cat {} + | wc -l   # 62,750
grep -rho '@Test' src/test --include='*.java' | wc -l # 4,501

848 个主代码文件、8.8 万行实现,配 797 个测试文件、6.2 万行断言、4,501 个 @Test。从比例上看,测试代码量是主代码的 0.71 倍——这个数字在“教学型算法仓库”里其实相当体面,说明项目并没有放任自流。

但分布很说明问题。按包统计主代码文件数:

包 文件数
datastructures 150
maths 143
dynamicprogramming 56
sorts 54
strings 45
ciphers 37
conversions 35
bitmanipulation 35

前两个包吃掉了三分之一的体量。这不是“算法百科”的自然形态,而是贡献者兴趣分布的直接投影:数据结构和数学公式门槛低、边界清晰、一篇博客就能抄到思路,于是堆积最多;而 graph(19 个)、geometry(11 个)、randomized(6 个)这类需要真正建模的领域则长期稀薄。

换句话说,这个仓库的形状不是被设计出来的,是被“什么好写”塑造出来的。这就是理解后面所有维护压力的前提。

二、贡献者结构:从“算法博物馆”变成“PR 流水线”

判断一个高星仓库是否变质,最灵敏的指标不是 star 增速,而是同一类 PR 的密度。

GitHub 上的检索结果给出了一组刺眼的数据:仓库累计 6,098 个 PR,其中 merged 2,463 个,当前 open 26 个。而标题里带 “surface area”(表面积)的 PR 有 98 个;标题完全等于 “Added surface area calculation for pyramid”(为金字塔添加表面积计算)的,有 75 个。

这 75 个 PR 中的绝大多数集中在 2026 年 10 月 28 日到 11 月 3 日这几天,也就是不到一周。它们的标题、正文、甚至未勾选的检查项都高度雷同,个别 PR 的正文里直接写了出处:

“This pull request demonstrates the GitHub code review process for ENGG 4450 Lab 6.”

“Surface area calculation for a pyramid added for a lab example.”

这是典型的课程作业批量投递:几十名学生在同一周、用同一个题目、向同一个仓库提 PR。其中只有 1 个被合并——#6853,作者 JonathanButterworth,2025 年 10 月 30 日合入。其余全部关闭,PR #7729 至今仍开着。

于是问题就露出来了。被合并的那一份实现,在 Area 的球体、立方体、圆柱等十余个方法之间是这样的:

public static double surfaceAreaPyramid(final double sideLength, final double slantHeight) {
    if (sideLength <= 0) {
        throw new IllegalArgumentException("");
    }
    if (slantHeight <= 0) {
        throw new IllegalArgumentException("slant height must be greater than 0");
    }
    double baseArea = sideLength * sideLength;
    double lateralSurfaceArea = 2 * sideLength * slantHeight;
    return baseArea + lateralSurfaceArea;
}

一个空字符串作为异常消息通过了审核并合入主干,而在 AreaTest 里 surfaceAreaPyramid 的命中次数是 0——这行代码至今没有任何测试。与此同时,PR 模板明确要求:

- [ ] All new algorithms include a corresponding test class that validates their functionality.

规则写在模板里,但没有写在 CI 里。78 个 PR 涌进来的那一周,人眼审核的带宽被瞬间抽干,模板上的勾选框就退化成了装饰。这不是某个维护者失职,这是结构缺陷的必然输出。

三、压力一:审核带宽被当成无限资源

仓库的治理结构极其精简。CODEOWNERS 只有一行:

* @DenizAltunkapan @yanglbme @alxkm

三个人的姓名,覆盖 848 个文件、4,501 个测试、所有依赖升级和所有外部 PR。而入口流量是持续的:仅 2026 年 9 月 1 日以来新建的 PR 就有 152 个,平均每天 2 个以上,其中大量是依赖机器人。

于是维护者只能用自动化替代判断,仓库里能清楚看到这套“减负装置”:

  • stale.yml:30 天无活动标记 stale,再 7 天自动关闭,只有打了 dont-close 标签才豁免。
  • close-failed-prs.yml:PR 超过 14 天、没有实质提交(明确排除 merge branch 'master' 这类空同步),且 checks 有失败并已全部完成,就自动评论并关闭。
  • update-directorymd.yml:每次 push 到 master 都用 directory-tree-generator 重新生成 1,606 行的 DIRECTORY.md 并发起 PR,把“维护目录”这项人工劳动彻底外包给流水线。
  • project_structure.yml + check_structure.py:用 26 行 Python 强制所有 .java 必须位于 src/main/java/com/thealgorithms/ 或 src/test/java/com/thealgorithms/ 之下,防止有人把文件丢在根目录。

这套组合相当务实,尤其是自动关闭失败 PR 的脚本——它精准识别出“靠合并 master 制造活跃假象”这个经典套路。但它也暴露了同一个事实:这个项目已经默认自己无法逐个人工处理 PR,只能靠定时任务清理积压。

自动化能清理噪音,却不能提升合入质量。上面那个空异常消息就是证据:CI 全绿、格式合规、文件名 PascalCase,于是自动化放行,人也没有余力再看一眼。

四、压力二:正确性债务在暗处累积

第二个压力来自“教学代码”本身的特殊性:它被当作参考实现阅读,所以错误会被复制。

最近两个月的 PR 队列里,修复类提交占据主流,且很多是基础算法级别的错误:

  • 哈希溢出:RabinKarpAlgorithm 的滚动哈希用 int 存储,当模数取常见的 1_000_000_007 时乘法溢出。提交者在 5,000 组随机文本上验证,1,110 组返回了错误下标(PR #7665,改为 long)。
  • 字符集假设:BoyerMoore 用长度 256 的数组做坏字符表,遇到中文直接 ArrayIndexOutOfBoundsException: Index 20013 out of bounds for length 256(PR #7664,改为 HashMap<Character, Integer>)。
  • 死循环:SwapSort 在遇到重复值时两个相同元素互相交换,{2, 2, 1, 1, 0, 0, 0} 永不终止(PR #7660)。
  • 丢数据:TreeSort 依赖的 BST 会忽略重复键,sort({-1, -1, 0}) 返回 [-1, 0, 0](PR #7661)。
  • 数值精度:CatalanNumbers 用 long 算阶乘,catalan(11) 返回 -65 而非 58786(PR #7732)。
  • 参数校验:BinomialCoefficient 传入负数时无限递归至 StackOverflowError;CatalanNumber 在 n = 0 时抛 ArrayIndexOutOfBoundsException(PR #7730、#7731)。
  • 公式写错:DistanceFormula.euclideanDistance 里 dY 用了 Math.pow(y2 - x1, 2),把 y1 误写成 x1(PR #7747)。
  • 静默错误:HexToOct.hexToDecimal("1G") 因为 indexOf 返回 -1,直接算出 15,不报错(PR #7748)。

这些不是“风格问题”,而是会让读者把错误结论抄进生产代码的缺陷。有些已经落地修复——比如 CatalanNumbers.java 现在内部用 BigInteger 计算阶乘,再用 longValueExact() 收口:

return factorial(2 * n).divide(factorial(n + 1).multiply(factorial(n))).longValueExact();

但有些还在路上。当前主干的 Pow.java 仍然是:

long result = 1;
for (int i = 1; i <= b; i++) {
    result *= a;
}
return result;

pow(2, 63) 会静默回绕成负数。PR #7752 提议改用 Math.multiplyExact,至今仍在 open 队列里等审核。这类“已知未修”的条目,正是 26 个 open PR 背后的真实内容——不是没人发现,是没人有时间。

五、压力三:一致性靠豁免清单硬撑

第三个压力最隐蔽,但最能说明结构性疲劳。

这个项目的静态检查配置其实非常激进。pom.xml 里编译器参数是:

<compilerArgs>
    <arg>-Xlint:all</arg>
    <arg>-Xlint:-auxiliaryclass</arg>
    <arg>-Werror</arg>
</compilerArgs>

-Werror 意味着任何 lint 警告都直接中断构建。再加上 build.yml 依次执行 mvn verify、mvn checkstyle:check、mvn spotbugs:check、mvn pmd:check,四道闸门串行。对 848 个文件的教学仓库来说,这个标准比很多商业项目还严。

严标准的代价立刻体现在豁免文件上:

  • pmd-exclude.properties:111 行,逐类逐规则豁免。其中 UselessMainMethod 出现 65 次,UselessParentheses 出现 52 次。
  • spotbugs-exclude.xml:59 条 <Match> 规则。
  • 主代码里仍有 64 个文件保留着 public static void main。

也就是说,为了通过检查,项目维护了一份和代码规模同步膨胀的“白名单”。这不是偷懒,恰恰是 PMD 的 UselessMainMethod 和 UselessParentheses 与教学代码天然冲突:教学代码需要 main 演示、需要括号表达运算顺序,而工具按生产代码的审美判它们为冗余。规则与目标不匹配,最后只能一条条豁免。

更耐人寻味的是 checkstyle.xml 里的注释:

<!-- TODO <module name="FileLength"/> -->
<!-- TODO <module name="LineLength">
  <property name="fileExtensions" value="java"/>
</module> -->

文件长度和行长度检查被 TODO 掉了,Header 检查也被注释。原因不难猜:AES.java 有 2,781 行,Blowfish.java 有 1,244 行,开了行宽限制整个密码学包都要重排。规则的缺席不是疏忽,是规模倒逼的妥协。

同样的问题在结构层面复现:主代码里有 7 组同名文件跨包并存——

searches/BoyerMoore.java          others/BoyerMoore.java
greedyalgorithms/CoinChange.java  dynamicprogramming/CoinChange.java
matrix/matrixexponentiation/Fibonacci.java  dynamicprogramming/Fibonacci.java
bitmanipulation/GenerateSubsets.java        recursion/GenerateSubsets.java
bitmanipulation/HammingDistance.java        strings/HammingDistance.java
datastructures/Node.java  datastructures/disjointsetunion/Node.java  devutils/nodes/Node.java
geometry/Point.java       lineclipping/utils/Point.java

同名不同义在 Java 里不算错误,但对“按目录浏览学习”的仓库来说,这是认知负担:读者无法通过类名判断该看哪一个,也无法从 DIRECTORY.md 的 1,606 行目录里快速建立心智模型。

六、如果重来一次,结构该怎么设计

把上面的证据串起来,可以给出四条不依赖情怀的结构性修正。它们都能在当前仓库里找到落点,不需要推倒重来。

第一,把准入条件从模板搬进 CI。

现在“必须有测试类”只是 PR 模板 里一个可勾可不勾的复选框。它应该变成可执行的门禁。pom.xml 里已经有 JaCoCo:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.16</version>
    ...
</plugin>

但只配置了 prepare-agent 和 report,没有 check 目标,也没有 <rules>——覆盖率只上报到 Codecov,从不阻断合并。补一条“新增文件行覆盖率不得低于 X%”的规则,比在模板里写十行提示有效得多。至少,Area.surfaceAreaPyramid 那个空异常消息不会在零测试的情况下进主干。

第二,让“一个算法一个包”成为硬约束。

check_structure.py 现在只校验“文件是否在 src/main/java/com/thealgorithms/ 之下”,这拦住了最粗暴的错误,但拦不住同名类泛滥。既然 searches 已经有 SearchAlgorithm 接口、sorts 已经有 SortAlgorithm 接口和共用的测试基类,那么把“每个算法一个独立子包 + 必须实现统一接口 + 测试必须继承共用基类”写进结构检查,就能把一致性从人评审变成机器判决。

第三,把仓库显式切成两层。

这个仓库同时在服务两种完全不同的需求:一是“查一个正确、可读、带 Wikipedia 链接的参考实现”,二是“练手、提 PR、跑 CI”。两者的质量标准和评审成本差一个数量级,混在一起就必然互相拖累——金字塔表面积的 75 个作业 PR,污染的是第一层。

显式分层是低成本解法:education 层只接受带测试、带出处、带复杂度说明的实现,采用严格门禁;playground 或 exercises 层接受课程作业与练习,单独 CI、不进 DIRECTORY.md、不占主干评审带宽。这样既不打击新人,也不让 8.8 万行的参考库为一次课堂作业承担信誉风险。

第四,把豁免清单当成技术债指标来运营。

pmd-exclude.properties 的 111 行、spotbugs-exclude.xml 的 59 条、checkstyle.xml 里被注释掉的 FileLength/LineLength/Header,本质上是同一件事:规则与目标不匹配,于是用文件对抗工具。健康的做法不是继续加行数,而是分两类处理——规则本身不适合教学代码的(如 UselessMainMethod),从规则集里正式关掉并写清原因;代码本身该改的(如 UselessParentheses),限期清理。让这份清单只减不增,它就从遮羞布变成了进度条。

七、勋章与包袱之间,只隔一层结构

67,113 颗星不是虚的。它换来的是 848 个经过 -Werror 与四重静态检查的实现、4,501 个测试用例、以及一个 2016 年至今仍在每天合并 PR 的活体项目。这些是勋章。

但同一组数字也标出了包袱的重量:6,098 个 PR 里只有 2,463 个被合并,75 个同题作业 PR 里只有 1 个通过且留下了未覆盖的空异常消息,111 行 PMD 豁免和 59 条 SpotBugs 例外在为主干背书,三个人名覆盖全部 CODEOWNERS,Pow 的溢出修复还排在 26 个 open PR 里等一个空闲的下午。

区别不在于星多星少,而在于规则是否可执行。写在模板里的规则会被洪水冲走,写进 CI 的规则会留下来。这个仓库过去十年靠“人不忍心拒绝”扩张到 8.8 万行,接下来的十年只能靠“机器不允许放行”维持可信度。勋章可以继续挂,但包袱得先卸下来。

登录后查看全文
Java