3.8 KiB
3.8 KiB
数据访问层编码规范
- 功能:规定数据访问层的实现方式,避免手写 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 方法
- MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:
Wrapper表达不了的查询(SUM/GROUP BY/多表JOIN)收敛到 Mapper 层,用自定义方法 + 显式结果类(dto/下的类或实体),参考ReviewRecallRecordMapper.sumReviewDurationByTask→dto/TaskReviewDuration+resources/mapper/ReviewRecallRecordMapper.xml- 结果映射:列名与属性能对应时可用自动映射,但
map-underscore-to-camel-case必须在application.yml里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式<resultMap> - 自定义 SQL 不会被
@TableLogic自动追加逻辑删除条件,必须显式写deleted = 0;租户条件created_by = ?仍由TenantLineInnerInterceptor自动追加 - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考
ReviewDurationIntegrationTest) - 反向约束:
Wrapper能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串
- 结果映射:列名与属性能对应时可用自动映射,但
写入形态
- 禁 patch 实体式更新:不要
new XxxEntity()+ 只set变化字段 +updateById就走。两个理由:一是字段清不空——本仓 未显式配update-strategy,MyBatis-Plus 默认跳过 null 字段,用户点了「清空备注」库里的值还在;二是语义依赖全局配置, 那个默认值改一次,全库的 patch 更新行为一起变且不报错。要局部更新先分清是哪种,三选一:- 整对象替换:先查到完整实体、改完字段、
updateById——适合「表单提交整张卡」的场景。 LambdaUpdateWrapper.set(...):需要显式写 null(真清空)时用,意图写在.set(field, null)上。XxxPatchDTO:由请求对象表达「哪些字段有值才改」,与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。