# 后端代码规范 - **功能**:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。 - **何时用**:新写或改动 `src/main/java` 下的类、`validate` 卡住不知道改什么、评审后端代码、想加规则或降豁免时。 ## 事实来源是配置文件 - 规则的唯一事实来源是 `config/checkstyle/checkstyle.xml`(模块与阈值)与 `config/checkstyle/suppressions.xml`(存量豁免基线)。 本文件只记「取什么值 + 为什么 + 出处」,不复述 Checkstyle 的模块说明,也不抄上游正文;**两者不一致时以配置文件为准**,并回来改这里。 - 门禁形态:`maven-checkstyle-plugin:3.3.1` + `checkstyle:10.12.4`,绑在 `validate` 阶段,`failOnViolation=true`, 只查 `src/main/java`(`includeTestSourceDirectory=false`)。`./mvnw validate` 即触发,跑 `test` / `package` / CI / Docker 构建都会先撞上它。 - 选型、基线与代价见 [Checkstyle 门禁笔记](../notes/implemented/process/2026-11-19-checkstyle-gate.md)。 ## 格式 - **缩进 4 空格,禁 tab**(`FileTabCharacter`)。Google Java Style 是 2 空格、Spring Framework 用 tab,都与本仓既有代码不符; 4 空格是既有代码与 IDE 默认的共同值,换掉要重排全部源文件,收益只在观感。 - **行宽 120**(`LineLength`)。Google 取 100 列,压到 100 会把存量违规从 215 处成倍放大,而 120 列恰好是既有代码排出来的宽度。 - **一行一句、一行一声明**(`OneStatementPerLine`、`MultipleVariableDeclarations`)。出处:Google Java Style §4.3「One statement per line」、 Spring Framework `src/checkstyle/checkstyle.xml` 的 `OneStatementPerLine`。 - **`if` / `for` / `while` / `else` 必须带花括号,即使只有一条语句**(`NeedBraces`)。出处:p3c `NeedBraceRule`。 理由不是风格:省掉花括号后往循环体补第二行是静默改逻辑(新语句落到循环外)。 - **import 不用通配、不留未用与重复**(`AvoidStarImport` / `UnusedImports` / `RedundantImport`)。出处:Google Java Style §3.3.1。 - **文件 ≤ 400 行**(`FileLength`):超了通常说明这个类不止承担一件事,先拆再交。 - **禁 `System.out` / `System.err`**(`RegexpSinglelineJava` 的 `noSystemOut`),日志走 `@Slf4j`。出处:Spring Framework `src/checkstyle/checkstyle.xml` 中的同类检查。 - **其余机械项**:`ModifierOrder`、`ArrayTypeStyle`(写 `String[] a` 不写 `String a[]`)、`UpperEll`(`1L` 不写 `1l`)、 `EmptyStatement`(多余分号)、`OuterTypeFilename`(公有类名必须等于文件名)、`OneTopLevelClass`(一个文件一个顶层类)。 ## 命名 - **类名 UpperCamelCase,只允许字母与数字**(`TypeName`,`^[A-Z][a-zA-Z0-9]*$`):下划线、数字开头都不行;缩写段可以全大写 (`HTTPServer` 能通过,没人要求你写成 `HttpServer`)。出处:p3c `ClassNamingShouldBeCamelRule`、Sonar S101。 - **方法 / 成员 / 局部变量 / 参数一律 lowerCamelCase**(`MethodName`、`MemberName`、`LocalVariableName`、`ParameterName`)。 出处:p3c `LowerCamelCaseVariableNamingRule`、Sonar S100。 - **常量全大写、下划线分隔**(`ConstantName`,`^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`)。出处:p3c `ConstantFieldShouldBeUpperCaseRule`。 - **包名全小写**(`PackageName`,`^[a-z]+(\.[a-z][a-z0-9]*)*$`)。 - **业务名称以上游术语表为准**:库表、实体、DTO 字段由 `lpt-docs/docs/concepts/README.md` 派生,不另起别名(meta `business-terminology.md`)。 - **异常类以 `Exception` 结尾**(p3c `ExceptionClassShouldEndWithExceptionRule`)、**`service/impl` 下的实现类以 `Impl` 结尾** (p3c `ServiceOrDaoClassShouldEndWithImplRule`)。这两条 Checkstyle 查不了,靠评审;没有对应接口的类不该叫 `Impl`,见 `code-review-checklist.md`。 ## 注释 - **类与公共方法写 Javadoc:做什么、边界条件、为什么这么写**。对齐 Spring Framework `SpringJavadocCheck` 关心的项(描述、`@param`、`@return`、`@throws`)。 注释必须跟着签名走:方法被移动或改名时一起搬,别把「取任务名」留在另一个方法头上。 - **注释与用户可见文案用中文**。用户文案另外还要求口语化(见 `api-response.md`)。 - **枚举常量必须带注释**(p3c `EnumConstantsMustHaveCommentRule`)。 - **不留注释掉的代码**(p3c `RemoveCommentedCodeRule`):历史在 git 里,注释掉的代码既不被编译也不会被清理。 ## 复杂度 - **方法 ≤ 80 行**(`MethodLength`)。出处:p3c `MethodTooLongRule` 取同一阈值。 - **参数 ≤ 7**(`ParameterNumber`)。出处:Sonar S107;超了先看是不是该收成参数对象。 - **圈复杂度 ≤ 15**(`CyclomaticComplexity`)。注意这是**圈复杂度**,不是 Sonar S3776 的认知复杂度:两者对不同结构计数不同, S3776 在本仓没有门禁(Checkstyle 不提供这个指标)。Checkstyle 默认阈值是 10,本仓先取 15(10 会把大量普通分支方法打成违规), 存量 6 处靠豁免挂着,往下收用棘轮。 - **嵌套 `if` / `for` / `try` 各 ≤ 3 层**(`NestedIfDepth` / `NestedForDepth` / `NestedTryDepth`);超了用卫语句提前返回。 - **switch 必须有 `default`**(`MissingSwitchDefault`);**重复字面量收敛成常量**(Sonar S1192)是评审项,Checkstyle 没有等价模块。 ## 异常与事务 - **`@Transactional` 必须写 `rollbackFor`**(`RegexpSinglelineJava` 的 `transactionRollback`,正则 `@Transactional(?![^)]*rollbackFor)`)。 出处:p3c `TransactionMustHaveRollbackRule`。默认只对 `RuntimeException` 回滚,受检异常抛出去事务照样提交。 - **不抛裸 `Exception` / `Throwable` / `RuntimeException`**(`IllegalThrows`),自定义异常继承具体基类。出处:Sonar S112。 - **捕获不许吞**(`EmptyCatchBlock` 只放行 `expected` / `ignore` 命名的变量):要么处理,要么记日志再抛。出处:Sonar S1166。 - **不 `printStackTrace()`**(`RegexpSinglelineJava` 的 `noPrintStackTrace`):日志框架之外没有上下文,也没有接收方。出处:Sonar S2139 的意图。 - **`String` 比较用 `equals` 不用 `==`**(`StringLiteralEquality`);**重写 `equals` 必须重写 `hashCode`**(`EqualsHashCode`)。 ## 持久化与接口边界 这三块不在这里复述,各由对应规则文件持有: - **数据访问**(查询结果用类承载、禁 `selectMaps` 取字符串 key、SQL 只留在 mapper、写入形态、实体继承 `BaseEntity`)→ `data-access.md`。 - **出参与入参边界**(Entity 不出 controller、请求体用 DTO 不用 `Map`、未知异常映射 500)→ `api-response.md`。 - **迁移脚本**(Flyway 命名、H2 与 MySQL 的差异)→ `database-migration.md`。 ## 豁免只减不增(ratchet) - **现状:债务豁免为 0**。`suppressions.xml` 里只剩 2 条框架约束(见下节),692 处存量违规已在 2026-11-19 全部改完, 折算为:展开 51 处通配 import、全仓格式化、补 181 处大括号、44 个 `@Transactional` 补 `rollbackFor`、 拆 7 个超长类、抽 6 个复杂方法、改 15 处命名、补 4 个私有构造。 - **新增豁免必须在 PR / 提交说明里写理由**,并说明为什么不能改代码。没有理由的新增豁免等于把门禁关掉一格。 只有「框架规定、改了就坏」才能豁免(见下节两条)。 - 跳闸口只有 `-Dcheckstyle.skip=true`(`failOnViolation` 写死在 pom 里,user property 覆盖不了),**只用于本地应急**; 推之前必须再跑一次 `./mvnw validate`。 ## 什么不算违规 - **Flyway Java 迁移类的类名**(`TypeName`):`V20261115_2__xxx.java` 的版本前缀是 Flyway 规定的,不满足 `^[A-Z][a-zA-Z0-9]*$` 属**正当例外**——不要改类名,也不要改 Flyway 的命名约定。这条以目录级豁免写在 `suppressions.xml`。 - **`LearningProgressTrackerApplication` 的 `HideUtilityClassConstructor`**:它是 Spring Boot 启动入口,只有 `main`、没有实例方法, Checkstyle 按「只有静态成员」的工具类特征判到了。给它加私有构造会让 Spring 测试上下文无法实例化启动类 (实测 164 个测试报 `No visible constructors`),所以只能豁免。 - **名字里的业务缩写**(`taskNum`、`aiTaskNum`):`MemberName` / `ParameterName` 只要求 lowerCamelCase,不要求把缩写展开成 `taskNumber`。 业务名以上游术语表为准,缩写形式同样是术语的一部分。 ## 不采纳的上游规则 | 上游规则 | 不采纳的理由 | |---|---| | p3c `ClassMustHaveAuthorRule` | 模板里的 `@author` 只会被复制粘贴,换手后立刻过期;问「这行是谁写的、为什么」用 `git blame`,答得比注释准。 | | p3c `PojoMustOverrideToStringRule` | 实体与 DTO 统一用 Lombok `@Data`,`toString` 已经生成;再加一条规则只会报假违规。 | | p3c `AvoidNegationOperatorRule` | 会逼出 `x == false` 这种更难读的写法;条件里取反(`!ok` 卫语句)是本项目的正常写法。 | | Google Java Style 的 2 空格缩进与 100 列 | 与本仓既有代码(4 空格、120 列)不符,切换要重排全部源文件,行为不变、评审成本全落在格式噪音上。 | | Spring Framework 的 tab 缩进 | 同上;且 tab 的显示宽度取决于编辑器设置,跨机器看 diff 对不齐。 |