global-coding-governance/java-coding-style/references/05-工程分层与数据访问.md

工程分层与数据访问

分层与依赖

• 必须：遵循项目既有模块边界和依赖方向；领域层不得反向依赖 Web、ORM 或具体基础设施实现。
• 必须：Controller/Endpoint 负责协议适配与边界校验，不承载核心业务编排。
• 必须：持久化对象、领域对象和 API DTO 的转换边界明确；不得把 ORM 实体直接作为外部契约。
• 推荐：使用构造器注入表达必需依赖并支持测试；字段注入仅在项目框架约束明确时使用。
• 推荐：工具类无状态、职责单一且构造器不可见；不要创建混杂业务逻辑的通用 Utils。
• 必须：循环依赖表示边界问题，不以延迟注入作为默认解决方案。

数据访问

• 必须：禁止字符串拼接用户输入生成 SQL；MyBatis 默认使用 #{}，${} 只允许经过严格白名单的元数据。
• 必须：明确查询列，不使用 SELECT * 作为生产查询默认写法。
• 必须：分页总数为零时避免继续执行无意义的数据查询；限制最大页大小和排序字段。
• 必须：批量查询、写入和 IN 参数有明确上限并按数据库能力分批。
• 必须：避免循环中逐条远程或数据库调用；检查 N+1 查询和不受控懒加载。
• 必须：更新语句只更新预期字段；乐观锁、版本号或条件更新必须检查受影响行数。
• 必须：事务内查询和更新基于明确隔离假设；不能用应用层 if 代替数据库唯一约束或原子条件。
• 推荐：索引设计与真实查询条件、排序和基数一致；新增查询必须评估执行计划或沿用已验证索引。
• 推荐：数据库约束与应用校验共同保护核心不变量，不机械套用“禁止所有外键”；服从项目的数据治理策略。

Spring、Jakarta 与 ORM

• 必须：Bean Validation 放在真实入口并确保级联校验生效；内部调用仍需保护领域不变量。
• 必须：@Transactional、缓存、异步和权限注解必须考虑代理边界、自调用、方法可见性和异常回滚语义。
• 必须：JPA 实体的 equals/hashCode 不得依赖会变化的数据库生成标识造成集合异常。
• 推荐：默认避免 Open Session in View 带来的隐式查询；在服务边界显式获取所需数据。
• 必须：MyBatis/JPA 映射字段、枚举、时区和 null 语义必须有测试，不能仅凭同名假设自动映射正确。

构建与依赖

• 必须：新增或升级依赖前确认项目 BOM、dependency management、版本锁定和许可证/安全要求。
• 必须：生产发布不依赖不可复现的 SNAPSHOT 或动态版本，除非项目流程明确批准。
• 必须：依赖变更检查传递依赖、冲突、打包体积和运行时兼容；不要只确认“能编译”。
• 推荐：优先使用 JDK 与项目已有库；为一个简单方法引入大型依赖通常不合理。
• 必须：生成代码和资源遵循构建目录约定，不手改会被生成器覆盖的文件。