DMS 代码走查规范

本文档用于 人工走查 / Code Review / AI 辅助审查 时的检查清单，与《DMS 代码编写规范》配套使用。走查时以《DMS 代码编写规范》为强制依据，本清单侧重 可操作的检查项与常见坏味道。

1. 适用范围

与《DMS 代码编写规范》第 1 节一致，适用于 DMS 全部 Java 服务与模块（wpglb-dms-admin、wpglb-dms-service、wpglb-dms-lms-service、wpglb-dms-driver-service、wpglb-dms-exporter-service、wpglb-dms-task、wpglb-dms-security-gateway、wpglb-dms-service-api、wpglb-dms-commons、wpglb-dms-tool 等）。

2. 走查方式建议

方式 说明
按变更范围 优先审查本次 PR/分支改动的文件；若改动调用链较深，沿调用链向上/向下各追 1～2 层。
按分层 Controller → Service → Mapper/XML；涉及 Feign/消息则补查 Client 与消费端。
按风险 资金、状态变更、批量、导出、定时任务、分布式锁等路径加重审查。

3. 控制台与日志（强制项对齐：日志规范）

检查项 说明
禁止 System.out / System.err 业务代码中不得用于输出调试信息；应使用 Slf4j。
禁止 printStackTrace() 异常应通过 log.error("...", e) 等记录，便于采集与检索。
禁止打印敏感信息 密码、token、完整证件号等不得写入日志。
关键链路日志 业务单号、耗时、结果、异常分支应有可追溯日志。

辅助检索（示例）：

System\.out|System\.err|printStackTrace

4. 数据访问与性能（强制项对齐：禁止循环读写库）

检查项 说明
循环查询（N+1） 禁止在 for/while/流式单次迭代中调用 getById、selectOne、list（按单键反复查）等；应改为批量查询、IN、关联查询或先收集 ID 再一次性查询后内存映射。
循环写入 禁止在循环中单条 insert/update/delete；应批量 SQL 或 MyBatis-Plus 批量接口，并控制分批大小与事务。
分页与动态条件 分页查询须符合项目对 DynamicConditionUtil 等统一转换的要求；Controller 不堆复杂条件拼装（见编写规范第 7 节）。

辅助检索思路：

  • 在 Service 实现中搜索 for (、while (，检查循环体内是否出现 mapper.、Service. 的单条查询/写入。
  • 关注 getById、selectById、list( 出现在循环体内的场景。

5. 资源与内存风险

检查项 说明
流与连接 InputStream/OutputStream/Reader/Writer 等优先 try-with-resources 或在 finally 中关闭；异常路径也要能释放。
大对象与导出 大批量导出时注意是否全量加载到内存；是否分页/流式；ByteArrayOutputStream 等与数据量相关的上限是否在可接受范围。
静态集合 避免静态可变 Map/List 无限增长且无淘汰策略；避免长生命周期引用持有大集合。
线程安全 SimpleDateFormat 非线程安全，禁止多线程共享同一实例；静态日期格式类字段需谨慎。

6. 线程与异步（强制项对齐）

检查项 说明
业务模块禁止私自 new ThreadPoolExecutor、Executors.* 创建线程池。
禁止直接 new Thread 跑业务逻辑。
异步须走平台统一线程池或调度框架（以项目实际配置为准）。

7. 分布式锁（若涉及）

检查项 说明
仅使用 @RedissonLock 或 RedissonLockClient，禁止第三种实现。
锁必须设置自动释放时间（leaseTime），禁止无过期锁。
锁 Key 粒度细化到业务主键；前缀复用 RedisConstants 等约定。
try/finally 释放；锁内逻辑短事务、无长耗时远程调用。

8. 分层与接口契约

检查项 说明
Controller 参数校验、鉴权（如需要）、调用 Service、返回 R<T>；不写核心业务与复杂 SQL 条件。
Service 业务逻辑、事务边界；复杂查询条件封装方法，避免复制粘贴。
对外接口 入参出参优先 DTO/VO/Query，避免直接暴露 Entity（特殊情况需评审）。
返回类型 R<T> 泛型尽量写全，避免无意义的裸 R。
错误码 业务异常使用 ServiceException + 域内 DmsErrorEnum（或各项目约定枚举），避免魔法字符串。

9. 常见代码坏味道（快速对照）

类型 示例或特征
未使用 import / 死代码 未引用的类、未使用的字段（如仅声明的 SimpleDateFormat）。
方法/接口命名误导 如方法名 remove 实际为“修改状态”。
未使用的方法参数 如分页接口中实体参数未参与条件构建，易误导维护。
重复逻辑可合并 如仅两字段比较却使用双重循环。
业务日志操作类型错误 如“修改”场景仍传 CREATE 类型常量。
吞异常 catch 空实现、printStackTrace 后 return null 且无日志。
Feign/远程 null 入参、与 HTTP 接口不一致的“无数据”语义（有的 R.fail，有的 R.data(null)）。
工具类依赖请求上下文 如仅从 RequestContextHolder 取请求；在非 Web 线程调用会 NPE。

10. 走查输出建议格式

走查结束后建议按以下结构记录（便于跟踪与复盘）：

  1. 范围：模块 / 包 / 主要类或接口。
  2. 必须修复：违反编写规范强制项、安全与数据一致性风险。
  3. 建议优化：性能、可读性、命名、重复代码。
  4. 待确认：依赖配置、产品规则、与前端/网关约定。

11. 关联文档

  • 《DMS 代码编写规范》（项目内 DMS-代码编写规范.md 或 .cursor/rules 中对应规则）
  • 《DMS-AI生成代码约束清单》（若存在，用于生成代码前的约束）

修订说明

  • 本文档随项目规范迭代更新；与《DMS 代码编写规范》冲突时，以编写规范为准。
作者：陆飞  创建时间：2026-04-10 16:34
最后编辑：陆飞  更新时间：2026-04-17 09:34