Files
lpt-be/.agents/notes/implemented/process/2026-11-19-checkstyle-gate.md
T

9.4 KiB
Raw Blame History

Agent Note: 用 Checkstyle 在 validate 阶段阻断代码坏味道

Status: implemented

Problem

格式、命名、复杂度、事务回滚这些坏味道,之前只存在于文档与评审习惯里,没有任何机械检查。结果是写了没人查: 全仓存量 692 处违规,横跨 149 个「文件 × 规则」组合,其中 215 处超 120 列、181 处单行语句不带花括号、 154 处一行写多条语句、42 处 @Transactional 缺 rollbackFor(受检异常抛出去时事务照样提交)。

人工评审兜不住,原因不在态度:

  • 一个 PR 的注意力预算有限,几十行格式差异会把真正的行为变更埋掉;
  • 同一条规则要在每次评审里重复提,提的人会累,被提的人会当噪音;
  • 有些违规(缺 rollbackFor、System.out、空 catch)在 diff 里根本不显眼,看见了也容易划过去。

Decision

把能机械判定的纪律交给构建,绑在 validate 阶段阻断,而不是写成文档等自觉。

  • 工具:maven-checkstyle-plugin:3.3.1 + checkstyle:10.12.4,goal 为 check,绑 validate, failOnViolation=true。违规即构建失败,不是警告。
  • 范围:只查 src/main/java(includeTestSourceDirectory=false)。测试里的长断言行、lambda 内联会制造大量假违规, 而假违规会把人训练成习惯性跳过检查。
  • 存量:先用 suppressions.xml 做 文件 × 规则 基线落地(149 条豁免覆盖 692 处),随后在同一天把 692 处全部改完, 基线缩到 2 条框架约束(见「豁免的现状」)。
  • 基线加载:pom 的 <suppressionsLocation> + 配置里的 ${checkstyle.suppressions.file}。不用 <propertyExpansion>config_loc=... 这种更常见的写法:maven-checkstyle-plugin:3.3.1 把 propertyExpansion 当 properties 文本走 Properties.load(InputStream) (ISO-8859-1),路径里含中文就变乱码(本仓路径含「系统」,实测报 Unable to find: /run/media/cat/系统/...)。 suppressionsLocation 走 plexus ResourceManager 按 basedir 解析,不经那段,含中文路径与任意 CWD 都成立。
  • 阈值:行 120、方法 80 行、文件 400 行、参数 7、圈复杂度 15、嵌套 if/for/try 各 3。
  • 跳闸口:-Dcheckstyle.skip=true,只用于本地应急(failOnViolation 写死在 pom,user property 覆盖不了它的语义)。
  • 文档分工:规则取值与出处进 .agents/roles/code-standards.md;工具查不了但必须人看的项进 .agents/roles/code-review-checklist.md。config/checkstyle/checkstyle.xml 是唯一事实来源,文档只解释「为什么」。

为什么基线粒度是「文件 × 规则」

  • 整文件豁免(<suppress files="..."> 不带 checks)最省事,但它让那个文件所有规则一起失效: 一个 800 行的老 controller 被整文件豁免后,新写的 System.out 与缺 rollbackFor 全放过,等于给最脏的文件开最大口子。
  • 行号豁免(beginLine / endLine)精度最高,但行号随每次编辑漂移:上面插一行,豁免就落到别的语句上, 或者干脆失效。维护基线的成本会超过改代码本身,而且漂移是静默的。
  • 文件 × 规则 的精度刚好落在可用区间:豁免的是「这个文件在这条规则上的存量」,同一文件的其他规则照样生效; 改到该文件时删掉这一行,就能立刻看到它在这条规则上的真实状态。棘轮规则(豁免只减不增)成立。

豁免的现状

suppressions.xml 只剩两条,都是「框架规定、改了就坏」,不是债务:

