docs: 补齐代码规范与评审清单,记录 HTTP 边界与 Checkstyle 决策
This commit is contained in:
@@ -0,0 +1,49 @@
|
|||||||
|
# Agent Note: HTTP 边界不再返回实体,入参改用请求 DTO
|
||||||
|
|
||||||
|
Status: implemented
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
接口层的类型直接复用了持久化实体与 `Map`,导致三件事同时发生:
|
||||||
|
|
||||||
|
- **实体即契约**:`CommonResult<TaskApplicationEntity>` 这类返回把库表形状暴露成 API。实体加一个字段就等于改接口,
|
||||||
|
而 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted` 这些列本来就不该出现在响应里。
|
||||||
|
- **`Map<String, String>` 当请求体**:10 个端点用 `@RequestBody Map`,字段名只在 `body.get("xxx")` 里出现,
|
||||||
|
拼错 key 不报错、无法被 Bean Validation 校验、OpenAPI 文档里是空对象。
|
||||||
|
- **实体当请求体**:`savePriorityWeights(@RequestBody UserPriorityWeightsEntity)` 让调用方能顺手改 `id`、`createdBy`。
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
在 controller 边界做转换,service 层签名不动:
|
||||||
|
|
||||||
|
- 出参:`dto/response/<东西>Response`,字段与实体同名(类型不变),另带 `createdTime` / `lastModifiedTime`;
|
||||||
|
不含 `createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`。每个类提供 `static of(Entity)` 工厂,实体为 null 时返回 null。
|
||||||
|
- `Page<Entity>` 返回:`new Page<>(current, size, total)` + `setRecords(records.stream().map(X::of).toList())`。
|
||||||
|
- 入参:`dto/request/<动作>Request`,字段名与原先 `body.get("key")` 的 key 完全一致;必要字段加 `@NotBlank` 并在 controller 上 `@Valid`。
|
||||||
|
- 局部更新改用 `update(new Entity(), lambdaUpdate().set(...))`,显式写「改哪几列」,不再依赖 MyBatis-Plus 的全局 null 策略;
|
||||||
|
传入空实体是为了让 `MetaObjectHandler` 继续填 `lastModifiedBy` / `lastModifiedTime` / `deviceInfo`。
|
||||||
|
|
||||||
|
## Alternatives considered
|
||||||
|
|
||||||
|
**① 直接在 service 层返回 DTO,controller 只透传。**
|
||||||
|
最强理由:转换点更靠里,controller 变薄,未来换实现(比如加缓存层)时不用再改 controller。
|
||||||
|
否掉的原因:service 接口与实现遍布 40 多个类,签名一改要跟着改 600 多个测试与所有调用方;
|
||||||
|
而「实体不出 controller」这条约束只需要在边界做一次转换就成立。等真有了第二个入口(gRPC、MQ handler)再下沉不迟。
|
||||||
|
|
||||||
|
**② 让实体自己 `@JsonIgnore` 掉审计列,不建 DTO。**
|
||||||
|
最强理由:改动最小,一个注解解决泄漏,响应体里也不会再有 `createdBy`。
|
||||||
|
否掉的原因:注解只解决序列化,解决不了「实体能当请求体」和「库表形状即契约」;而且把 API 决策藏在实体里,
|
||||||
|
以后 lpt-ai 或内部服务需要这些列时会互相拉扯。
|
||||||
|
|
||||||
|
**③ 保留 `Map` 请求体,只加 `@Valid` 常量约束。**
|
||||||
|
最强理由:不动前端契约,也没有 10 个新类。
|
||||||
|
否掉的原因:`Map` 拿不到字段级校验与文档,`body.get("markerName")` 拼错永远是 null;
|
||||||
|
本轮恰好要为 18 个出参加 DTO,入参顺手一起做,边际成本远低于再开一轮。
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
- 响应体少了 4 个字段(`createdBy` / `lastModifiedBy` / `deviceInfo` / `deleted`)。已核对 `lpt-fe`:
|
||||||
|
这 4 个字段零使用,`createdTime`(16 处)与 `lastModifiedTime`(2 处)保留,前端无需改动。
|
||||||
|
- service 仍返回实体,controller 里多了一次映射调用;`Page` 需要手工重建(MyBatis-Plus 的 `convert` 返回 `IPage`,类型对不上)。
|
||||||
|
- 请求 DTO 里加了 `@NotBlank`,校验失败的文案由 DTO 决定;原本由 service 抛 `ErrorParameterException` 的路径仍在(DTO 未覆盖的语义校验)。
|
||||||
|
- 回归由 608 个测试守住;改动后 `./mvnw validate` 仍为 0 违规。
|
||||||
@@ -0,0 +1,117 @@
|
|||||||
|
# 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` 的「启动命令」节。
|
||||||
@@ -11,6 +11,17 @@
|
|||||||
- 参数校验失败:`MethodArgumentNotValidException`,code=400。
|
- 参数校验失败:`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 转换
|
## DTO 转换
|
||||||
|
|
||||||
- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。
|
- MapStruct 编译期生成 `*ConvertImpl.java`,同名属性自动映射。
|
||||||
|
|||||||
@@ -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 */` 这种字段取值说明不算违规。
|
||||||
@@ -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 对不齐。 |
|
||||||
@@ -17,3 +17,18 @@
|
|||||||
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
|
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
|
||||||
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
|
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`)
|
||||||
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
|
- 反向约束:`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。
|
||||||
|
|||||||
@@ -8,7 +8,9 @@
|
|||||||
- 命名:业务概念的英文名以 `lpt-docs/docs/concepts/README.md` 术语表为准,库表、实体、DTO 字段由它派生,不另起别名(规则见 meta `.agents/roles/business-terminology.md`)。
|
- 命名:业务概念的英文名以 `lpt-docs/docs/concepts/README.md` 术语表为准,库表、实体、DTO 字段由它派生,不另起别名(规则见 meta `.agents/roles/business-terminology.md`)。
|
||||||
- 本仓库专属规则:`.agents/roles/`
|
- 本仓库专属规则:`.agents/roles/`
|
||||||
- `.agents/roles/database-migration.md`:数据库迁移(Flyway Migration)
|
- `.agents/roles/database-migration.md`:数据库迁移(Flyway Migration)
|
||||||
- `.agents/roles/data-access.md`:编码规范 · 数据访问层
|
- `.agents/roles/code-standards.md`:后端代码规范的取值与出处(Checkstyle 门禁、棘轮、不采纳的上游规则)
|
||||||
|
- `.agents/roles/code-review-checklist.md`:Checkstyle 查不了、必须人看的评审项(实体出 controller、Map 请求体、patch 更新等)
|
||||||
|
- `.agents/roles/data-access.md`:编码规范 · 数据访问层与写入形态
|
||||||
- `.agents/roles/api-response.md`:响应规范、DTO 转换
|
- `.agents/roles/api-response.md`:响应规范、DTO 转换
|
||||||
- `.agents/roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01)
|
- `.agents/roles/ownership-and-markers.md`:内容归属与结构化报告(归属-01 / 报告-01)、标记(标记-01)
|
||||||
- `.agents/roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02)
|
- `.agents/roles/ai-integration.md`:学习引导(复习-06)、AI 异步链路(AI-02)
|
||||||
@@ -198,8 +200,15 @@ lpt-be/src/main/java/com/guo/learningprogresstracker/
|
|||||||
```bash
|
```bash
|
||||||
mvn clean compile -DskipTests # 编译(需要 JDK 17)
|
mvn clean compile -DskipTests # 编译(需要 JDK 17)
|
||||||
mvn spring-boot:run # 启动(默认 profile: local)
|
mvn spring-boot:run # 启动(默认 profile: local)
|
||||||
|
./mvnw validate # 先跑 Checkstyle,违规即失败
|
||||||
```
|
```
|
||||||
|
|
||||||
|
- **Checkstyle 门禁**:`./mvnw validate` 会先跑 Checkstyle(绑 `validate` 阶段,`failOnViolation=true`,只查 `src/main/java`),
|
||||||
|
`test` / `package` / CI / Docker 构建都会先撞上它。配置在 `config/checkstyle/`:`checkstyle.xml` 是规则与阈值,
|
||||||
|
`suppressions.xml` 是存量豁免基线(改到被豁免的文件时顺手删掉对应豁免行)。
|
||||||
|
- **应急跳闸**:`-Dcheckstyle.skip=true` 只用于本地临时绕过(`failOnViolation` 写死在 pom,user property 覆盖不了),
|
||||||
|
推之前必须再跑一次 `./mvnw validate`。规则取值、理由与出处见 `.agents/roles/code-standards.md`。
|
||||||
|
|
||||||
## 关联项目
|
## 关联项目
|
||||||
|
|
||||||
| 项目 | 路径 | 端口 | 说明 |
|
| 项目 | 路径 | 端口 | 说明 |
|
||||||
|
|||||||
Reference in New Issue
Block a user