Files
lpt-be/.agents/roles/code-review-checklist.md
T

3.6 KiB
Raw Blame History

后端代码评审清单

  • 功能:列出 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 */ 这种字段取值说明不算违规。