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

6.7 KiB
Raw Blame History

数据访问层编码规范

  • 功能:规定数据访问层的写法与查询/取锁形态,避免手写 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 条 (记录)。

加锁形态

  • 取同一把行锁必须是单一步骤的排他锁。 禁止 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。