豁免 为什么必须豁免
db/migration/** 的 TypeName Java 迁移类的类名由 Flyway 规定为 V20261115_2__xxx,改了就等于让 Flyway 认为已有迁移消失
LearningProgressTrackerApplication 的 HideUtilityClassConstructor 启动类只有 main;给它加私有构造后 Spring 测试上下文无法实例化,实测 164 个测试报 No visible constructors

692 处是怎么清零的(都是改代码,不是加豁免):

规则 数量 做法
LineLength / OneStatementPerLine / MultipleVariableDeclarations / 未用与重复 import 388 全仓跑 palantir-java-format(4 空格 / 120 列),再人工收尾 1 处长行
NeedBraces 181 先按行处理单语句体(128 处),再用 Checkstyle 报告的行号精确包住多行体(52 处),剩 4 处手改
AvoidStarImport 51 脚本按「文件里用到的类名 ∩ 包内类名」展开成显式 import,共 27 个文件
transactionRollback 42 给 44 个 @Transactional 补 rollbackFor = Exception.class;正则加 \b 避免误伤 @TransactionalEventListener
FileLength 5 拆出 ReviewFeedService、ReviewStatsService、TagDictionaryService、StudySessionConvergenceService、StudyReportDraftService、RecallExpressionValidator、MindMapMatchTool
CyclomaticComplexity 6 主干只做分发,分支下沉为私有方法
ParameterNumber 1 9 参数方法收成 SourceContext record
命名 / 构造器 / System.out 15 reportFragmentsController→ReportFragmentsController、mapStruct→mapstruct、3 个异常处理方法改名、3 个工具类补私有构造、启动打印改 log.info

验证方式:./mvnw validate 输出 You have 0 Checkstyle violations,./mvnw test 为 608 个测试全绿。 过程中两次被测试挡住并纠正:「给启动类加私有构造」与「@TransactionalEventListener 被正则误伤」,都已回退/修正。

Alternatives considered

① 先把 692 处存量改干净,再一次性开闸。 最强理由:门禁就该一把落地,基线豁免本质是技术债登记册,「以后再改」在实践中等于永远不改;而且一次格式化能顺手把风格统一掉, 比留 149 条豁免干净得多。 否掉的原因:692 处改动会和真正的功能改动混在同一批提交里,评审无法分辨哪些是行为变更。LineLength 与 NeedBraces 要求重排语句,重排中混进一个改了分支的差异几乎必然漏过,而格式改错只会由特定输入暴露,测试覆盖不到。 先开闸再棘轮,评审看到的是「删掉一行豁免 + 改动这一处」,可分辨。

② 引入 p3c-pmd(阿里 Java 规约的 PMD 实现)。 最强理由:规则更贴中文团队习惯(异常命名、常量命名、事务回滚、枚举注释本就是我们引用的上游),规则集覆盖面比这份 Checkstyle 配置更广, 还能一次拿到 CognitiveComplexity 这类 Checkstyle 没有的检查。 否掉的原因:p3c-pmd 的 PMD 版本锁在 6.15,而 CognitiveComplexity 需要 6.35+,两者在同一套 PMD 里只能择一; 且引入第二套工具链意味着两份配置、两套豁免、两倍检查时间,换来的增益与已选的 Checkstyle 模块高度重叠。

③ 接 SonarQube。 最强理由:规则最全(认知复杂度、重复字面量、异常被吞、覆盖率趋势),有界面能看历史与责任人,在多人的项目里权威性最高。 否掉的原因:要维护一个实例(数据库、升级、token、webhook),对个人项目这份运维成本不成比例;而且它擅长的是事后看板, 不是 mvn package 时的阻断——要的是「提交前就红」,不是一个每周打开看一眼的面板。

④ 只写规则文档,不加门禁。 最强理由:成本最低,不改构建时间、不需要豁免、不引入工具链;而且文档能解释「为什么这样写」,工具只能报「哪里错了」。 否掉的原因:这正是当前失效的原因——692 处存量违规就是「写了没人查」的直接证据。文档与工具是分工不是替代: 工具查能机械判定的,文档解释为什么,两者都要有。

Consequences

代价:

  • 豁免仍是「文件 × 规则」,将来若被迫新开豁免,被豁免的文件在那条规则上会裸奔;所以新增豁免必须写理由(现状是 0 条债务豁免)。
  • 跳过开关存在且好按。遇到「先发出去」的场合会被用,只能靠 PR 说明与 ./mvnw validate 复跑约束。
  • 测试代码完全不查,测试里的长行、魔法数字、System.out 仍然是人的活。
  • 构建多了一步(秒级),第一次撞上 400 行 / 80 行阈值的类会被迫先拆或先加豁免,这个摩擦是真实的。

收益:

  • 新文件零豁免:新建的类一违反就红,不需要任何人先记住规则。
  • validate 在 package 之前,mvn -f、CI 的 docker build(Dockerfile 里跑 mvn package -DskipTests)都拦得住。
  • 豁免清单本身就是可数的债务看板:149 条、692 处,改动前后能直接对比。
  • 规则取值有了唯一事实来源,文档不必复述模块说明;上游出处(Google Java Style、Spring、p3c、Sonar)写在 code-standards.md 里, 下一次加规则有据可依。

Verification

  • 构建配置:pom.xml 的 maven-checkstyle-plugin 执行段(checkstyle-validate)。
  • 规则与阈值:config/checkstyle/checkstyle.xml;基线:config/checkstyle/suppressions.xml。
  • 触发:./mvnw validate,失败时输出 文件:行 与规则名。
  • 文档:.agents/roles/code-standards.md、.agents/roles/code-review-checklist.md、AGENTS.md 的「启动命令」节。