# 后端代码评审清单 - **功能**:列出 Checkstyle 查不了、必须人看才能发现的后端坏味道,每条给出识别方式、改法与当前数量。 - **何时用**:评审 lpt-be 的 PR、改 controller / service / mapper、自查交付前;机械格式与命名问题交给 `./mvnw validate`,不在这里重复。 ## 出参与入参 ### 1. Controller 出参不出现实体 `CommonResult`、`CommonResult>` 都算违规;实体带租户与审计列,库表形状一改就击穿 API 契约。 出参放 `dto/`。存量 18 个端点已于 2026-11-19 清零(改为 `dto/response`),新代码别再引入;历史例子: `TaskController#getPriorityWeights`、`StudySessionController#getTaskFragments`。 ### 2. 请求体不用 `Map` 看到 `@RequestBody Map 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`, 并用两个并发请求验证。