Files
lpt-be/.agents/roles/code-standards.md
T

106 lines
9.5 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.
# 后端代码规范
- **功能**:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。
- **何时用**:新写或改动 `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 对不齐。 |