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

118 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` 的「启动命令」节。