4.7 KiB
后端代码评审清单
- 功能:列出 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 */ 这种字段取值说明不算违规。
并发与性能
9. 循环里发查询(N+1)
for / stream.map / forEach 里出现 selectOne / selectById / selectList / exists 就是违规:请求的 SQL 条数会随
行数或子记录数线性增长,而库在远端,单程 40–80ms。识别方式是看循环体内有没有 mapper 调用、以及列表 DTO 的字段是不是
「每行再查一次」补出来的。改法:收集 id/编号 → 一条 IN 取齐 → 内存建 Map 装饰;聚合类下推 SQL。
2026-11-21 回忆列表(47 → 7 条)、导出范围(4+5×T → 9 条)已按此收敛。
10. 取锁写法会在并发下死锁
同一事务里先 INSERT IGNORE(或普通 INSERT)拿 S 锁、再 SELECT ... FOR UPDATE 升级 X 锁,两个并发请求必然死锁,
表现为接口随机 500,且只在「首次进入页面」这类并发场景出现。识别:锁表的取锁语句是不是两步。
改法见 data-access.md「加锁形态」:锁行可能不存在时用 INSERT ... ON DUPLICATE KEY UPDATE 再 FOR UPDATE,
并用两个并发请求验证。