docs: 补充查询次数与加锁形态规则

This commit is contained in:
2026-11-21 16:54:13 +08:00
parent 9c3e22680d
commit e96cb3e3d3
2 changed files with 51 additions and 4 deletions
+16
View File
@@ -47,3 +47,19 @@ Javadoc 描述的方法名、参数、返回跟下面那个方法对不上就是
新增英文注释、或把中文提示改成英文都算违规:这个项目的用户文案与注释都是中文,混语种会在同一屏里跳出来。 新增英文注释、或把中文提示改成英文都算违规:这个项目的用户文案与注释都是中文,混语种会在同一屏里跳出来。
用户文案还要求口语化(见 `api-response.md`)。历史情况(2026-11-19 前)是混排:`ReviewRecallController:21`、`LoginResult:21` 这类成句英文注释要翻成中文; 用户文案还要求口语化(见 `api-response.md`)。历史情况(2026-11-19 前)是混排:`ReviewRecallController:21`、`LoginResult:21` 这类成句英文注释要翻成中文;
`/** REPORT | FRAGMENT */` 这种字段取值说明不算违规。 `/** 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`,
并用两个并发请求验证。
+35 -4
View File
@@ -1,7 +1,7 @@
# 数据访问层编码规范 # 数据访问层编码规范
- **功能**:规定数据访问层的实现方式,避免手写 SQL 与字符串 key 取值带来的跨库隐患。 - **功能**:规定数据访问层的写法与查询/取锁形态,避免手写 SQL、按字符串 key 取值、逐行查询和并发死锁。
- **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、评审数据访问代码时。 - **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、写列表/详情/导出类接口、新增取锁逻辑、评审数据访问代码时。
## 编码规范 ## 编码规范
@@ -12,12 +12,43 @@
- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值** - **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值**
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错 - MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错
- 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法 - 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法
- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml` - **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallMapper.sumTaskDuration` → `dto/recall/TaskRecallDuration`
- 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `<resultMap>` - 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `<resultMap>`
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewFeedbackIntegrationTest`、`AiUsageAggregationIntegrationTest`)
- 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
## 查询次数
- **一次请求的 SQL 条数必须可数,且与行数、子记录数无关。** 库在远端,单程 40–80ms,条数直接等于延迟:
一页 20 行、每行再查 3 次就是 60 次往返。禁止在 `for` / `stream.map` / `forEach` 里调 mapper(N+1)——
先把需要的 id/编号收集起来,一条 `IN` 取齐再在内存里装饰(范例 `ReviewFeedService.mergeAndConvert`、
`RecallDetailAssembler.facts`)。
- **列表只查列表要用的数据。** DTO 里没有的字段不要顺手查:`RecallSummary` 不含 `requests`,列表就不查 AI 任务;
文档类数据(`document_json`)只要分页行里已经带出来,就不要再按主键回表查一遍。
- **分页只发一次 COUNT。** `selectPage` 自带 COUNT,不要再对同一个 wrapper 调 `selectCount`;不需要总数的列表用
`new Page<>(pageNum, pageSize, false)` 或 `selectList`。
- **聚合下推 SQL,并且带过滤条件。** 计数/求和/分组用 `GROUP BY` + 显式结果类(`ReviewStatsService.fillReviewTaskStats` 的写法),
不要在 Java 里遍历全表累加;聚合语句必须带 `IN (...)`、时间窗等条件,禁止每次请求整表 `GROUP BY`。
- **同一份数据一次请求只查一次。** 同一批 id 的任务名、学习预期、待更新导图被查两遍就合并;命中集合算完再一条
`UPDATE ... WHERE id IN (...)`,不要逐行 `updateById`。
- **验证**:改完列表/详情/导出接口,用 `logging.level.com.guo.learningprogresstracker.mapper=DEBUG` 数单次请求的
`==> Preparing:` 条数,再换一个页大小复核条数不变。2026-11-21 回忆列表就是按这条从 47 条降到 7 条
([记录](../notes/implemented/bug-fix/2026-11-21-recall-owner-lock-deadlock-and-read-batching.md))。
## 加锁形态
- **取同一把行锁必须是单一步骤的排他锁。** 禁止 `INSERT IGNORE`(行已存在时只拿共享锁 S)紧跟 `SELECT ... FOR UPDATE`:
两个并发事务各持 S 锁互等 X 锁,InnoDB 直接判定死锁并回滚其一,接口表现为随机 500。
- **两种允许的写法**:
- 锁行一定存在 → 直接 `SELECT ... WHERE <pk> = ? FOR UPDATE`;
- 锁行可能不存在 → 先 `INSERT INTO ... VALUES (...) ON DUPLICATE KEY UPDATE <pk> = <pk>`(命中已有行时这是排他锁),
再 `SELECT ... FOR UPDATE`。参考 `ReviewRecallMapper.ensureOwnerLock` / `lockUser`。
- **锁内只做必要的语句。** 读路径如果会 `reconcile`/抹除数据,就必须和写入串行;此时锁的持有时间等于该事务里的全部语句数,
按上面的「查询次数」把事务压到个位数。
- **验证**:新增或改动取锁逻辑后,用两个并发请求(或两个 JDBC 事务)跑同一条路径,确认没有再出现
`Deadlock found when trying to get lock`;单线程点一遍不算验证。
## 写入形态 ## 写入形态
- **禁 patch 实体式更新**:不要 `new XxxEntity()` + 只 `set` 变化字段 + `updateById` 就走。两个理由:一是字段清不空——本仓 - **禁 patch 实体式更新**:不要 `new XxxEntity()` + 只 `set` 变化字段 + `updateById` 就走。两个理由:一是字段清不空——本仓