50 lines
3.6 KiB
Markdown
50 lines
3.6 KiB
Markdown
# 后端代码评审清单
|
||
|
||
- **功能**:列出 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 */` 这种字段取值说明不算违规。
|