Files
lpt-be/.agents/roles/data-access.md
T

66 lines
6.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 数据访问层编码规范
- **功能**:规定数据访问层的写法与查询/取锁形态,避免手写 SQL、按字符串 key 取值、逐行查询和并发死锁。
- **何时用**:编写 Mapper 或查询逻辑、需要聚合或联表、写列表/详情/导出类接口、新增取锁逻辑、评审数据访问代码时。
## 编码规范
### 数据访问层
- **优先使用纯 MyBatis-Plus Java API**(`Wrappers.<T>lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL
- 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段
- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值**
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错
- 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法
- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallMapper.sumTaskDuration` → `dto/recall/TaskRecallDuration`
- 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `<resultMap>`
- **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加
- 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewFeedbackIntegrationTest`、`AiUsageAggregationIntegrationTest`)
- 反向约束:`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` 就走。两个理由:一是字段清不空——本仓
未显式配 `update-strategy`,MyBatis-Plus 默认跳过 null 字段,用户点了「清空备注」库里的值还在;二是语义依赖全局配置,
那个默认值改一次,全库的 patch 更新行为一起变且不报错。要局部更新先分清是哪种,三选一:
- **整对象替换**:先查到完整实体、改完字段、`updateById`——适合「表单提交整张卡」的场景。
- **`LambdaUpdateWrapper.set(...)`**:需要显式写 null(真清空)时用,意图写在 `.set(field, null)` 上。
- **`XxxPatch` DTO**:由请求对象表达「哪些字段有值才改」,与 `api-response.md` 的入参规范对齐。
现状 17 处 patch 写法(全仓 27 处 `updateById`,其余是整对象更新),例 `ReviewServiceImpl#updateReport`、`ReviewServiceImpl#submitFeedback`。
- **实体统一继承 `BaseEntity`**:`created_by` / `created_time` / `last_modified_by` / `last_modified_time` / `device_info` / `deleted`
由 `config/AutoTableField` 自动填充与 `@TableLogic` 软删除接管。不继承就少审计列,`created_by` 缺失还会让租户拦截器无列可加。
现状:`entity/` 下 19 个业务实体全部继承(`entity/` 的第 20 个文件是 `BaseEntity` 本身)。
- **SQL 只出现在 Mapper**:service 里不拼 SQL 字符串(当前 3 处 `.last("LIMIT " + n)` 属存量违规,见 `code-review-checklist.md`);
需要分页/限量时用参数化占位符,或用 `Page` / `IPage`,再不行下沉到 mapper。