# 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 的 `` + 配置里的 `${checkstyle.suppressions.file}`。不用 `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` 是唯一事实来源,文档只解释「为什么」。 ### 为什么基线粒度是「文件 × 规则」 - **整文件豁免**(`` 不带 `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` 的「启动命令」节。