docs: 补齐代码规范与评审清单,记录 HTTP 边界与 Checkstyle 决策

This commit is contained in:
2026-11-20 09:36:38 +08:00
parent ec2f74bf18
commit 5310f480ce
7 changed files with 356 additions and 1 deletions
+11
View File
@@ -11,6 +11,17 @@
- 参数校验失败:`MethodArgumentNotValidException`,code=400。
- 用户可见错误文案必须口语化、可理解,避免“无法生成”“不存在”等技术化表述;技术细节写入日志。例如无学习报告时应提示“这个任务还没开始学习哦,学习后产生学习报告后再来吧”,而不是“没有学习报告,无法生成思维导图”。
## 出参和入参的边界
- **实体不出 controller**:`CommonResult<XxxEntity>`、`CommonResult<Page<XxxEntity>>` 都不行,出参一律是 `dto/` 下的类。
实体带租户与审计列,库表形状一改就直接击穿 API 契约,前端还得跟着改。
- **请求体用 DTO,不用 `Map<String, String>`**:`Map` 丢类型、丢校验、丢字段名,只能在 service 里 `get("xxx")` 拼字符串;
每个端点一个 request DTO + `@Valid`。
- **`CommonResult` 不写裸类型**:一律 `CommonResult<T>`,哪怕是错误分支也给出 `data` 的类型;裸类型在生成文档与前端类型推导上都退化成 `any`。
存量:`GlobalExceptionHandler` 的 7 个 handler 仍是裸 `CommonResult`。
- **未知异常映射 500**:`@ExceptionHandler(Exception.class)` 返回 `CommonResult.serverError`(code=500),不能复用参数错误的 400,
否则系统故障被说成「参数不对」。存量:该兜底 handler 现在返回 400。
## DTO 转换
- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。
+49
View File
@@ -0,0 +1,49 @@
# 后端代码评审清单
- **功能**:列出 Checkstyle 查不了、必须人看才能发现的后端坏味道,每条给出识别方式、改法与当前数量。
- **何时用**:评审 lpt-be 的 PR、改 controller / service / mapper、自查交付前;机械格式与命名问题交给 `./mvnw validate`,不在这里重复。
## 出参与入参
### 1. Controller 出参不出现实体
`CommonResult<XxxEntity>`、`CommonResult<Page<XxxEntity>>` 都算违规;实体带租户与审计列,库表形状一改就击穿 API 契约。
出参放 `dto/`。存量 18 个端点已于 2026-11-19 清零(改为 `dto/response`),新代码别再引入;历史例子: `TaskController#getPriorityWeights`、`StudySessionController#getTaskFragments`。
### 2. 请求体不用 `Map<String, String>`
看到 `@RequestBody Map<String, String> body` 再 `body.get("xxx")` 就是违规:类型、校验、字段名的编译期保护全丢。
每个端点建一个 request DTO + `@Valid`。存量 10 处已于 2026-11-19 清零(改为 `dto/request`);历史例子: `MarkerController#addUserTag`、`ReviewController#saveSortPreference`。
### 3. 局部更新要说清「清空」还是「不动」
`new XxxEntity()` + 只 `set` 变了的字段 + `updateById` 是 patch 实体式更新:想表达的「清空」落不了库(null 被跳过),
行为还依赖全局 null 策略。整对象替换 / `LambdaUpdateWrapper.set(...)` / `XxxPatch` DTO 三选一。存量 17 处已于 2026-11-19 清零(改为 `lambdaUpdate().set(...)`);历史例子: `ReviewServiceImpl#updateReport`、`ReviewServiceImpl#submitFeedback`。
### 4. SQL 不拼字符串
`.last("LIMIT " + n)`、`apply("name = '" + x + "'")` 这类拼接一律违规,哪怕当前值来自内部常量——下一个人会传用户输入。
能参数化就用 `{0}` 占位,表达不了下沉到 mapper 的自定义 SQL。存量 3 处已于 2026-11-19 清零(改用 `selectPage`);历史例子: `ReviewServiceImpl` 与 `ReviewRecallService` 的 `last("LIMIT " + n)`。
### 5. 未知异常映射 500,不伪装成 400
`@ExceptionHandler(Exception.class)` 返回 `CommonResult.error(...)`(code=400)会把系统故障说成「你参数不对」,用户反复重试、值班查不到。
未知异常走 `CommonResult.serverError`(code=500),技术细节写日志。存量已于 2026-11-19 修正:兜底 handler 现在返回 `serverError`(500)。
## 分层与命名
### 6. `service/impl` 只放 `service/` 接口的实现
包名写 `impl` 却没有对应接口的类(`RecallJson`、`AiTaskParams`、`ReviewRecallStore`、`AiServiceClient` 这类工具或客户端也算)就是放错位置:
无接口就别用 `Impl` 后缀,也别放这个包,挪到 `service/`、`client/` 或调用方内部。存量 34 个已于 2026-11-19 挪出 `service/impl`(`service/ai`、`service/recall`、`service/review`、`service/session`)。
### 7. 注释跟随签名,不跟随历史
Javadoc 描述的方法名、参数、返回跟下面那个方法对不上就是违规——例如 `ReviewServiceImpl:371` 的「取任务名」挂在 `submitFeedback` 上。
方法移动、改名、改签名时把注释一起搬;过期注释比没有注释更贵。
### 8. 注释与用户可见文案统一中文
新增英文注释、或把中文提示改成英文都算违规:这个项目的用户文案与注释都是中文,混语种会在同一屏里跳出来。
用户文案还要求口语化(见 `api-response.md`)。历史情况(2026-11-19 前)是混排:`ReviewRecallController:21`、`LoginResult:21` 这类成句英文注释要翻成中文;
`/** REPORT | FRAGMENT */` 这种字段取值说明不算违规。
+105
View File
@@ -0,0 +1,105 @@
# 后端代码规范
- **功能**:说明本项目在格式、命名、注释、复杂度、异常与事务上取哪些值、为什么这样取、出处在哪。
- **何时用**:新写或改动 `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 对不齐。 |
+15
View File
@@ -17,3 +17,18 @@
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
## 写入形态
- **禁 patch 实体式更新**:不要 `new XxxEntity()` + 只 `set` 变化字段 + `updateById` 就走。两个理由:一是字段清不空——本仓
未显式配 `update-strategy`,MyBatis-Plus 默认跳过 null 字段,用户点了「清空备注」库里的值还在;二是语义依赖全局配置,
那个默认值改一次,全库的 patch 更新行为一起变且不报错。要局部更新先分清是哪种,三选一:
- **整对象替换**:先查到完整实体、改完字段、`updateById`——适合「表单提交整张卡」的场景。
- **`LambdaUpdateWrapper.set(...)`**:需要显式写 null(真清空)时用,意图写在 `.set(field, null)` 上。
- **`XxxPatch` DTO**:由请求对象表达「哪些字段有值才改」,与 `api-response.md` 的入参规范对齐。
现状 17 处 patch 写法(全仓 27 处 `updateById`,其余是整对象更新),例 `ReviewServiceImpl#updateReport`、`ReviewServiceImpl#submitFeedback`。
- **实体统一继承 `BaseEntity`**:`created_by` / `created_time` / `last_modified_by` / `last_modified_time` / `device_info` / `deleted`
由 `config/AutoTableField` 自动填充与 `@TableLogic` 软删除接管。不继承就少审计列,`created_by` 缺失还会让租户拦截器无列可加。
现状:`entity/` 下 19 个业务实体全部继承(`entity/` 的第 20 个文件是 `BaseEntity` 本身)。
- **SQL 只出现在 Mapper**:service 里不拼 SQL 字符串(当前 3 处 `.last("LIMIT " + n)` 属存量违规,见 `code-review-checklist.md`);
需要分页/限量时用参数化占位符,或用 `Page` / `IPage`,再不行下沉到 mapper。